Usage

build

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

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

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 for the envelope contract and upstream fixture provenance.

The Tree-sitter P4 pilot

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 for the pin, measured result, limits, and the decision not to make it the default.

render

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

check

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:

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.

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

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.

mcp

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.

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.

5.6 KiB Raw Permalink Blame History