Close Milestone 4 with adapter adoption evidence
This commit is contained in:
parent
95271dcf2e
commit
6d06195950
27 changed files with 2870 additions and 325 deletions
149
docs/REFERENCE_ADAPTERS.md
Normal file
149
docs/REFERENCE_ADAPTERS.md
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue