brick/skills/brick-sast/SKILL.md

---
name: brick-sast
description: Build an interactive codebase architecture visualization and JSON dependency graph with Brick SAST to inspect how a repository is structurally composed. Map files, directories, classes, functions, calls, imports, inheritance, cycles, hubs, and unresolved references; compare structural regressions; or overlay existing Fold findings while preserving provenance. Verify material graph claims in source. Do not use as proof of security, correctness, or maintainability.
metadata:
  tags: brick, static-analysis, software-architecture, dependency-graph, code-visualization, fold
---

# Brick SAST

Use Brick to turn a repository into an evidence-aware architecture graph, then verify important structural claims against source. Brick is an architecture inspection aid, not a vulnerability detector or a proof that the design is good.

## Analysis contract

Brick emits a stable JSON graph and an interactive HTML visualization. It currently recognizes Rust, Dart, Python, C/C++, JavaScript/TypeScript,
Swift, and a focused P4_16 lexical slice. Treat the graph as a layered static
model:

- nodes represent repositories, directories, files, classes, functions, unresolved external symbols, and imported Fold findings;
- edges represent containment, definitions, calls, imports, inheritance, and finding overlays;
- every relationship should retain its lane, backend, confidence label, and provenance;
- health metrics summarize observable graph properties; they do not measure architecture quality in the abstract.

Preserve these evidence boundaries:

- Syntactic edges are navigation candidates until confirmed in source.
- External nodes mean Brick could not resolve a target locally; they are not defects by themselves.
- Fold findings retain the confidence and backend reported by Fold. Source findings categorized as `proved`, `latent`, or `concrete-witness` are Symbolic only within Fold's bounded model; other source findings and binary findings are Imported. Never universalize a Fold result or relabel binary evidence as heuristic proof.
- Confidence labels from different producers are categories, not calibrated probabilities.
- Missing files, unsupported syntax, malformed reports, and frontend failures reduce coverage. Never describe incomplete coverage as a clean result.
- P4 nodes and relationships retain exact `p4.kind` and `p4.relation`
  attributes. The lexical P4 slice is not p4c, P4_14 support, architecture type
  checking, or formal verification.
- Qualified p4c diagnostic envelopes produce Imported findings. They do not
  prove a property. Treat P4 symbolic adapters as unavailable unless the model
  itself records a named tool/version, explicit bounds, and real report
  provenance.
- Read parser/apply cycles, unreachable states, and unresolved P4 dependencies
  from `metrics.p4`. Repeated applies are legal unless canonical directed edges
  form an SCC; every unreachable-state warning is a structural observation, not
  a proof of runtime unreachability.
- Report the health-score components and raw counts with the aggregate score. A single score can hide lost files, symbols, or edges.

## Workflow

### 1. Set the question

Choose one primary mode before running Brick:

- snapshot: explain the current composition and dependency shape;
- visualization: create an explorable artifact for a human reviewer;
- comparison: identify structural changes between two revisions or artifacts;
- gate: enforce thresholds already approved by the project;
- evidence overlay: correlate architecture with an existing Fold report;
- query service: expose bounded read-only graph inspection to an MCP client.

Do not introduce new architectural policy merely because a metric is available.

### 2. Confirm the installed interface

Run:

    brick --version
    brick build --help

When the binary is unavailable but the Brick repository is present, use:

    cargo run --manifest-path /path/to/brick/Cargo.toml -- build --help

Use the actual help output as the command contract. Do not infer flags from this document if the installed version differs.

### 3. Produce durable artifacts

Write outputs outside the analyzed source tree when practical so generated files do not enter the graph:

    brick build /path/to/repository \
      --json build/brick/architecture.json \
      --html build/brick/architecture.html

Overlay one or more existing Fold reports only when the task asks for security evidence or correlation:

    brick build /path/to/repository \
      --fold-report build/fold/report.json \
      --json build/brick/architecture.json \
      --html build/brick/architecture.html

Do not run Fold solely because Brick supports its output. Use the Fold-SAST skill when a security scan is actually requested.

### 4. Summarize deterministically

Run the bundled helper from this skill directory:

    python3 scripts/architecture_summary.py build/brick/architecture.json

The helper reports counts, dependency cycles, hubs, unresolved targets, evidence lanes, and Fold overlays without changing the graph. Read [references/architecture-review.md](references/architecture-review.md) when comparing artifacts or interpreting metrics.

For an MCP client that needs bounded interactive inspection of an existing
artifact, start the read-only stdio server:

    brick mcp build/brick/architecture.json

Use `brick_impact`, `brick_cycles`, `brick_bridges`, and `brick_evidence` only
as views over the validated JSON. Preserve their query/building schema versions
and do not treat SCC or weak-bridge observations as runtime or verifier proof.

### 5. Hydrate material claims with source

For each finding that may influence a design decision:

1. Record the relevant node and edge IDs and their provenance.
2. Open the source locations on both sides of the relationship.
3. Distinguish observed structure from inferred intent.
4. State coverage or resolution limitations.
5. Recommend a change only when source evidence supports it.

Examples of necessary restraint:

- A cyclic component can be intentional recursion or a small local implementation loop.
- High fan-in can indicate a stable abstraction rather than harmful coupling.
- High fan-out can be an orchestrator's legitimate responsibility.
- An unresolved call can be a standard-library, framework, generated, dynamic, or foreign-function target.

### 6. Report findings first

Lead with verified architectural risks, ordered by impact. For each finding include:

- the structural observation and affected symbols;
- graph evidence and source evidence;
- why it matters in this repository;
- confidence and coverage limitations;
- the smallest supported remediation or investigation step.

Then provide artifact paths, graph coverage, health components, and notable healthy structure. If no material issue is verified, say so and describe what was inspected rather than claiming the architecture is sound.

## Structural signals

| Signal | Useful question | Required caution |
| --- | --- | --- |
| Cyclic SCC | Which dependency loops cross responsibilities? | Confirm direction and intent in source; recursion may be expected. |
| High fan-out | Which symbols coordinate many dependencies? | Generated code and dispatchers can dominate counts. |
| High fan-in | Which symbols are architectural load-bearing points? | Popular stable APIs are not automatically fragile. |
| Unresolved target | Where is dependency resolution incomplete? | External and dynamic calls are expected in many ecosystems. |
| Isolated node | Which analyzed symbols lack modeled relationships? | Parser coverage can create false isolation. |
| Cross-directory edge | Where do package or layer boundaries interact? | Directory layout is not necessarily the intended architecture. |
| Fold overlay | Which security findings touch structural hubs? | Preserve Fold's original evidence and confidence. |

## Comparison and gates

Compare stable node and edge identities, raw counts, and evidence coverage before comparing health scores. A score improvement is not meaningful if the newer artifact silently analyzed fewer files or relationships.

Use an explicit project-owned gate only after its thresholds and exclusions are reviewed:

    brick check build/brick/architecture.json --min-score 70

For compatible schema-v4 artifacts, request an inspectable stable-ID diff and
optionally add project-owned absolute-count limits:

    brick check build/brick/current.json --min-score 70 \
      --baseline build/brick/baseline.json \
      --diff-json build/brick/structural-diff.json \
      --max-removed-nodes 0

Versioned repository-relative dependency boundaries can use the same gate:

    brick check build/brick/current.json --min-score 70 \
      --policy architecture-policy.json \
      --policy-result-json build/brick/policy-result.json

The values and policy above are only examples; replace them with approved
project-owned thresholds and boundaries. Do not convert exploratory
observations into CI failures without user authorization. Keep the JSON
artifacts that triggered a failure so the result is reproducible.

## Companion skills

- Use Fold-SAST for bounded symbolic security analysis and Fold report production.
- Use fp-check to validate a suspected security finding.
- Use YAMS to locate definitions, call sites, and surrounding architectural context in an indexed repository.
- Use a language-specific skill when parser behavior or framework conventions materially affect interpretation.