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:

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.

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:

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

3.8 KiB Raw Blame History