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
|
|
@ -35,6 +35,8 @@ incremental methods while retaining the full loader as a fallback.
|
|||
relationship keys, source inspection, branch-aware node hiding, panel resizing, zooming, and
|
||||
managed idle shutdown.
|
||||
- A generic Markdown/TOML adapter plus contracts for deterministic project-owned adapters.
|
||||
- A public adapter SDK, optional Python/JavaScript/TypeScript/C++ reference integrations, and one
|
||||
fixed read-only reference MCP binding.
|
||||
|
||||
DocForge does not run shell commands from documentation, mutate Git, build an application, deploy,
|
||||
publish, choose a project globally, or cross project boundaries.
|
||||
|
|
@ -100,6 +102,49 @@ uv run pytest -q
|
|||
Use the executables under `/absolute/path/DocForge/.venv/bin/` when DocForge is not installed into
|
||||
the active shell environment.
|
||||
|
||||
For an installed distribution, choose only the language extras the project needs:
|
||||
|
||||
```bash
|
||||
python -m pip install docforge
|
||||
python -m pip install 'docforge[javascript]'
|
||||
python -m pip install 'docforge[typescript]'
|
||||
python -m pip install 'docforge[cpp]'
|
||||
```
|
||||
|
||||
The base wheel contains the Python reference adapter and no Tree-sitter distribution. JavaScript,
|
||||
TypeScript, and C++ require their matching optional extras. `docforge[languages]` installs all
|
||||
three optional frontend groups.
|
||||
|
||||
### Configure a reference source project
|
||||
|
||||
Reference adapters are a narrow alternative to the generic documentation descriptor. Create
|
||||
`.docforge/reference-adapter.toml`:
|
||||
|
||||
```toml reference-adapter
|
||||
schema_version = 1
|
||||
project_id = "my-python-project"
|
||||
title = "My Python Project"
|
||||
language = "python"
|
||||
source_roots = ["src"]
|
||||
```
|
||||
|
||||
Start the fixed read-only server:
|
||||
|
||||
```bash
|
||||
python -I -m docforge.reference_mcp \
|
||||
--project-root /absolute/path/MyProject \
|
||||
--capability-mode read
|
||||
```
|
||||
|
||||
For C++, set `language = "cpp"` and add a project-relative
|
||||
`compilation_database = "compile_commands.json"`. The database is inert bounded inventory; the
|
||||
reference adapter does not execute its commands or compiler.
|
||||
|
||||
The reference integrations publish syntax and local static relationships only. They do not claim
|
||||
resolved calls, types, inheritance, macro behavior, compiler include semantics, runtime behavior,
|
||||
or semantic ownership. See [reference adapters](REFERENCE_ADAPTERS.md) for exact evidence and
|
||||
limitations.
|
||||
|
||||
### Assess and onboard an unconfigured project
|
||||
|
||||
Run a read-only assessment before writing configuration:
|
||||
|
|
@ -478,6 +523,10 @@ Every command emits deterministic JSON:
|
|||
docforge --project-root /absolute/path/MyProject <command>
|
||||
```
|
||||
|
||||
The sections below group common workflows. The implementation-derived list of all 28 current
|
||||
commands, exact invocations, 36 generic MCP tools, arguments, and input-schema hashes is the
|
||||
[generated command reference](COMMAND_REFERENCE.md).
|
||||
|
||||
### Project and index commands
|
||||
|
||||
```text
|
||||
|
|
@ -590,6 +639,31 @@ declares the named writer, and application requires the same writer/applier iden
|
|||
`--no-ast` to preserve the no-AST binding. Generic CLI generation refuses project-owned adapters
|
||||
because it cannot safely reconstruct their composition.
|
||||
|
||||
A custom adapter owner supplies the already constructed project and immutable launcher through the
|
||||
Python API:
|
||||
|
||||
```python
|
||||
from docforge.adapter_launcher import AdapterLauncherV1
|
||||
from docforge.client_config import generate_adapter_client_configuration
|
||||
|
||||
launcher = AdapterLauncherV1.for_project(
|
||||
project,
|
||||
module="my_project_docforge",
|
||||
)
|
||||
fragment = generate_adapter_client_configuration(
|
||||
project,
|
||||
launcher,
|
||||
"codex",
|
||||
capability_mode="read",
|
||||
)
|
||||
```
|
||||
|
||||
The top-level module must be installed for the exact isolated Python environment and resolve to a
|
||||
regular file inside the project root. The fixed `docforge.reference_mcp` module is the only trusted
|
||||
dotted exception. Generation probes resolution without importing the custom module, binds current
|
||||
source availability and policy, and emits no arbitrary command, arguments, working directory, or
|
||||
environment.
|
||||
|
||||
Select projection behavior independently:
|
||||
|
||||
```bash
|
||||
|
|
@ -684,6 +758,10 @@ docforge-mcp \
|
|||
|
||||
Omit `--proposal-writer` when the MCP client should not create or append proposals.
|
||||
|
||||
For `.docforge/reference-adapter.toml`, use the fixed `docforge.reference_mcp` command shown in
|
||||
[setup](#configure-a-reference-source-project). It exposes exactly the 21 read tools and never
|
||||
registers proposal or application tools.
|
||||
|
||||
Select the session's declared surface explicitly when useful:
|
||||
|
||||
```bash
|
||||
|
|
@ -986,6 +1064,28 @@ changes outside this process boundary.
|
|||
|
||||
## Troubleshooting
|
||||
|
||||
### `optional_dependency_missing`
|
||||
|
||||
Install the exact extra named in the error into the same Python environment that starts DocForge:
|
||||
|
||||
```bash
|
||||
python -m pip install 'docforge[javascript]'
|
||||
python -m pip install 'docforge[typescript]'
|
||||
python -m pip install 'docforge[cpp]'
|
||||
```
|
||||
|
||||
Do not install every frontend merely to suppress the check. A missing optional parser is a closed,
|
||||
actionable capability error and does not affect base generic or Python reference operation.
|
||||
|
||||
### `adapter_launcher_unavailable` or `invalid_adapter_launcher`
|
||||
|
||||
Use one installed top-level Python module whose resolved regular-file origin is inside the project
|
||||
root, or use the fixed `docforge.reference_mcp` binding. Arbitrary dotted modules, packages,
|
||||
stdlib modules, missing modules, commands, argument strings, working directories, and environment
|
||||
injection are rejected. Test the exact generated fragment rather than editing its command by hand.
|
||||
|
||||
See [agent integration](AGENT_INTEGRATION.md) and the [security model](SECURITY.md).
|
||||
|
||||
### `adapter_restart_required`
|
||||
|
||||
The project-local adapter code, its declared descriptor, or another implementation file changed
|
||||
|
|
@ -1128,8 +1228,11 @@ make gate
|
|||
Use `make benchmark` for the historical Milestone 0 baseline, `make benchmark-m1` for the
|
||||
counter-gated warm-operation benchmark, `make benchmark-m2` for agent workflow gates, and
|
||||
`make benchmark-m3-full` for the ten-sample 1,000-node projection, worker, fragment, status,
|
||||
equivalence, response-size, and memory gates. `make accessibility` runs the generated manual,
|
||||
portable graph, and live viewer axe and keyboard flows.
|
||||
equivalence, response-size, and memory gates. `make benchmark-m4-full` runs the 1,002-node adapter
|
||||
and recovery benchmark. `make adoption-m4` performs the offline fresh-wheel proof.
|
||||
`make command-reference-check` rejects command-reference drift, and `make docs-check` validates
|
||||
the maintained documentation graph. `make accessibility` runs the generated manual, portable
|
||||
graph, and live viewer axe and keyboard flows.
|
||||
|
||||
Project-specific vocabulary, extraction rules, and serialization belong in the project adapter.
|
||||
Generic core behavior must remain deterministic, project-bound, and recoverable.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue