137 lines
5.6 KiB
Markdown
137 lines
5.6 KiB
Markdown
# 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.
|