Add doc-weaver 0.1.0: TypeScript documentation compiler

TypeDoc + JSDoc (RDFC) compiler producing a TypeDoc site and a doc-forge-shaped MCP bundle for React/TypeScript packages. - TypeDoc loader + human-docs and MCP renderers, signature-level parameter docs and default-export surfacing - MCPServer over @modelcontextprotocol/sdk (docs://index, docs://nav, docs://modules/{module}, ping tool) - doc-weaver build / serve CLI - RDFC convention guide and hand-written wiki - packaged as @aetoskia/doc-weaver with an npm release pipeline (build-and-publish-npm + backfill-npm-from-tags)
2026-10-21 00:35:15 +05:30
parent bb3767ac15
commit aeb6e6b0f6
24 changed files with 3688 additions and 0 deletions
--- a/docs/wiki/01_overview.md
+++ b/docs/wiki/01_overview.md
@@ -0,0 +1,60 @@
+# Library Overview
+
+`doc-weaver` turns RDFC-compliant TypeScript JSDoc into maintainable reference
+documentation. It never edits source comments; it reads them, renders them, and
+assembles documentation from all available material — exactly as `doc-forge`
+does for Python docstrings.
+
+Analysis is static: source is parsed by the TypeScript compiler API via TypeDoc
+and is never executed.
+
+---
+
+## 🧭 Which Build Should You Use?
+
+| Flag                  | Source                | Output                                            |
+|-----------------------|-----------------------|---------------------------------------------------|
+| `--docs` (`--mkdocs`, `--lib`) | JSDoc comments | `site/lib/**` TypeDoc HTML (the MkDocs parallel) |
+| `--mcp`               | JSDoc comments + model | `docs/mcp/**` doc-forge-shaped JSON             |
+| `--api`               | OpenAPI spec          | reserved                                          |
+| `--wiki`              | Hand-written markdown | `docs/wiki/**` (unchanged)                        |
+
+---
+
+## 🏗️ Architecture
+
+```
+TypeScript + JSDoc
+       |
+  TypeDoc (loader)             -> serialized reflection JSON
+       |
+  TypeDocJsonToMCP (renderer)  -> MCP bundle (docs/mcp/)
+  generateHumanDocs (renderer) -> TypeDoc HTML site (site/lib/)
+```
+
+The MCP renderer and the human renderer never depend on each other: both read
+the same serialized reflections, so the machine bundle and the human site can
+never disagree about a symbol.
+
+---
+
+## 🔄 MCP bundle shape
+
+`docs/mcp/**` is a self-contained, machine-readable reference whose shape is
+byte-compatible with `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 } }
+```
+
+`doc-weaver serve --mcp --module doc-weaver` serves it over stdio. See the
+[RDFC Guide](02_rdfc.md) for how to write the JSDoc that fills it.
+
+---
+
+## ➡️ Read Next
+
+- [02 – RDFC Guide](02_rdfc.md)
--- a/docs/wiki/02_rdfc.md
+++ b/docs/wiki/02_rdfc.md
@@ -0,0 +1,173 @@
+# RDFC Guide
+
+RDFC — the **React Doc-forge Convention** — is the TypeScript counterpart to
+doc-forge's **GSDFC**. This page is the practical companion to the convention:
+how to write JSDoc so it renders correctly in the TypeDoc site **and** stays
+machine-parsable in the MCP bundle and by AI tooling.
+
+---
+
+## 🧭 Overview
+
+- Documentation is the single source of truth and lives in JSDoc comments.
+- `doc-weaver` compiles comments; it never rewrites or invents them.
+- Structure follows the TypeScript export hierarchy.
+- Every public export should have a complete and accurate JSDoc comment.
+- Types live in signatures; do not duplicate them in prose unless a tag
+  requires it.
+
+---
+
+## 📦 Module (file) level
+
+Document the file with a leading block comment. It becomes the module
+`docstring` in the MCP bundle.
+
+```ts
+/**
+ * # Resource list
+ *
+ * Renders, filters, and paginates a resource collection.
+ *
+ * ---
+ *
+ * Notes:
+ *     - Reads configuration from the OpenAPI spec.
+ *     - Pagination is server-driven.
+ */
+```
+
+---
+
+## 📦 Components
+
+Document the component function and its props. Components are classified
+automatically as `kind: "component"` (PascalCase name).
+
+```ts
+/**
+ * Render a single resource row with actions.
+ *
+ * @param props - Component props.
+ * @param props.item - The resource record to display.
+ * @param props.onSelect - Invoked when the row is selected.
+ * @returns The rendered row element.
+ *
+ * @example
+ * ```tsx
+ * <ResourceList item={record} onSelect={handleSelect} />
+ * ```
+ */
+export function ResourceList(props: ListCellProps) {
+  // ...
+}
+```
+
+---
+
+## 📦 Hooks
+
+Hooks are classified automatically as `kind: "hook"` (name starts with `use`).
+
+```ts
+/**
+ * Subscribe to server-sent events for an item.
+ *
+ * @param url - SSE endpoint, or `null` to disable.
+ * @param handlers - Event handlers keyed by event name.
+ * @returns Connection state and the latest payload.
+ *
+ * @remarks
+ * The subscription is torn down on unmount.
+ */
+export function useItemSse(url: string | null, handlers: ItemSseHandlers) {
+  // ...
+}
+```
+
+---
+
+## 📦 Types, interfaces, and members
+
+Document the type and each member. Members become nested `members` entries in
+the MCP bundle.
+
+```ts
+/**
+ * A single display field extracted from an OpenAPI schema.
+ */
+export interface FieldConfig {
+  /** Property name in the payload. */
+  name: string;
+  /** `x-edit-as: date` — edit a `date-time` field with a date input. */
+  editAs?: string;
+  /** Schema-level `default` used to seed create-form state. */
+  defaultValue?: unknown;
+}
+```
+
+---
+
+## 📦 Notes subsection grouping
+
+Group related information using labeled subsections (Markdown bold):
+
+```
+Notes:
+    **Guarantees:**
+
+        - deterministic output
+
+    **Lifecycle:**
+
+        - created during initialization
+        - reused across renders
+```
+
+---
+
+## 📦 Heading map
+
+`doc-weaver` renders JSDoc block tags into stable markdown headings so both
+TypeDoc and the MCP bundle agree:
+
+| JSDoc tag | Rendered heading |
+|-----------|------------------|
+| `@param` | `**Parameters:**` |
+| `@returns` / `@return` | `**Returns:**` |
+| `@throws` | `**Throws:**` |
+| `@example` | `**Example:**` |
+| `@deprecated` | `**Deprecated:**` |
+| `@see` | `**See also:**` |
+| `@remarks` | `**Remarks:**` |
+| *other* | `**@tag:**` |
+
+---
+
+## 📦 Mapping to output kinds
+
+| TS construct | `kind` |
+|--------------|--------|
+| interface / type alias | `interface` / `type-alias` |
+| function component (PascalCase) | `component` |
+| custom hook (`use*`) | `hook` |
+| plain function | `function` |
+| object / class member | `property` / `method` |
+| const / let / var | `variable` |
+
+An explicit `@kind` tag overrides the inferred kind.
+
+---
+
+## 🛡️ Enforcement
+
+Unlike doc-forge (which runs `pydoclint` in CI), `doc-weaver` performs no
+signature linting: TypeDoc extracts whatever JSDoc is present. Keep comments
+complete and accurate — they are the single source of truth for both the human
+site and the machine bundle.
+
+---
+
+## Related
+
+- [01 – Overview](01_overview.md)
--- a/docs/wiki/index.md
+++ b/docs/wiki/index.md
@@ -0,0 +1,55 @@
+# 🪡 doc-weaver — TypeScript Documentation Weaver
+
+`doc-weaver` is the TypeScript counterpart to `doc-forge`. It compiles
+JSDoc-annotated TypeScript into a **TypeDoc** site (the MkDocs parallel) and a
+**doc-forge-shaped MCP JSON bundle**, so React packages document themselves for
+humans and agents alike.
+
+> **Doc model:** this wiki is written for humans — guides and conventions. The
+> authoritative API contracts live in the code (JSDoc) and the machine-readable
+> bundle under `docs/mcp/`.
+
+---
+
+## 🚀 Key Features
+
+- 🧵 JSDoc extraction via TypeDoc (the TypeScript compiler API)
+- 🧬 doc-forge-compatible MCP bundle (`index.json`, `nav.json`, `modules/*.json`)
+- ⚛️ React-aware kinds — `component` (PascalCase) and `hook` (`use*`)
+- 📚 RDFC (React Doc-forge Convention) — the JSDoc parallel to GSDFC
+- 🔌 MCP server over stdio exposing `docs://index`, `docs://nav`, and
+  `docs://modules/{module}`
+
+---
+
+## 📦 Installation
+
+```bash
+npm install
+npm run build
+```
+
+This produces the `doc-weaver` binary under `bin/` and `dist/`.
+
+---
+
+## 📁 Documentation Structure
+
+| Section                                 | Description                                    |
+|-----------------------------------------|------------------------------------------------|
+| [Overview](01_overview.md)              | What doc-weaver is and how it fits             |
+| [RDFC Guide](02_rdfc.md)                | How to write RDFC-conformant JSDoc             |
+
+---
+
+## 🔗 Related Resources
+
+- **Source Code:** the `doc-weaver` repository
+- **MCP Bundle:** generated by `doc-weaver build --mcp --module src/index.ts`
+  into `docs/mcp/`
+- **Library Registry:** registered in the standards hub as `doc-weaver`
+  (MCP `:8010`)
+
+---
+
+© Aetoskia Internal — `doc-weaver` 0.1.0