70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# Brick
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
```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
|
|
```
|
|
|
|
Open the HTML in a browser. `build` prints diagnostic counts, and a scan that
|
|
finds no supported source says so.
|
|
|
|
## Commands
|
|
|
|
| Command | What it does |
|
|
| --- | --- |
|
|
| `brick build <repo>` | Scan a repository; write JSON and HTML. Can layer Fold/SARIF or p4c findings onto the graph. |
|
|
| `brick render <model.json>` | Render an existing model to HTML. |
|
|
| `brick check <model.json>` | 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 <model.json>` | Serve read-only MCP queries: impact, cycles, bridges, evidence, and caller status (is a function called, unknown, or unreferenced). |
|
|
| `brick setup` | Report which optional frontends this binary can initialize. |
|
|
|
|
Full usage, including the import contracts: [docs/usage.md](docs/usage.md).
|
|
|
|
## Limits
|
|
|
|
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.
|
|
|
|
## Documentation
|
|
|
|
- [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).
|