# Usage

## build

```bash
cargo run -- build ../fold --json fold.brick.json --html fold.brick.html
cargo run -- build ../yams --exclude site --exclude build \
  --json yams.brick.json --html yams.brick.html
```

`--exclude` drops generated or checked-in output by exact directory component
(repeatable). File and directory symlinks are skipped with repository-relative
diagnostics, which prevents outside-root traversal, cycles and duplicate
aliases. A file with invalid UTF-8 is decoded lossily with a diagnostic; files
with NUL bytes are skipped as binary. `build` prints diagnostic counts, and a
scan that finds no supported source says so.

The HTML loads Cytoscape.js from unpkg by default; pass `--cytoscape-url` for an
internal or vendored copy.

### Layering Fold findings

```bash
cargo run -- build ../fold --fold-report ../fold/build/findings.json \
  --json fold.brick.json --html fold.brick.html
```

A report must be a SARIF log or a Fold findings report; anything else is an
error. Findings keep Fold's Symbolic lane only when the report names Fold as its
producer (`tool.name` / `tool.driver.name`); other producers' findings are
Imported, never Symbolic. Findings without a file location are diagnosed, and
SARIF `file://` URIs are decoded before matching.

Paths are normalized lexically across `/`, `\`, `.` and `..` before exact
repository-relative matching; a path with `..` that exists in this checkout
follows the filesystem instead, so `link/..` resolves through the symlink.
Absolute paths are accepted only beneath the scan root (including filesystem
aliases whose canonical targets are beneath it); leading traversal and
unrelated suffix paths stay diagnostics. Findings for excluded, generated or
missing files are never attached to a neighbouring file.

### Layering p4c diagnostics

```bash
cargo run -- build tests/fixtures/p4c \
  --p4c-report tests/fixtures/p4c/reports/p4c-1.2.5.16-duplicate-state.json \
  --json p4c.brick.json --html p4c.brick.html
```

The bridge accepts a qualified p4c v1.2.5.16 regression diagnostic envelope. It
is tool/version/mode-specific, fails closed, and its evidence is Imported, not
Symbolic. See [P4 evidence](architecture/p4-evidence.md) for the envelope
contract and upstream fixture provenance.

### The Tree-sitter P4 pilot

```bash
cargo run -- setup --json
cargo run --features tree-sitter-p4-pilot -- setup --require-tree-sitter-p4-pilot
cargo run --features tree-sitter-p4-pilot -- build tests/fixtures/p4_tree_sitter \
  --p4-frontend tree-sitter-pilot --json p4-pilot.brick.json --html p4-pilot.brick.html
```

`setup` reports whether the compiled binary can initialize the pilot; the
`--require-...` form fails closed, for install and CI steps. The pilot is
default-disabled and augments the lexical pass, which still runs: its matches
stay Syntactic and name-index resolution stays Heuristic. See
[the pilot study](research/tree-sitter-p4-pilot.md) for the pin, measured
result, limits, and the decision not to make it the default.

## render

```bash
cargo run -- render fold.brick.json --html fold.brick.html
```

## check

```bash
cargo run -- check fold.brick.json --min-score 70 --max-cycles 5
```

`check` recomputes metrics from the graph (stored metrics are never trusted)
and fails a model with no scanned source.

Compare against a compatible baseline by stable IDs:

```bash
cargo run -- check current.brick.json --min-score 70 \
  --baseline baseline.brick.json --diff-json structural-diff.json \
  --max-removed-nodes 0 --max-changed-edges 5
```

Diff gates are unlimited unless set. Models with different schemas, roots,
repository identities, exclusions or P4 frontends are rejected by default; for
corresponding checkouts, `--allow-root-relocation` asserts root equivalence. It
relaxes only the root check, works with saved artifacts, and records both roots
and the policy in diff schema 2. Repository display-name and imported
provenance changes stay visible. See [structural diff](architecture/structural-diff.md).

Apply a versioned repository-relative dependency policy through the same gate:

```bash
cargo run -- check current.brick.json --min-score 70 \
  --policy architecture-policy.json --policy-result-json policy-result.json
```

Unknown policy keys and kinds, and scope mismatches, fail closed. Matched edges
keep their complete evidence. See [policy](architecture/policy.md).

## mcp

```bash
cargo run -- mcp current.brick.json
```

A read-only MCP 2025-06-18 stdio server over a validated model. Its six tools
cover dependency/dependent impact, SCC cycles, weak-graph bridges, complete
node/edge evidence inspection, and caller status: `brick_callers` reports
whether a function is `resolved`, `unknown` (with the reasons callers may
exist) or `unreferenced`, and `brick_uncalled` lists unreferenced functions per
language. Unreferenced is a review candidate, never proof of dead code. The
tools never scan, mutate or render. See [MCP](architecture/mcp.md).

## What the model contains

- Repository, directory, file, class, function, external-dependency and Fold
  finding nodes; contains, defines, calls, imports, inherits and flags edges.
- Deterministically ordered per-edge evidence: lane, backend, producer-local
  confidence, provenance.
- SCC cycle counts, unresolved references, isolation, fan-in/fan-out, per-language
  call-site coverage (`metrics.resolution`) and the experimental structural-health
  composite.
- For P4_16: headers, structs, parsers, controls, tables, actions, states,
  includes, parser transitions, table apply calls and scoped action calls, with
  parser-state and control/apply cycle, unreachable-state and unresolved metrics
  that are observations, not verifier proof.