@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,79 @@
+# @rarusoft/dendrite-wiki
+
+> The markdown-wiki adapter for [`@rarusoft/dendrite-memory`](../memory/).
+
+A VitePress-rendered living wiki that pairs with the AI memory brain. Implements `CanonicalTarget` against `docs/wiki/`, owns the wiki page store / lint / search / synthesis / maintenance review surface / browser-side review bridge / API reference generator / chart insertion / telemetry pipeline / doctor health check.
+
+## Status
+
+`0.1.0-alpha.0` — publish-prep alpha. The package is now public-publishable from the monorepo workflow and pairs with `@rarusoft/dendrite-memory`. Publish both extracted packages under the same dist-tag during the first alpha pass. See the [Library Extraction Roadmap](../../docs/wiki/library-extraction-roadmap.md) for the migration story.
+
+## What's inside
+
+- **`store`** — wiki page CRUD + lint + claims + context briefing. The wiki-tier counterpart of the brain's `memory-store`.
+- **`canonical-target`** — `WikiCanonicalTarget` implementation of the brain's interface. Self-registers as the default at module load.
+- **`search-index`** — wiki search ranking (re-uses the brain's tokenizer).
+- **`context-cache`** — `wiki_context` LRU+TTL cache; subscribes to brain mutation events so writes don't serve stale briefings.
+- **`maintenance-actions` / `maintenance-inbox` / `maintenance-runner`** — the Review Board's verb side.
+- **`page-drift` / `contradicts-shipped-memory`** — wiki lint rules that compare prose to shipped memories.
+- **`page-inbox` / `librarian`** — per-page and multi-category audit aggregators.
+- **`review-bridge`** — HTTP bridge for the browser-viewable Review Board.
+- **`api-reference` + `api-extractor/`** — multi-language API doc generator (TypeScript / tree-sitter / Python).
+- **`chart-insert` / `chart-prompts`** — Mermaid chart authoring.
+- **`wiki-synthesis`** — LLM-assisted wiki narration (claims, guidance, proposals, drift resolution, chart synthesis, memory auto-clean decisions).
+- **`telemetry` / `telemetry-defaults` / `telemetry-report`** — opt-in aggregate-counters upload pipeline.
+- **`benchmark` / `benchmark-events`** — wiki benchmark snapshots and per-session event capture.
+- **`report-export` / `binder-export`** — HTML report and printable binder exports.
+- **`doctor`** — health-check audit.
+- **`diff-context`** — git diff → relevant memories + skills aggregator.
+- **`generated-docs`** — derived artifact refresher (search index, maintenance-inbox.json, etc.).
+- **`i18n`** — translation table.
+
+## Quickstart
+
+```ts
+import '@rarusoft/dendrite-wiki'; // auto-registers WikiCanonicalTarget on @rarusoft/dendrite-memory
+
+import { rememberProjectMemory, applyProjectMemoryPromotion } from '@rarusoft/dendrite-memory';
+import { listWikiPages, readWikiPage, buildWikiContext } from '@rarusoft/dendrite-wiki';
+
+// Brain promotion now resolves against the wiki adapter — promoted memories
+// land as markdown bullets in the appropriate docs/wiki/<slug>.md page with a
+// provenance line per record.
+const memory = await rememberProjectMemory({ /* … */ });
+await applyProjectMemoryPromotion({ memoryIds: [memory.id] });
+
+// The wiki tier itself: list pages, read raw content, build the briefing the
+// MCP server returns from `wiki_context`.
+const pages = await listWikiPages();
+const briefing = await buildWikiContext({ query: 'what auth pattern do we use?' });
+```
+
+The wiki adapter expects a `docs/wiki/` markdown surface in the process cwd. To run against a different root, change directory before importing — `store.ts` captures the wiki root at module-init time via `process.cwd()` (a known tradeoff documented in the architecture page).
+
+## Design contract
+
+The wiki tier reaches the brain ONLY through the `@rarusoft/dendrite-memory` barrel. One contract test in the parent monorepo pins this at `npm test` time:
+
+- `test/wiki-no-brain-internals.test.ts` — every `.ts` file under `packages/wiki/src/` must reach brain symbols via `@rarusoft/dendrite-memory`. Deep imports into `packages/memory/src/` internals fail the test.
+
+`npm run build -w @rarusoft/dendrite-wiki` succeeds standalone (proves the same at the type-resolution level, with `@rarusoft/dendrite-memory` declared as a workspace dependency).
+
+## How wiki ↔ brain talk
+
+Two inversions established during Phase 4 of the extraction:
+
+- **Tokenizer.** The brain owns `tokenizeSearchQuery`. The wiki re-exports it from `@rarusoft/dendrite-memory` so the two share tokenization rules without the wiki being a brain dependency.
+- **Cache invalidation.** When the brain mutates, it emits an `onMemoryMutation` event. The wiki's `context-cache.ts` registers its invalidator on import. No brain → wiki reverse calls.
+
+`CanonicalTarget` uses module-level default-target DI: `WikiCanonicalTarget` registers itself as the brain's default canonical target via a top-level `setDefaultCanonicalTarget(createWikiCanonicalTarget())` side effect, run on `canonical-target.js` load. Because the barrel re-exports `canonical-target.js` first, `import { anything } from '@rarusoft/dendrite-wiki'` is enough to wire the brain DI.
+
+## Related
+
+- [`@rarusoft/dendrite-memory`](../memory/) — the AI memory brain core.
+- [Dendrite Wiki MCP](https://github.com/mfillalan/dendrite-wiki-mcp) — the umbrella product.
+- [Library Extraction Roadmap](../../docs/wiki/library-extraction-roadmap.md) — the migration story.
+
+## License
+
+Apache-2.0.

package/dist/api-extractor/extract.js

@@ -0,0 +1,269 @@
+/**
+ * Extracts an `ApiFileReference` from a single TypeScript source file.
+ *
+ * Uses the TypeScript Compiler API directly (no typedoc, no extra dependencies — the
+ * `typescript` package is already a devDep). Parses the file with `ts.createSourceFile`
+ * and `setParentNodes: true` so `Node.getText()`, the printer, and parent-walking helpers
+ * all work without a full Program. JSDoc is read off `node.jsDoc[last]` directly because
+ * Program-loaded source files don't set parent pointers in a way `getJSDocCommentsAndTags`
+ * can use; the last entry of the array is the immediately-preceding doc block.
+ *
+ * Each top-level exported declaration becomes one `ApiSymbol`. Function default values
+ * are stripped from rendered signatures (implementation detail, not type contract).
+ * Interfaces render with their full member body via the TS printer. `@internal`-tagged
+ * exports are filtered. The renderer in `./render.ts` formats the result as markdown.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+export function extractApiFileReference(sourcePath, options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const absolute = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(rootDir, sourcePath);
+    const relative = toForwardSlash(path.relative(rootDir, absolute));
+    // Parse the file directly with parent pointers enabled. We don't need a Program for A1 —
+    // there's no type-checker work, just AST traversal of declarations and JSDoc. Setting parent
+    // pointers makes ts.Node.getText() and printNode work without a separate setup step.
+    const text = readFileSync(absolute, 'utf8');
+    const sourceFile = ts.createSourceFile(absolute, text, ts.ScriptTarget.ES2022, /*setParentNodes*/ true, ts.ScriptKind.TS);
+    const symbols = [];
+    for (const statement of sourceFile.statements) {
+        const extracted = extractSymbolsFromStatement(statement, sourceFile);
+        for (const symbol of extracted) {
+            if (isInternal(symbol)) {
+                continue;
+            }
+            symbols.push(symbol);
+        }
+    }
+    symbols.sort((left, right) => left.sourceLine - right.sourceLine);
+    return {
+        sourcePath: relative,
+        moduleSlug: deriveModuleSlug(relative),
+        symbols,
+        fileDocComment: extractFileDocComment(sourceFile)
+    };
+}
+function extractSymbolsFromStatement(statement, sourceFile) {
+    if (!hasExportModifier(statement)) {
+        return [];
+    }
+    if (ts.isFunctionDeclaration(statement) && statement.name) {
+        return [buildSymbol(statement, statement.name.text, 'function', renderFunctionSignature(statement), sourceFile)];
+    }
+    if (ts.isClassDeclaration(statement) && statement.name) {
+        return [buildSymbol(statement, statement.name.text, 'class', renderClassSignature(statement), sourceFile)];
+    }
+    if (ts.isInterfaceDeclaration(statement)) {
+        return [buildSymbol(statement, statement.name.text, 'interface', renderInterfaceSignature(statement), sourceFile)];
+    }
+    if (ts.isTypeAliasDeclaration(statement)) {
+        return [buildSymbol(statement, statement.name.text, 'type-alias', renderTypeAliasSignature(statement), sourceFile)];
+    }
+    if (ts.isEnumDeclaration(statement)) {
+        return [buildSymbol(statement, statement.name.text, 'enum', renderEnumSignature(statement), sourceFile)];
+    }
+    if (ts.isVariableStatement(statement)) {
+        const out = [];
+        for (const decl of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(decl.name)) {
+                continue;
+            }
+            out.push(buildSymbol(statement, decl.name.text, 'variable', renderVariableSignature(statement, decl), sourceFile));
+        }
+        return out;
+    }
+    return [];
+}
+function buildSymbol(jsDocCarrier, name, kind, signature, sourceFile) {
+    const { docComment, tags } = parseJSDoc(jsDocCarrier);
+    const sourceLine = sourceFile.getLineAndCharacterOfPosition(jsDocCarrier.getStart(sourceFile)).line + 1;
+    const isDeprecated = tags.some((tag) => tag.name === 'deprecated');
+    return {
+        name,
+        kind,
+        signature,
+        docComment,
+        tags,
+        sourceLine,
+        isDeprecated
+    };
+}
+function hasExportModifier(node) {
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    if (!modifiers) {
+        return false;
+    }
+    return modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+function parseJSDoc(node) {
+    // ts.getJSDocCommentsAndTags walks the parent chain, but Program-created source files do
+    // not have parent pointers set, so it returns nothing. Read .jsDoc directly instead. The
+    // parser attaches one JSDoc node per JSDoc block preceding the declaration; the LAST entry
+    // is the immediately-preceding one, which is the "owning" doc for the declaration.
+    const jsDocList = node.jsDoc;
+    if (!jsDocList || jsDocList.length === 0) {
+        return { docComment: null, tags: [] };
+    }
+    const owning = jsDocList[jsDocList.length - 1];
+    const body = renderJSDocComment(owning.comment).trim();
+    const tags = [];
+    if (owning.tags) {
+        for (const tag of owning.tags) {
+            tags.push(parseTag(tag));
+        }
+    }
+    return { docComment: body.length > 0 ? body : null, tags };
+}
+function parseTag(tag) {
+    const name = tag.tagName.text;
+    const text = renderJSDocComment(tag.comment).trim();
+    if (ts.isJSDocParameterTag(tag)) {
+        return {
+            name,
+            text,
+            paramName: ts.isIdentifier(tag.name) ? tag.name.text : tag.name.getText()
+        };
+    }
+    return { name, text };
+}
+function renderJSDocComment(comment) {
+    if (!comment) {
+        return '';
+    }
+    if (typeof comment === 'string') {
+        return normalizeLineEndings(comment);
+    }
+    const joined = comment
+        .map((part) => {
+        if (part.kind === ts.SyntaxKind.JSDocText) {
+            return part.text;
+        }
+        if (part.kind === ts.SyntaxKind.JSDocLink || part.kind === ts.SyntaxKind.JSDocLinkCode || part.kind === ts.SyntaxKind.JSDocLinkPlain) {
+            const link = part;
+            const targetName = link.name ? link.name.getText() : '';
+            const linkText = link.text ?? '';
+            const label = linkText.trim().length > 0 ? `${targetName} ${linkText.trim()}`.trim() : targetName;
+            return `{@link ${label}}`;
+        }
+        return '';
+    })
+        .join('');
+    return normalizeLineEndings(joined);
+}
+/**
+ * Normalize CRLF / lone CR to LF in extracted text. Source files checked out on Windows
+ * with `core.autocrlf=true` come back from disk with CRLF, which would otherwise leak
+ * into the extracted JSDoc/TSDoc text fields and produce platform-dependent fixtures
+ * and pages. Normalizing at the extraction boundary keeps every downstream artifact
+ * (`ApiFileReference`, rendered markdown, manifest content hash) byte-identical across
+ * Windows / macOS / Linux checkouts.
+ */
+function normalizeLineEndings(text) {
+    return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+function isInternal(symbol) {
+    return symbol.tags.some((tag) => tag.name === 'internal');
+}
+function extractFileDocComment(sourceFile) {
+    const fullText = sourceFile.getFullText();
+    const ranges = ts.getLeadingCommentRanges(fullText, 0);
+    if (!ranges) {
+        return null;
+    }
+    for (const range of ranges) {
+        if (range.kind !== ts.SyntaxKind.MultiLineCommentTrivia) {
+            continue;
+        }
+        const raw = fullText.slice(range.pos, range.end);
+        if (!raw.startsWith('/**')) {
+            continue;
+        }
+        return cleanBlockComment(raw);
+    }
+    return null;
+}
+function cleanBlockComment(raw) {
+    const inner = raw.replace(/^\/\*\*/, '').replace(/\*\/$/, '');
+    const lines = inner.split(/\r?\n/).map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+    while (lines.length > 0 && lines[0].trim() === '') {
+        lines.shift();
+    }
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
+        lines.pop();
+    }
+    return lines.join('\n').trim();
+}
+// --- signature renderers -----------------------------------------------------
+const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed, removeComments: true, omitTrailingSemicolon: true });
+function renderFunctionSignature(node) {
+    const typeParams = renderTypeParameters(node.typeParameters);
+    const params = (node.parameters ?? []).map((p) => renderParameter(p)).join(', ');
+    const returnType = node.type ? `: ${printNode(node.type)}` : '';
+    return `function ${node.name?.text ?? ''}${typeParams}(${params})${returnType}`;
+}
+function renderParameter(node) {
+    // Strip default values from the rendered signature — they're implementation detail, not
+    // part of the public type contract, and they add visual noise to the API page. Preserve
+    // rest tokens, optionals, and the type annotation.
+    const dotDotDot = node.dotDotDotToken ? '...' : '';
+    const name = node.name.getText();
+    const question = node.questionToken ? '?' : '';
+    const typeAnnotation = node.type ? `: ${printNode(node.type)}` : '';
+    return `${dotDotDot}${name}${question}${typeAnnotation}`;
+}
+function renderClassSignature(node) {
+    const typeParams = renderTypeParameters(node.typeParameters);
+    const heritage = (node.heritageClauses ?? [])
+        .map((clause) => printNode(clause).trim())
+        .join(' ');
+    const heritageSuffix = heritage.length > 0 ? ` ${heritage}` : '';
+    return `class ${node.name?.text ?? ''}${typeParams}${heritageSuffix}`;
+}
+function renderInterfaceSignature(node) {
+    // Print the full interface including its members. An empty `interface Foo` line on its
+    // own is useless on the API page; readers care about the shape of the type, which is the
+    // member list. The TS printer handles formatting + indentation cleanly. Strip the leading
+    // `export` modifier — every symbol on an API reference page is exported by definition.
+    return printNode(node).replace(/^export\s+/, '');
+}
+function renderTypeAliasSignature(node) {
+    const typeParams = renderTypeParameters(node.typeParameters);
+    return `type ${node.name.text}${typeParams} = ${printNode(node.type)}`;
+}
+function renderEnumSignature(node) {
+    const members = node.members.map((member) => `  ${printNode(member)}`).join(',\n');
+    return `enum ${node.name.text} {\n${members}\n}`;
+}
+function renderVariableSignature(statement, decl) {
+    const flags = statement.declarationList.flags;
+    const keyword = flags & ts.NodeFlags.Const ? 'const' : flags & ts.NodeFlags.Let ? 'let' : 'var';
+    const name = ts.isIdentifier(decl.name) ? decl.name.text : decl.name.getText();
+    const typeAnnotation = decl.type ? `: ${printNode(decl.type)}` : '';
+    return `${keyword} ${name}${typeAnnotation}`;
+}
+function renderTypeParameters(params) {
+    if (!params || params.length === 0) {
+        return '';
+    }
+    return `<${params.map((p) => printNode(p)).join(', ')}>`;
+}
+function printNode(node) {
+    const sourceFile = node.getSourceFile();
+    if (sourceFile) {
+        return printer.printNode(ts.EmitHint.Unspecified, node, sourceFile);
+    }
+    // Fallback for synthesized nodes: build a transient SourceFile.
+    const transientFile = ts.createSourceFile('__transient__.ts', '', ts.ScriptTarget.ES2022, false, ts.ScriptKind.TS);
+    return printer.printNode(ts.EmitHint.Unspecified, node, transientFile);
+}
+function deriveModuleSlug(relativeSourcePath) {
+    const trimmed = relativeSourcePath.replace(/\\/g, '/').replace(/^\.\//, '');
+    const withoutExt = trimmed.replace(/\.[cm]?tsx?$/i, '');
+    const stripped = withoutExt
+        .replace(/^src\//, '')
+        .replace(/^packages\/([^/]+)\/src\//, '$1/');
+    return `api/${stripped}`;
+}
+function toForwardSlash(value) {
+    return value.replace(/\\/g, '/');
+}

package/dist/api-extractor/language-extractor.js

@@ -0,0 +1,15 @@
+/**
+ * Language pluggability surface for the API reference generator.
+ *
+ * The orchestrator (`refreshApiReference`) walks a registered list of `LanguageExtractor`
+ * implementations and dispatches to the first one whose `detect(rootDir)` returns true.
+ * TypeScript is the only built-in today (`./typescript-extractor.ts`); future Python/Rust/Go
+ * support is a drop-in module implementing this same interface — no orchestrator changes.
+ *
+ * The interface is deliberately small and async-friendly so a Python extractor that shells
+ * out to `pdoc --output json` or a Rust extractor wrapping `rustdoc --output-format json`
+ * can implement it without contortion. It is also free of TypeScript-specific shapes;
+ * everything the orchestrator needs is the language-agnostic `ApiFileReference` from
+ * `./types.ts`. Phase A7 of the API reference roadmap establishes this layering.
+ */
+export {};