149 lines
6.6 KiB
Markdown
149 lines
6.6 KiB
Markdown
# Reference adapters
|
|
|
|
DocForge includes fixed, syntax-scoped reference adapters for Python, JavaScript, TypeScript, and
|
|
C++. They demonstrate the public adapter contract, deterministic complete and incremental
|
|
publication, function Logic, cache recovery, and a runnable read-only MCP binding. They are not
|
|
compiler or language-service replacements.
|
|
|
|
Use a reference adapter when its deliberately narrow graph is sufficient or when proving a fresh
|
|
DocForge integration. Use the [Language Adapter Authoring Guide](ADAPTER_AUTHORING_GUIDE.md) for a
|
|
production adapter that needs resolved symbols, calls, inheritance, types, build semantics, or
|
|
semantic ownership.
|
|
|
|
## Installation
|
|
|
|
The Python reference adapter uses the standard library and is available in the base wheel. The
|
|
other frontends are separate optional extras:
|
|
|
|
```bash
|
|
python -m pip install docforge
|
|
python -m pip install "docforge[javascript]"
|
|
python -m pip install "docforge[typescript]"
|
|
python -m pip install "docforge[cpp]"
|
|
```
|
|
|
|
Install `docforge[languages]` only when one environment intentionally needs all three Tree-sitter
|
|
frontends. JavaScript and TypeScript use distinct grammar packages and distinct extras.
|
|
|
|
## Fixed project configuration
|
|
|
|
The runnable reference binding reads exactly
|
|
`.docforge/reference-adapter.toml` below the selected project root. The configuration is data only:
|
|
it cannot name a provider, Python module, command, arguments, working directory, environment, or
|
|
discovery rule.
|
|
|
|
Reference adapter configuration `.docforge/reference-adapter.toml`:
|
|
|
|
```toml
|
|
schema_version = 1
|
|
project_id = "example-python"
|
|
title = "Example Python project"
|
|
language = "python"
|
|
source_roots = ["src"]
|
|
```
|
|
|
|
`language` is one of `python`, `javascript`, `typescript`, or `cpp`. Source roots must be sorted,
|
|
unique, non-overlapping project-relative directories outside `.docforge`. The configuration,
|
|
roots, and inventoried source files must be regular confined paths without symlink traversal. The
|
|
configuration is limited to 65,536 bytes, at most 64 source roots, and 65,536 examined inventory
|
|
entries.
|
|
|
|
C++ additionally requires one explicit project-confined compilation database:
|
|
|
|
```toml
|
|
schema_version = 1
|
|
project_id = "example-cpp"
|
|
title = "Example C++ project"
|
|
language = "cpp"
|
|
source_roots = ["include", "src"]
|
|
compilation_database = "compile_commands.json"
|
|
```
|
|
|
|
`compilation_database` is forbidden for the other three languages.
|
|
|
|
## Published scope
|
|
|
|
All four adapters publish deterministic file, module or translation-unit, class or struct, and
|
|
function nodes where their syntax supports those categories. They publish lexical `contains`
|
|
relationships, a narrow set of project-local `depends_on` relationships, and function-scoped
|
|
Logic. Calls that appear inside Logic are syntax steps, not resolved symbol relationships.
|
|
|
|
### Python
|
|
|
|
Python uses `ast` from the standard library for source extraction and Logic. Manifest construction
|
|
does not build a Python AST; it tokenizes imports only far enough to publish dependencies that
|
|
resolve to another module in the declared source inventory.
|
|
|
|
It does not import or execute project code. It does not resolve dynamic imports, calls,
|
|
inheritance, imported symbols, types, overloads, re-exports, decorators, metaclasses, descriptors,
|
|
or runtime-generated behavior.
|
|
|
|
### JavaScript and TypeScript
|
|
|
|
JavaScript uses the optional `tree-sitter-javascript` grammar. TypeScript uses the distinct
|
|
optional `tree-sitter-typescript` grammar. Their focused incremental tests prove that manifest
|
|
construction and an unchanged warm build do not invoke the Tree-sitter extraction parser.
|
|
|
|
Only static relative imports and re-exports that resolve to another inventoried source file become
|
|
dependencies. Dynamic `import()`, `require()`, bare package specifiers, aliases, `tsconfig` paths,
|
|
loader hooks, types, interfaces, overloads, calls, inheritance, symbols, and runtime behavior are
|
|
not resolved. The adapters never import, compile, transpile, or execute project code.
|
|
|
|
### C++
|
|
|
|
C++ treats `compile_commands.json` as the authoritative bounded translation-unit inventory and as
|
|
fingerprint evidence. Commands, arguments, directories, and output fields are parsed as inert
|
|
data. The adapter executes no compiler, build tool, command, project binary, or project code.
|
|
|
|
The reference C++ manifest uses the optional `tree-sitter-cpp` grammar to parse inventoried sources
|
|
and discover quoted includes. It publishes a dependency only when that quoted include resolves
|
|
directly to a real project-local header in the declared roots. Angle-bracket includes, compiler
|
|
include paths, frameworks, generated headers, compiler-provided headers, conditional compilation,
|
|
and macro expansion are omitted.
|
|
|
|
This is not a Clang semantic adapter. It does not claim resolved calls, types, templates, aliases,
|
|
concepts, references, inheritance, overload ownership, out-of-line semantic ownership, macro
|
|
semantics, or compiler include semantics. A warm C++ extraction-cache hit is therefore not evidence
|
|
that manifest construction performed zero parser work.
|
|
|
|
## Complete and incremental proof
|
|
|
|
Each reference adapter implements:
|
|
|
|
- `load_projection()` for the complete primary graph compatibility oracle;
|
|
- `load_complete_assembly()` for the complete graph-plus-Logic oracle;
|
|
- `load_manifest()` and `extract_source()` for incremental extraction; and
|
|
- deterministic assembly of the complete current contribution set.
|
|
|
|
The maintained fixtures prove complete determinism, exact complete/incremental graph and Logic
|
|
parity, reverse-dependency invalidation, additions and deletions, corrupt extraction-cache
|
|
recovery, confinement, and exact unsupported-fact inventories. See
|
|
[Incremental Adapter Indexing](INCREMENTAL_INDEXING.md) for the cache contract and
|
|
[Legacy Adapters and No-AST Policy](LEGACY_AND_NO_AST.md) for compatibility and policy limits.
|
|
|
|
Current fixture evidence is:
|
|
|
|
| Language | Primary nodes | Relationships | Logic projections |
|
|
|---|---:|---:|---:|
|
|
| Python | 14 | 13 | 5 |
|
|
| JavaScript | 14 | 14 | 5 |
|
|
| TypeScript | 13 | 14 | 4 |
|
|
| C++ | 17 | 16 | 5 |
|
|
|
|
These are regression-fixture shapes, not promises for arbitrary repositories.
|
|
|
|
## Read-only reference server
|
|
|
|
Start the fixed server with:
|
|
|
|
```bash
|
|
python -I -m docforge.reference_mcp \
|
|
--project-root /absolute/path/to/project \
|
|
--capability-mode read
|
|
```
|
|
|
|
The server selects one of the four in-repository providers solely from the validated fixed
|
|
configuration. Its cache stays below `.docforge/cache/reference-adapter/<language>`. It registers
|
|
the 21-tool read surface and no proposal or application tools. See
|
|
[Agent Integration](AGENT_INTEGRATION.md) for generated client fragments and
|
|
[MCP Boundary](MCP_CONTRACT.md) for the exact tool contract.
|