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

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:

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:

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 for the cache contract and Legacy Adapters and No-AST Policy 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:

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 for generated client fragments and MCP Boundary for the exact tool contract.

6.6 KiB Raw Blame History