86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
# 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:<own package>/` against `lib/`. Public top-level names from imported
|
|
libraries resolve across files: `show`/`hide` are honoured, `as`-prefixed
|
|
imports never bind bare names, and a library's own `export`s are followed one
|
|
level.
|
|
- **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), and
|
|
[C/C++ and Rust resolution](research/cpp-rust-resolution.md) for that
|
|
resolver's research, validation and the agent-facing caller-status contract.
|
|
|
|
## 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).
|