Add language-neutral project onboarding
This commit is contained in:
parent
73165c9f51
commit
09c09300b1
8 changed files with 924 additions and 9 deletions
266
docs/PROJECT_ONBOARDING.md
Normal file
266
docs/PROJECT_ONBOARDING.md
Normal file
|
|
@ -0,0 +1,266 @@
|
|||
# Project onboarding
|
||||
|
||||
DocForge onboarding has two separate outcomes:
|
||||
|
||||
1. A generic manual can be configured, indexed, rendered, visualized, and exposed through the MCP.
|
||||
2. A source graph additionally requires one validated language frontend per source language.
|
||||
|
||||
The onboarding command never claims that source semantics exist merely because it found source
|
||||
files. It reports each detected language as `adapter_required` until a project integration supplies
|
||||
and proves that frontend.
|
||||
|
||||
## Start with a read-only assessment
|
||||
|
||||
```bash
|
||||
docforge --project-root /absolute/path/MyProject onboard
|
||||
```
|
||||
|
||||
The assessment:
|
||||
|
||||
- detects common source languages and build-system evidence;
|
||||
- excludes version-control, dependency, generated, cache, and build directories;
|
||||
- inventories likely documentation;
|
||||
- reports whether the project is already configured;
|
||||
- states which capabilities are ready and which still need an adapter;
|
||||
- does not create or modify files.
|
||||
|
||||
Limit detection to one or more known profiles when automatic discovery is not appropriate:
|
||||
|
||||
```bash
|
||||
docforge --project-root /absolute/path/MyProject onboard --language rust
|
||||
docforge --project-root /absolute/path/MyProject onboard --language java
|
||||
docforge --project-root /absolute/path/MyProject onboard \
|
||||
--language cpp \
|
||||
--language typescript
|
||||
```
|
||||
|
||||
Current profile IDs are `c`, `cpp`, `csharp`, `go`, `java`, `javascript`, `kotlin`, `lua`, `php`,
|
||||
`python`, `ruby`, `rust`, `scala`, `swift`, and `typescript`. A profile recognizes project
|
||||
evidence. It is not itself a parser.
|
||||
|
||||
## Scaffold a generic manual
|
||||
|
||||
After reviewing the assessment:
|
||||
|
||||
```bash
|
||||
docforge --project-root /absolute/path/MyProject onboard \
|
||||
--scaffold \
|
||||
--project-id my-project \
|
||||
--title "My Project"
|
||||
```
|
||||
|
||||
Scaffolding creates:
|
||||
|
||||
- `.docforge/project.toml`;
|
||||
- `.docforge/templates/manual.html`;
|
||||
- `docs/docforge/content/project-overview.md`;
|
||||
- the derived SQLite index;
|
||||
- the rendered starter manual.
|
||||
|
||||
The command refuses to replace any existing target. Canonical files are written before the
|
||||
descriptor, and a failed write removes files created by that attempt. The configured manual is
|
||||
immediately usable through the generic CLI, viewer, and MCP.
|
||||
|
||||
The starter overview records detected languages and states that the source graph is unavailable
|
||||
until a language frontend passes the adapter proof. That limitation is deliberate.
|
||||
|
||||
## Complete onboarding checklist
|
||||
|
||||
### 1. Repository assessment
|
||||
|
||||
- [ ] Resolve one explicit project root.
|
||||
- [ ] Detect version-control and worktree boundaries.
|
||||
- [ ] Detect source languages and build systems.
|
||||
- [ ] Find existing manuals, design notes, API references, plans, and proof records.
|
||||
- [ ] Exclude vendored, generated, dependency, cache, and build trees.
|
||||
- [ ] Estimate source, documentation, and expected graph size.
|
||||
- [ ] Report missing tools without changing the repository.
|
||||
- [ ] Review the assessment before scaffolding.
|
||||
|
||||
Done when authored source is distinguishable from disposable and external files.
|
||||
|
||||
### 2. Identity and authority
|
||||
|
||||
- [ ] Assign a stable project ID and title.
|
||||
- [ ] Declare canonical content roots.
|
||||
- [ ] Declare authority files.
|
||||
- [ ] Declare derived cache, changeset, preview, template, and render roots.
|
||||
- [ ] Define documentation families and allowed relationships.
|
||||
- [ ] Define proposal writers and operations.
|
||||
- [ ] Decide which views are public, internal, or restricted.
|
||||
- [ ] Keep source mutation disabled unless separately designed and authorized.
|
||||
|
||||
Done when every durable documentation fact has one authoritative source and every derived output
|
||||
can be deleted without losing that fact.
|
||||
|
||||
### 3. Manual foundation
|
||||
|
||||
- [ ] Scaffold or adapt `.docforge/project.toml`.
|
||||
- [ ] Create at least one authoritative overview node.
|
||||
- [ ] Assign stable node IDs, families, authorities, statuses, tags, and summaries.
|
||||
- [ ] Import existing documents without silently changing their meaning.
|
||||
- [ ] Separate current implementation, approved plans, proposals, and history.
|
||||
- [ ] Define bounded context profiles for common development tasks.
|
||||
- [ ] Validate, index, render, and visualize the manual.
|
||||
|
||||
Done when every rendered passage can be traced to a canonical source.
|
||||
|
||||
### 4. Language frontend selection
|
||||
|
||||
For every source language:
|
||||
|
||||
- [ ] Select or implement one frontend.
|
||||
- [ ] Record its frontend and extractor versions.
|
||||
- [ ] Define source discovery from authoritative build information.
|
||||
- [ ] Define stable symbol identities.
|
||||
- [ ] Define ownership for shared or generated declarations.
|
||||
- [ ] Define supported node kinds and relationships.
|
||||
- [ ] Define dependency discovery.
|
||||
- [ ] State unsupported semantic facts explicitly.
|
||||
|
||||
All frontends emit the same DocForge contracts:
|
||||
|
||||
- `AdapterManifest` inventories fingerprinted extraction units and dependencies.
|
||||
- `AdapterSourceProjection` owns nodes, relationships, and optional function Logic for one unit.
|
||||
- `AdapterProjection` provides the deterministic complete rebuild.
|
||||
|
||||
Language metadata may differ. Graph publication, indexing, querying, visualization, and MCP
|
||||
behavior do not.
|
||||
|
||||
Done when repeated extraction produces the same stable identities without inferred or guessed
|
||||
facts.
|
||||
|
||||
### 5. Build-system evidence
|
||||
|
||||
#### C and C++
|
||||
|
||||
- [ ] Use an authoritative compilation database.
|
||||
- [ ] Preserve target flags, definitions, language standards, and include paths.
|
||||
- [ ] Resolve headers shared by multiple translation units.
|
||||
- [ ] Assign shared symbols to one deterministic source contribution.
|
||||
- [ ] Record compiler-derived project include dependencies.
|
||||
|
||||
#### Rust
|
||||
|
||||
- [ ] Read the Cargo workspace and package graph.
|
||||
- [ ] Respect packages, targets, features, and conditional compilation.
|
||||
- [ ] Model crates, modules, traits, implementations, functions, and supported macros.
|
||||
- [ ] Treat expanded macro output as derived evidence.
|
||||
- [ ] Record the exact toolchain and extraction backend.
|
||||
|
||||
#### Java
|
||||
|
||||
- [ ] Read Gradle, Maven, or explicit source-root configuration.
|
||||
- [ ] Respect modules, source sets, language level, and classpath.
|
||||
- [ ] Model packages, classes, interfaces, records, methods, fields, and supported annotations.
|
||||
- [ ] Separate authored source from generated and annotation-processor output.
|
||||
- [ ] Record inheritance and interface implementation.
|
||||
|
||||
Other languages follow the same rule: the language frontend translates authoritative build and
|
||||
source evidence into the common adapter contract.
|
||||
|
||||
Done when a clean machine can reproduce the same source inventory from declared configuration.
|
||||
|
||||
### 6. Complete reference projection
|
||||
|
||||
- [ ] Extract the complete supported source tree.
|
||||
- [ ] Generate stable source and symbol nodes.
|
||||
- [ ] Generate only evidence-backed relationships.
|
||||
- [ ] Generate optional function-scoped Logic separately from the primary graph.
|
||||
- [ ] Reject duplicate node or Logic ownership.
|
||||
- [ ] Reject missing relationship endpoints.
|
||||
- [ ] Reject unsafe source paths.
|
||||
- [ ] Record project identity, source hash, counts, and duration.
|
||||
- [ ] Repeat the build and compare exact output.
|
||||
|
||||
Done when two unchanged complete builds are identical.
|
||||
|
||||
### 7. Incremental compilation
|
||||
|
||||
- [ ] Fingerprint each extraction unit.
|
||||
- [ ] Record extractor versions.
|
||||
- [ ] Record direct source dependencies.
|
||||
- [ ] Invalidate reverse dependents.
|
||||
- [ ] Remove deleted-source contributions.
|
||||
- [ ] Treat missing or corrupt caches as cache misses.
|
||||
- [ ] Publish cache and graph generations atomically.
|
||||
- [ ] Keep the complete projection as the equivalence oracle.
|
||||
|
||||
Required proof:
|
||||
|
||||
- [ ] cold build;
|
||||
- [ ] unchanged warm build;
|
||||
- [ ] implementation-file change;
|
||||
- [ ] shared-header or shared-module change;
|
||||
- [ ] added, renamed, and deleted source;
|
||||
- [ ] build-feature or compiler-setting change;
|
||||
- [ ] corrupt cache;
|
||||
- [ ] interrupted extraction;
|
||||
- [ ] complete-versus-incremental equivalence.
|
||||
|
||||
Done when incremental extraction produces exactly the complete projection.
|
||||
|
||||
### 8. Source and manual integration
|
||||
|
||||
- [ ] Link documented systems to their implementation.
|
||||
- [ ] Link API reference nodes to extracted symbols.
|
||||
- [ ] Link roadmap work to affected systems.
|
||||
- [ ] Link relevant tests and proof artifacts.
|
||||
- [ ] Report implemented but undocumented systems.
|
||||
- [ ] Report documented systems without implementation.
|
||||
- [ ] Keep uncertain links as proposals.
|
||||
- [ ] Keep source and manual projections independently rebuildable.
|
||||
|
||||
Done when a developer can navigate from a decision to implementation and back without guessing
|
||||
from filenames.
|
||||
|
||||
### 9. Views and MCP
|
||||
|
||||
- [ ] Configure the generic graph browser.
|
||||
- [ ] Configure manual, source, API, roadmap, and proof views as needed.
|
||||
- [ ] Verify search, filters, backlinks, dependencies, impact, and Logic.
|
||||
- [ ] Generate the exact project-bound MCP command.
|
||||
- [ ] Select read, proposal, and application capabilities explicitly.
|
||||
- [ ] Register and reload the client.
|
||||
- [ ] Call `docforge_bootstrap`.
|
||||
- [ ] Verify project ID, root fingerprint, adapter version, revision, source hash, and index health.
|
||||
- [ ] Verify the MCP cannot switch projects or weaken project authority.
|
||||
|
||||
Done when a new session can identify and retrieve the correct project without being told its file
|
||||
layout.
|
||||
|
||||
### 10. Operating guide and maintenance
|
||||
|
||||
- [ ] Record the authority and progressive-reading order.
|
||||
- [ ] Explain exact lookup, search, context, backlinks, and impact analysis.
|
||||
- [ ] Explain proposal, review, approval, and application.
|
||||
- [ ] Explain cache invalidation and recovery.
|
||||
- [ ] Explain frontend and adapter version changes.
|
||||
- [ ] Run complete/incremental equivalence in continuous integration.
|
||||
- [ ] Add contract tests for newly supported language features.
|
||||
- [ ] Never hand-resolve generated-output conflicts.
|
||||
- [ ] Never convert an inferred relationship into canonical truth silently.
|
||||
|
||||
Done when a developer unfamiliar with the repository can use DocForge without loading the entire
|
||||
manual or inventing another documentation workflow.
|
||||
|
||||
## CLI and MCP boundary
|
||||
|
||||
Initial assessment and scaffolding belong to the CLI because an MCP server cannot be registered
|
||||
until the project exists. The MCP begins at `docforge_bootstrap`, after its process has been fixed
|
||||
to one configured project root.
|
||||
|
||||
DocForge does not let an MCP call install dependencies, run project builds, modify Git, deploy, or
|
||||
publish. A project integration may use its own normal development workflow for those actions.
|
||||
|
||||
## Frontend packaging direction
|
||||
|
||||
Reusable language frontends should be separate packages or project-owned adapters over the public
|
||||
DocForge contracts. They must not put language-specific rules into the graph, index, viewer, or MCP
|
||||
core.
|
||||
|
||||
Worldforge is the first complete C++ reference integration. A reusable C++ package should be
|
||||
extracted only after that integration proves stable ownership, compiler dependency invalidation,
|
||||
and complete/incremental equivalence. Rust and Java frontends should then implement the same
|
||||
contract using their authoritative build and language tooling rather than copying C++ extraction
|
||||
rules.
|
||||
Loading…
Add table
Add a link
Reference in a new issue