doc-weaver/README.md

# doc-weaver

TypeScript documentation compiler that mirrors [`doc-forge`](../doc-forge).

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

- **Humans** – a [TypeDoc](https://typedoc.org) 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

```bash
npm install
npm run build
```

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

---

## CLI usage

```bash
# 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):

```jsonc
{
  "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:

```bash
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`](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/`:

```bash
# 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