From d88238c986f0644a76b51caf6c4e64b0118882f8 Mon Sep 17 00:00:00 2001 From: trvon Date: Thu, 24 Sep 2026 20:42:00 -0600 Subject: [PATCH] docs: trim the README and split usage, resolution and development out The README had grown to 254 lines covering an overview, every command, the Fold/SARIF and p4c import contracts, the P4 pilot, per-language resolution rules, limits, schema history, development and the agent skill. It is now a 70-line overview (what Brick is, evidence lanes, languages, quick start, commands, limits, links), and the rest lives in: - docs/usage.md: every command (build, render, check with diff and policy gates, mcp, setup), Fold/SARIF and p4c layering, the P4 pilot, and what the model contains. - docs/resolution.md: per-language name resolution as the code now implements it, what is not handled, P4 limits, the regression corpus and schema version 4. - docs/development.md: build and test commands, the quality gate, the toolchain pin, and the brick-sast skill. Architecture docs are linked, not repeated. "What v0.1 provides" and the milestone note are folded into usage.md and the roadmap pointer. Every relative link and anchor resolves. --- README.md | 296 +++++++++----------------------------------- docs/development.md | 30 +++++ docs/resolution.md | 82 ++++++++++++ docs/usage.md | 134 ++++++++++++++++++++ 4 files changed, 302 insertions(+), 240 deletions(-) create mode 100644 docs/development.md create mode 100644 docs/resolution.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index ee9367b..ff59b52 100644 --- a/README.md +++ b/README.md @@ -1,254 +1,70 @@ # Brick -Brick builds an evidence-aware visual representation of a codebase. Directories -become compounds, files become rooms, classes/functions become structural -elements, and dependency edges show calls, imports, and inheritance. The same -model is emitted as versioned JSON for other tools, including a future Fold -integration. +Brick turns a repository into an evidence-aware map of its structure. +Directories become compounds, files become rooms, classes and functions become +elements, and edges show calls, imports and inheritance. The same model is +written as versioned JSON for other tools and rendered as an interactive HTML +graph. -The default extractor uses pinned Tree-sitter grammars for Rust, Dart, C -(`.c`), C++ (including headers), JavaScript/JSX, and TypeScript/TSX. Python and Swift retain the lexical preview; -P4_16 retains its separate lexical and optional pilot paths. Declarations are -Syntactic evidence. Calls, imports, and inheritance retain Heuristic target -resolution with backend, confidence, and source location, independently of -imported symbolic evidence. +Every edge keeps its evidence: lane, backend, confidence and source location. +Declarations are **Syntactic**; call, import and inheritance targets are +**Heuristic**; findings from Fold or p4c are **Imported** (Fold's own proofs keep +their **Symbolic** lane). Nothing is promoted to a stronger lane than its +evidence supports, and every unresolved call records why. + +## Languages + +| Language | Frontend | +| --- | --- | +| Rust, Dart, C (`.c`), C++ (with headers), JavaScript/JSX, TypeScript/TSX | pinned Tree-sitter grammars | +| Python, Swift | lexical preview | +| P4_16 | lexical preview; optional Tree-sitter pilot | + +How names resolve in each, and where they do not, is in +[docs/resolution.md](docs/resolution.md). Read the graph with its reported +call-site coverage in mind: on a large C++ repository only a minority of call +sites resolve. ## Quick start - cargo run -- build ../fold --json fold.brick.json --html fold.brick.html +```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 generated or checked-in output by exact directory component (repeatable): +Open the HTML in a browser. `build` prints diagnostic counts, and a scan that +finds no supported source says so. - cargo run -- build ../yams --exclude site --exclude build \ - --json yams.brick.json --html yams.brick.html +## Commands -Scans skip file and directory symlinks with repository-relative diagnostics. -This prevents outside-root traversal, cycles, and duplicate aliases. +| Command | What it does | +| --- | --- | +| `brick build ` | Scan a repository; write JSON and HTML. Can layer Fold/SARIF or p4c findings onto the graph. | +| `brick render ` | Render an existing model to HTML. | +| `brick check ` | Gate on the structural score, cycles, a baseline diff, or a dependency policy. Metrics are recomputed from the graph, never trusted from the file. | +| `brick mcp ` | Serve read-only MCP queries: impact, cycles, bridges, evidence. | +| `brick setup` | Report which optional frontends this binary can initialize. | -Layer Fold findings onto the building: +Full usage, including the import contracts: [docs/usage.md](docs/usage.md). - cargo run -- build ../fold \ - --fold-report ../fold/build/findings.json \ - --json fold.brick.json \ - --html fold.brick.html +## Limits -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. +Brick reads syntax, not compiler output: no type checking, build configuration, +macro expansion, overload resolution or dynamic dispatch. The structural score +is an experimental composite, not proof of correctness, maintainability or +security; use the component metrics and evidence, and do not rank teams or +repositories by the score alone. -Fold artifact paths are normalized lexically across `/`, `\\`, `.`, and `..` -components 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 model's scan root (including existing filesystem -aliases whose canonical targets are beneath that root); leading traversal and unrelated -suffix paths remain diagnostics. Findings for excluded, generated, or genuinely -missing files are never attached to a neighboring source file. +## Documentation -Layer a qualified p4c v1.2.5.16 regression diagnostic envelope onto P4 -structure: - - 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 p4c bridge is tool/version/mode-specific and its evidence is Imported, not -Symbolic. See `docs/architecture/p4-evidence.md` for the envelope contract and -real upstream fixture provenance. - -Detect whether this Brick binary can initialize the pinned Tree-sitter P4 -pilot before selecting it: - - cargo run -- setup --json - cargo run --features tree-sitter-p4-pilot -- \ - setup --require-tree-sitter-p4-pilot - -The versioned setup report distinguishes an unavailable compile-time feature -from a usable parser. The `--require-tree-sitter-p4-pilot` form fails closed, -which makes it suitable for installation and CI setup steps. - -Run the default-disabled Tree-sitter P4 pilot as an augmentation to lexical -extraction: - - 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 - -Tree-sitter matches remain Syntactic and name-index resolution remains -Heuristic. The lexical pass still runs. See -`docs/research/tree-sitter-p4-pilot.md` for the pin, measured result, limits, -and decision not to promote the pilot to the default frontend. - -Render an existing model or enforce an explicit experimental gate: - - cargo run -- render fold.brick.json --html fold.brick.html - cargo run -- check fold.brick.json --min-score 70 --max-cycles 5 - -Compare a compatible baseline by stable IDs while retaining the existing gate: - - 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 explicitly set. Models with different schemas, -roots, repository identities, exclusions, or P4 frontends are rejected by default. -For corresponding checkouts, add `--allow-root-relocation` to explicitly assert -root equivalence. This 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 remain visible. See -`docs/architecture/structural-diff.md` for the versioned diff contract. - -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/kinds and scope mismatches fail closed. Matched edges retain -complete evidence. See `docs/architecture/policy.md`. - -Serve read-only MCP queries over a validated, versioned model: - - cargo run -- mcp current.brick.json - -The four tools cover dependency/dependent impact, SCC cycles, weak-graph -bridges, and complete node/edge evidence inspection. They do not scan, mutate, -or render. See `docs/architecture/mcp.md` for protocol and query semantics. - -Open the generated HTML in a browser. It loads Cytoscape.js from unpkg by -default; an internal or vendored URL can be supplied with --cytoscape-url. - -## What v0.1 provides - -- A deterministic schema for repository, directory, file, class, function, - external dependency, and Fold finding nodes. -- Contains, defines, calls, imports, inherits, and flags edges. -- Deterministically ordered per-edge evidence records retaining lane, backend, - producer-local confidence, and provenance. -- SCC-based cycle counts, unresolved references, isolation, fan-in/fan-out, and - an inspectable experimental structural-health composite. -- An interactive compound graph with layout switching, dependency focus, and - node/edge inspection. -- Fold native findings-json and SARIF ingestion without collapsing backend or - confidence. -- P4_16 headers, structs, parsers, controls, tables, actions, states, includes, - parser transitions, table apply calls, and scoped action calls with explicit - domain attributes. -- A fail-closed p4c v1.2.5.16 diagnostic-envelope bridge that preserves raw - identity and attaches Imported evidence to the narrowest resolvable entity. -- Explicit P4 structural metrics for parser-state and control/apply cycles, - unreachable parser states, and unresolved P4 dependencies without treating - any observation as verifier proof. -- A default-disabled, pinned Tree-sitter P4 pilot that adds parallel Syntactic - declaration evidence and control-scoped table-action relationships without - replacing lexical or imported evidence, plus a versioned setup probe that - detects whether the compiled binary can initialize it. -- Deterministic stable-ID structural diff JSON with complete before/after - evidence and optional count gates integrated into `brick check`. -- Versioned declarative repository-relative dependency policies evaluated by - the same `brick check` gate with complete matched-edge evidence. -- A thin read-only MCP 2025-06-18 stdio surface for impact, cycles, bridges, and - evidence inspection over validated Brick JSON. -- A focused Rust test suite, quality gate, bounded auto-loop, and artifact-based - benchmark runner. - -## Important limits - -Brick extracts syntax, without compiler type checking or build configuration. -Macro expansion, overload resolution, dynamic dispatch, generated code, and -full package/build-system resolution remain outside the default frontend. -Malformed syntax produces diagnostics; recoverable sibling facts remain visible. -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. `check` recomputes metrics from the graph -(stored metrics are never trusted) and fails a model with no scanned source. -Its score is not proof of correctness, maintainability, -or security. Use the component metrics and evidence records; do not rank teams -or repositories by the composite alone. - -Grammar-based resolution respects language, file, declaration ownership, and -lexical namespace. Relative JS/TS and Dart imports resolve against the importing -directory (Dart `package:/` against `lib/`); missing paths never -fall back to unrelated basenames. Explicit JS/TS named/default import bindings, -module-scoped Rust grouped/aliased imports, module-qualified Rust public calls, -and public top-level Dart names from imported libraries can resolve across files -(Dart `show`/`hide` combinators are not modelled). The lexical preview resolves -Python names in the calling file, then in files it imports; Swift names in the -calling file, then by a module-wide unique name (Swift files of one module see -each other without imports). -C++ calls resolve through the include closure: a header prototype pairs with -its definition in another translation unit, lookup walks class (including -in-repository bases) and namespace scopes outward, and `static`/anonymous -definitions stay file-local. Declarations in `#elif`/`#else` branches stay in -the graph (`source.preprocessor-branch: alternative`) but are never call -targets, because Brick does not evaluate conditions; several `using` -directives that nominate different declarations make a call ambiguous. C++ and -Rust member calls resolve only through an explicitly declared receiver type -(parameter, local, field, `this`/`self`, smart pointer, or `Self`-returning -constructor) and carry `source.resolution`. Rust types are identified by their -declaring file, so same-named types in different modules resolve through the -caller's `use` binding or stay ambiguous. Calls inside Rust expression macros (`assert!`, `format!`, -`vec!`, ...) are recovered by re-parsing and carry `source.extraction`. -Every unresolved call edge records `source.unresolved-reason`, and -`metrics.resolution` reports per-language call-site coverage; read the graph -with that coverage in mind (on a large C++ repository only a minority of call -sites resolve). Ambiguous targets stay external. Virtual calls resolve to the -declared type's method only (overrides are not fanned out), and Catch2 -`TEST_CASE` bodies are not yet recognized as functions. Bare package specifiers, tsconfig aliases, Rust -wildcard/block-local binding expansion, Cargo workspace module paths, -`compile_commands.json` include paths, and compiler-grade dispatch need further -adapters. File fan-out remains an observation rather -than proof of semantic coupling. Scope architecture gates to production paths -and verify candidates against source and tests. - -The source-language regression corpus checks exact declarations, owners, and -dependencies across six language strata, including clean-negative files. Its -three-repeat benchmark runs in the quality gate. These labeled cases establish -the covered behaviors, not language-wide accuracy. See -`docs/research/language-correctness.md` for the acceptance evidence and limits. - -P4 extraction is a conservative P4_16 lexical preview, not a p4c frontend. -The optional Tree-sitter pilot does not preprocess macros and rejects all pilot -facts from a file when its parse has error or missing nodes. It is not the -default frontend. Implicit terminal states are modeled only when referenced. -Parser transitions -and control/action calls use scoped lexical resolution; unresolved targets stay -external. P4_14, macro expansion, architecture type checking, compiler IR, and -formal-verifier evidence require separate adapters. P4V, `p4-symbolic`, bf4, -and P4K adapters remain disabled until a real versioned machine-readable result -contract and explicit bounded-model semantics are qualified. - -Schema version 4 stores scan scope (including the selected P4 frontend), -parallel relationship evidence, and a nested `metrics.p4` contract. Version-1 -through version-3 JSON are rejected by CLI consumers rather than guessed; -rebuild old artifacts before rendering or checking them. - -The next serious analyzer milestone should consume compiler/YAMS/Fold graph -facts through adapters while retaining the standalone lexical lane as a fast -preview. See docs/architecture/graph-model.md and docs/ROADMAP.md. - -## Development - - cargo fmt --check - cargo test - cargo clippy --all-targets -- -D warnings - ./scripts/quality-gate.sh - python3 tests/benchmarks/runner.py self-test - -Repository workflow is in AGENTS.md and docs/prompts. - -Brick pins `nightly-2026-05-28` in `rust-toolchain.toml`, matching Fold's Rust -analyzer. Rustup selects it automatically for Cargo, rustfmt, and Clippy commands -run inside this repository. - -## Agent skill - -The evidence-aware architecture review workflow lives in -`skills/brick-sast/`. It includes a deterministic JSON summary helper and a -review reference that keeps graph observations separate from source-verified -architectural conclusions. Validate the package with: - - env UV_CACHE_DIR=/private/tmp/brick-uv-cache uv run --with pyyaml \ - python /path/to/skill-creator/scripts/quick_validate.py skills/brick-sast +- [Usage](docs/usage.md): every command, Fold/SARIF and p4c imports, the P4 + pilot, diffs and policies. +- [Resolution](docs/resolution.md): per-language name resolution, limits, + schema versions. +- [Development](docs/development.md): building, tests, the quality gate, the + agent skill. +- Architecture: [graph model](docs/architecture/graph-model.md), + [structural diff](docs/architecture/structural-diff.md), + [policy](docs/architecture/policy.md), [MCP](docs/architecture/mcp.md), + [P4 evidence](docs/architecture/p4-evidence.md); [roadmap](docs/ROADMAP.md). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..0376930 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,30 @@ +# Development + +```bash +cargo fmt --check +cargo test +cargo clippy --all-targets -- -D warnings +./scripts/quality-gate.sh +python3 tests/benchmarks/runner.py self-test +``` + +`scripts/quality-gate.sh` runs formatting, Clippy with warnings as errors, the +tests with and without the P4 pilot feature, the Python unit tests, and the +benchmark self-tests and runs. The repository workflow is in `AGENTS.md` and +`docs/prompts/`. + +Brick pins `nightly-2026-05-28` in `rust-toolchain.toml`, matching Fold's Rust +analyzer; rustup selects it automatically for Cargo, rustfmt and Clippy inside +this repository. + +## Agent skill + +The evidence-aware architecture review workflow lives in `skills/brick-sast/`. +It includes a deterministic JSON summary helper and a review reference that +keeps graph observations separate from source-verified architectural +conclusions. Validate the package with: + +```bash +env UV_CACHE_DIR=/private/tmp/brick-uv-cache uv run --with pyyaml \ + python /path/to/skill-creator/scripts/quick_validate.py skills/brick-sast +``` diff --git a/docs/resolution.md b/docs/resolution.md new file mode 100644 index 0000000..b6961a2 --- /dev/null +++ b/docs/resolution.md @@ -0,0 +1,82 @@ +# Resolution and limits + +Brick extracts syntax, without compiler type checking or build configuration. +Macro expansion, overload resolution, dynamic dispatch, generated code and full +package/build-system resolution are outside the default frontend. Malformed +syntax produces diagnostics; recoverable sibling facts stay visible. + +Every unresolved call edge records `source.unresolved-reason`, resolved member +calls carry `source.resolution`, and `metrics.resolution` reports per-language +call-site coverage. Ambiguous targets stay external. Read the graph with that +coverage in mind: on a large C++ repository only a minority of call sites +resolve. File fan-out is an observation, not proof of semantic coupling; scope +architecture gates to production paths and verify candidates against source and +tests. + +## Per language + +- **All grammar-based languages:** resolution respects language, file, + declaration ownership and lexical namespace. +- **JavaScript/TypeScript:** relative imports resolve against the importing + directory, and missing paths never fall back to unrelated basenames. Explicit + named and default import bindings resolve across files. +- **Dart:** relative imports resolve against the importing directory, and + `package:/` against `lib/`. Public top-level names from imported + libraries resolve across files; `show`/`hide` combinators are not modelled. +- **Rust:** module-scoped grouped and aliased imports and module-qualified public + calls resolve. Types are identified by their declaring file, so same-named + types in different modules resolve through the caller's `use` binding or stay + ambiguous. Calls inside expression macros (`assert!`, `format!`, `vec!`, ...) + are recovered by re-parsing and carry `source.extraction`. +- **C and C++:** calls resolve through the include closure. A header prototype + pairs with its definition in another translation unit, lookup walks class + (including in-repository bases) and namespace scopes outward, and + `static`/anonymous definitions stay file-local. Declarations in `#elif`/`#else` + branches stay in the graph (`source.preprocessor-branch: alternative`) but are + never call targets, because Brick does not evaluate conditions. Several + `using` directives that nominate different declarations make a call + ambiguous. Virtual calls resolve to the declared type's method only + (overrides are not fanned out), and Catch2 `TEST_CASE` bodies are not yet + recognized as functions. `.c` files use the C grammar. +- **C++ and Rust member calls** resolve only through an explicitly declared + receiver type: a parameter, local, field, `this`/`self`, smart pointer, or a + `Self`-returning constructor. +- **Python (lexical preview):** names resolve in the calling file, then in files + it imports. +- **Swift (lexical preview):** names resolve in the calling file, then by a + module-wide unique name, since Swift files of one module see each other + without imports. + +Not yet handled, and needing further adapters: bare package specifiers, +tsconfig aliases, Rust wildcard and block-local binding expansion, Cargo +workspace module paths, `compile_commands.json` include paths, and +compiler-grade dispatch. + +## P4 + +P4 extraction is a conservative P4_16 lexical preview, not a p4c frontend. +Implicit terminal states are modelled only when referenced. Parser transitions +and control/action calls use scoped lexical resolution; unresolved targets stay +external. The optional Tree-sitter pilot does not preprocess macros and rejects +all pilot facts from a file whose parse has error or missing nodes. P4_14, macro +expansion, architecture type checking, compiler IR and formal-verifier evidence +need separate adapters; P4V, `p4-symbolic`, bf4 and P4K adapters stay disabled +until a real versioned machine-readable result contract and explicit +bounded-model semantics are qualified. + +## Evidence for these rules + +The source-language regression corpus checks exact declarations, owners and +dependencies across six language strata, including clean-negative files; its +three-repeat benchmark runs in the quality gate. These labelled cases establish +the covered behaviours, not language-wide accuracy. See +[language correctness](research/language-correctness.md). + +## Schema + +Schema version 4 stores scan scope (including the selected P4 frontend), +parallel relationship evidence and a nested `metrics.p4` contract. CLI consumers +reject version 1-3 JSON rather than guess; rebuild old artifacts before +rendering or checking them. Consuming compiler, YAMS and Fold graph facts +through adapters, while keeping the lexical lane as a fast preview, is on the +[roadmap](ROADMAP.md); see also the [graph model](architecture/graph-model.md). diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..f655141 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,134 @@ +# 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 four tools +cover dependency/dependent impact, SCC cycles, weak-graph bridges and complete +node/edge evidence inspection; they 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. -- 2.52.0