# 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).