Design & Architecture¶

G.U.A.R.D. operates as a verification gate that acts on a version control repository. By linking abstract norms to concrete file paths and code symbols (anchors), it ensures that compliance requirements remain traceable and actively monitored.

System Architecture¶

The core verification workflow consists of three primary stages:

flowchart TD
    Registry[Compliance Registry YAML] --> Parser[Registry Parser]
    Parser --> Validator[Anchor Symbol Validator]
    Git[Git Diff Engine] --> HunkFilter[Hunk Anchor Filter]

    Source[Source Code Repository] --> Validator
    Source --> Git

    Validator --> Evaluator[Audit Gate Evaluator]
    HunkFilter --> Evaluator

    Evaluator --> Report[JSON/JUNIT Compliance Report]

1. Registry Parser: Loads the configuration YAML, validating the defined categories, norms, and code references.
2. Anchor Symbol Validator: Inspects the current state of files in the workspace to verify that each referenced symbol (anchor) actually exists. If a symbol is missing, the gate triggers a failure.
3. Hunk Anchor Filter (Git Engine): Compares the repository's HEAD against a base commit (baseSha). If a registered file was modified, it extracts the raw git diff hunks and checks if the modification overlaps with the specific lines containing the anchor symbol.

Registry Schema Reference¶

The compliance registry is defined in a YAML file (usually compliance-registry.yaml). It uses the following structure:

categories:
  - id: ISO-27001-A.5
    name: Information security policies
    norms:
      - id: ISM-001
        title: Protect clinical data rendering fixtures from accidental drift.
        # Single reference configuration
        code_ref:
          file: mock-epr/src/main.ts
          anchor: patientRecord
          kind: variable

      - id: ISM-002
        title: Keep the patient summary generated from a typed source of truth.
        # Multiple references configuration
        code_refs:
          - file: mock-epr-python/main.py
            anchor: renderRecordCard
            kind: function
          - file: mock-epr-python/extra_components.py
            anchor: renderRecordCardV2
            kind: function

Schema Parameters¶

Code Reference Object¶

Each code reference defines exactly where the compliance control is implemented:

• file: The repository-relative path to the source file (e.g. src/auth.ts).
• anchor: The name of the code symbol representing the control (e.g. hashPassword).
• kind: The type of the symbol. Valid types include function, variable, class, method, etc. (used by the parser to search for boundaries).

Engine Optimization Features¶

G.U.A.R.D. includes performance optimizations to support execution on large codebases inside containerized environments:

1. Batch Diffing¶

Instead of invoking git diff sequentially for every changed file in the registry, G.U.A.R.D. maps out all modified files that match the registry, then queries Git in a single batch command:

git diff <base-sha> -- <file1> <file2> <file3> ...

2. Line Anchor Verification and Caching (FileCache)¶

To verify if an anchor exists in a file, G.U.A.R.D. parses/scans the file content. When multiple norms reference the same file, the content is stored in a lightweight in-memory cache (FileCache). This avoids repeated filesystem disk read operations.

3. Anchor Hunk Extraction¶

When a file is modified, the compiler maps the changed line numbers in the git diff hunk against the location of the anchor symbol in the target file. If a change occurs outside the scope of the anchor's definition, the status is reported as unchanged, ensuring developers are not flagged for unrelated changes.