doc-weaver/README.md

doc-weaver

TypeScript documentation compiler that mirrors doc-forge.

doc-weaver reads TypeScript + JSDoc and emits documentation for both humans and machines:

• Humans – a TypeDoc site (the parallel to doc-forge's MkDocs site).
• Machines – an MCP JSON bundle (index.json, nav.json, modules/) whose shape is byte-compatible with the bundle doc-forge produces for Python, so the same consumers (agents, docs:// clients, the standards registry) can query it unchanged.

Where doc-forge uses mkdocs + Google-style docstrings (GSDFC), doc-weaver uses TypeDoc + Google-style JSDoc (RDFC).

---

Parity map

Concern	Python (doc-forge)	TypeScript (doc-weaver)
Source of truth	Python docstrings (GSDFC)	TypeScript types + JSDoc (RDFC)
Front-end (loader)	Griffe static analysis	TypeDoc (TypeScript compiler API)
Middle-end (model)	Project -> Module -> DocObject	Project -> Module -> DocObject
Human renderer	MkDocs (site/lib)	TypeDoc (site/lib)
Machine renderer	MCPRenderer JSON	TypeDocJsonToMCP JSON
Convention	GSDFC (Google-style docstrings)	RDFC (Google-style JSDoc)
CLI	doc-forge build/serve	doc-weaver build/serve
MCP server	docforge.servers.MCPServer	docweaver.servers.MCPServer

MCP bundle (identical shape to doc-forge)

docs/mcp/
  index.json            { project, type: "docforge-model", modules_count, source }
  nav.json              [ { module, resource: "docs://modules/<module>" } ]
  modules/<module>.json { module, content: { path, docstring, objects } }

Each object is rendered recursively as:

{ name, kind, path, signature, docstring, members? }

Resource URIs use the same docs:// scheme as doc-forge:

• docs://index
• docs://nav
• docs://modules/{module}

Module paths use dotted form (components.ResourceList) so a single URI segment matches, exactly like Python's dotted module paths.

---

Installation

npm install
npm run build

This produces the doc-weaver binary in dist/ and bin/.

---

CLI usage

# Machine-readable MCP JSON
doc-weaver build --mcp --module src/index.ts --project-name my-app

# Human-facing TypeDoc site (MkDocs parallel)
doc-weaver build --docs --module src/index.ts --project-name my-app

# Both in one pass
doc-weaver build --mcp --docs --module src/index.ts

# Serve a generated MCP bundle
doc-weaver serve --mcp --module my-app --out-dir docs/mcp

Flags:

Flag	Meaning	Default
--mcp	Emit MCP JSON bundle	–
--docs / --mkdocs / --lib	Emit the TypeDoc human site	–
--module <path> / --entry <file>	Entry point for TypeDoc	required
--project-name <name> / --name <name>	Project name	package.json name
--tsconfig <file>	tsconfig to use	auto-discovered
--out-dir <dir>	MCP output directory	docs/mcp
--out <dir>	Human docs output directory	site/lib
--plugin <name...>	Extra TypeDoc plugins	–
--strict	Fail on TypeScript errors instead of generating anyway	off

By default doc-weaver skips TypeScript error checking (skipErrorChecking), so documentation is produced even when a project has unrelated type errors. Pass --strict to make errors fatal.

--api and --wiki are reserved for parity with doc-forge and are not yet implemented.

---

Adding it to a React package

Add a script to the package's package.json (pointing at the package entry):

{
  "scripts": {
    "docs:mcp": "doc-weaver build --mcp --module index.ts --out-dir docs/mcp",
    "docs:site": "doc-weaver build --docs --module index.ts --out site/lib",
    "docs:serve": "doc-weaver serve --mcp --module my-app --out-dir docs/mcp"
  }
}

Packages in this workspace (react-openapi, react-auth, vet) export their public surface from index.ts, so a single --module index.ts documents the package. To document per-file modules, pass a directory or several entry points instead:

doc-weaver build --mcp --module src
doc-weaver build --mcp --module src/a.ts --module src/b.ts

---

Architecture

TypeScript + JSDoc
       |
  TypeDoc (loader)            -> serialized reflection JSON
       |
  TypeDocJsonToMCP (renderer) -> MCP bundle
  generateHumanDocs (renderer)-> TypeDoc HTML site

src/
  cli/          commands, mcp-utils
  loaders/      typedoc-loader (static analysis)
  models/       semantic model + TypeDoc helpers
  renderers/    mcp-renderer, human-docs, docstring, signature
  servers/      mcp-server (official MCP SDK)
templates/      typedoc.json baseline

Like doc-forge, doc-weaver is renderer-agnostic: the MCP renderer and the TypeDoc renderer never depend on each other, and no user code is executed to produce documentation semantics.

---

Convention (RDFC)

See docs/wiki/02_rdfc.md for the React Doc-forge Convention (RDFC) — Google-style JSDoc that keeps docstrings the single source of truth and makes them machine-parsable.

The hand-written docs live under docs/wiki/ and are built with MkDocs into site/wiki/ (mirroring doc-forge), while the API site is built by TypeDoc into site/lib/:

# Wiki (MkDocs) -> site/wiki/
mkdocs build -f docs/mkdocs.wiki.yml

# API site (TypeDoc) + MCP bundle for doc-weaver itself
node bin/doc-weaver.js build --mcp --docs \
  --module src --project-name doc-weaver \
  --out-dir docs/mcp --out site/lib

---

License

MIT