81 lines
3.8 KiB
Markdown
81 lines
3.8 KiB
Markdown
|
# Legacy adapters and no-AST policy
|
||
|
|
|
||
|
|
DocForge preserves the original one-method adapter contract while offering incremental extraction,
|
||
|
|
complete graph-plus-Logic assemblies, and an independently selectable no-AST MCP policy. These are
|
||
|
|
separate compatibility boundaries.
|
||
|
|
|
||
|
|
## One-method adapters remain valid
|
||
|
|
|
||
|
|
An existing adapter that implements only:
|
||
|
|
|
||
|
|
```python
|
||
|
|
def load_projection(self) -> AdapterProjection: ...
|
||
|
|
```
|
||
|
|
|
||
|
|
continues to work. It receives the same projection validation, indexing, querying, visualization,
|
||
|
|
and MCP behavior as before. It does not receive extraction-cache speedups and publishes no Logic
|
||
|
|
through the complete assembly contract.
|
||
|
|
|
||
|
|
Incremental adoption is additive. Implement `load_manifest()` and `extract_source()` while keeping
|
||
|
|
`load_projection()` as the independent complete graph oracle. If incremental contributions publish
|
||
|
|
Logic, also implement `load_complete_assembly()` so complete and incremental graph-plus-Logic
|
||
|
|
output can be compared exactly. The public authoring surface is `docforge.adapter_sdk`; see the
|
||
|
|
[Language Adapter Authoring Guide](ADAPTER_AUTHORING_GUIDE.md).
|
||
|
|
|
||
|
|
## What no-AST means
|
||
|
|
|
||
|
|
`--no-ast` is an immutable policy on one MCP process binding. It preserves the configured adapter
|
||
|
|
strategy but forbids AST, Tree-sitter, compiler-AST, and function-Logic evolution for that binding.
|
||
|
|
It also rejects nonempty Logic before index publication and rejects a pre-existing index that
|
||
|
|
contains Logic before reads or live visualization.
|
||
|
|
|
||
|
|
Start the generic server with:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
docforge-mcp --project-root /absolute/path/to/project --no-ast
|
||
|
|
```
|
||
|
|
|
||
|
|
Project-owned integrations select the same policy with
|
||
|
|
`create_project_server(..., no_ast=True)` or `create_read_only_server(..., no_ast=True)`.
|
||
|
|
`docforge_bootstrap` and `docforge_get_contract` report the effective policy, and
|
||
|
|
`docforge_get_logic` returns `adapter_policy_forbids_logic`.
|
||
|
|
|
||
|
|
Changing this policy requires a new process. It does not rewrite or reload an adapter in place.
|
||
|
|
|
||
|
|
## What no-AST does not mean
|
||
|
|
|
||
|
|
No-AST is not:
|
||
|
|
|
||
|
|
- an inspection mechanism that proves which parser an arbitrary adapter uses;
|
||
|
|
- a filesystem, Python-import, or process sandbox;
|
||
|
|
- a promise that the adapter performs no non-AST fingerprinting, dependency discovery, caching, or
|
||
|
|
complete-projection loading; or
|
||
|
|
- permission to change project files, adapter code, or the configured capability surface.
|
||
|
|
|
||
|
|
Repository permissions and project instructions remain responsible for processes that have direct
|
||
|
|
filesystem access. The MCP boundary still excludes shell execution, arbitrary file operations,
|
||
|
|
Git mutation, builds, deployment, publication, project switching, and cross-project retrieval.
|
||
|
|
|
||
|
|
## Reference adapters are not no-AST adapters
|
||
|
|
|
||
|
|
The built-in Python reference extracts syntax and Logic with the standard-library AST. The
|
||
|
|
JavaScript, TypeScript, and C++ references extract syntax and Logic with their optional
|
||
|
|
Tree-sitter grammars. Their normal projections contain Logic, so they must not be presented or
|
||
|
|
configured as no-AST adapters.
|
||
|
|
|
||
|
|
The narrower performance statements in [Reference Adapters](REFERENCE_ADAPTERS.md) concern
|
||
|
|
specific manifest and warm-cache paths. A parser-free manifest does not turn an adapter that
|
||
|
|
publishes AST-derived Logic into a no-AST adapter.
|
||
|
|
|
||
|
|
## Migration choices
|
||
|
|
|
||
|
|
Keep a one-method adapter when its complete rebuild is acceptable and no function Logic is needed.
|
||
|
|
Adopt incremental extraction when measured source parsing dominates synchronization. Adopt the
|
||
|
|
complete assembly contract when Logic is published or overlapping raw evidence needs deterministic
|
||
|
|
ownership.
|
||
|
|
|
||
|
|
Choose no-AST only when the project binding must forbid AST-derived publication and future adapter
|
||
|
|
upgrades of that kind. It is a binding policy, not a substitute for adapter confinement,
|
||
|
|
conformance tests, restart detection, cache recovery, or the full proof matrix in
|
||
|
|
[Incremental Adapter Indexing](INCREMENTAL_INDEXING.md).
|