Documentation Synthesis

Documentation Synthesis Area

Overview

The documentation synthesis subsystem transforms repository metadata into polished GitHub wiki pages. It stitches together repository structure, prompt templates, LLM integrations, and wiki persistence so that every run can generate or refresh Home, Architecture, and area-specific documentation with consistent formatting and content depth.

Key Components

• WikiGenerator (src/wiki-generator.ts:24) orchestrates documentation generation across home, architecture, and area pages using the Anthropic Agent SDK or CLI providers.
• loadPrompt (src/prompt-loader.ts:10) injects runtime variables into Markdown prompt templates that steer LLM output.
• createQueryFunction (src/query-factory.ts:25) selects the appropriate LLM transport (Agent SDK, Claude CLI, Codex CLI, or mock) and wraps it in a streaming Query.
• TemplateRenderer (src/template-renderer.ts:29) loads Markdown templates, applies overrides, and caches results for reuse.
• GitHubWikiWriter (src/github/github-wiki-writer.ts:34) checks out the wiki repo, writes generated pages, maintains the sidebar, and commits/pushes updates.
• Prompt and template assets under src/prompts/ and src/templates/ define the deterministic scaffolding that each generated page must follow.

How It Works

• Crawl results and repo metadata are passed into WikiGenerator, which formats the file tree (formatRepoStructure) and loads the appropriate prompt variant (generateHomePage, generateArchitecturalOverview, or generateAreaDocumentation).
• Prompts are hydrated by loadPrompt, then executed through the QueryFunction determined by createQueryFunction; responses stream back from the LLM provider and are normalized (collectResponseText, stripFenceWrappers, ensureHeading).
• Page-specific post-processing ensures required sections exist (e.g., ensureArchitectureOutline adds canonical headings and Mermaid diagrams) before rendering through TemplateRenderer.
• Generated Markdown is assembled into a map of page name → content; when persistence is enabled, GitHubWikiWriter.writeDocumentation prepares the wiki repo, writes changed pages, regenerates _Sidebar.md, commits, and pushes.
• Future roadmap hooks (updateDocumentationFromDiff, reviewDocumentation) are placeholders for diff-aware updates and CI review workflows.

Important Functions/Classes

• WikiGenerator.generateHomePage (src/wiki-generator.ts:360)
  Builds the Home prompt, dispatches it to the LLM, normalizes headings, and renders the home template. Supports incremental updates when incrementalDocs is enabled and an existing doc is provided.
• WikiGenerator.generateArchitecturalOverview (src/wiki-generator.ts:413)
  Mirrors the home workflow but enforces an architecture outline, injects fallback sections, and guarantees a Mermaid diagram via ensureArchitectureOutline.
• WikiGenerator.generateAreaDocumentation (src/wiki-generator.ts:566)
  Reads relevant files, embeds their contents into the area prompt, processes the LLM response, and writes through the area template with per-area variants (slugged under areas/).
• WikiGenerator.identifyRelevantFiles (src/wiki-generator.ts:501)
  Delegates to the LLM to choose files per architectural area, validates they exist, and deduplicates the list—critical for limiting prompt payloads.
• createQueryFunction (src/query-factory.ts:25)
  Routes invocation to Agent SDK, Claude CLI, Codex CLI, or mock pipelines, logging context for debugging and handling provider-specific streaming quirks.
• TemplateRenderer.render (src/template-renderer.ts:42)
  Resolves variant-specific templates, caches the result, and interpolates {{placeholders}} across the final Markdown.
• GitHubWikiWriter.writeDocumentation (src/github/github-wiki-writer.ts:69)
  Prepares the wiki repository, optionally cleans legacy Markdown on “fresh” runs, writes updated pages, keeps _Sidebar.md synchronized, commits, and pushes via GitRepositoryManager.

Developer Notes

• WikiGenerator.escapeRegExp (src/wiki-generator.ts:146) replaces special characters with a static token; confirm this behavior before relying on regex escaping in custom headings.
• Ensure Config supplies apiKey, baseURL, documentationDepth, and templateDir when needed; missing values fall back to defaults but may affect prompt quality.
• Prompt variables are simple string replacements; guard against introducing {{ or }} in template content without placeholders.
• External CLI providers (claude, codex) must be installed and on PATH; the factory surfaces ENOENT errors with actionable messages.
• TemplateRenderer caches file hits; restart the process or clear the cache when editing templates during development.
• GitHubWikiWriter assumes the wiki repo can be cloned/pushed with provided credentials; test with mode: 'fresh' and cleanupOnFresh in sandbox environments to avoid residual content.
• Unimplemented methods (updateDocumentationFromDiff, reviewDocumentation) are placeholders; guard callers until roadmap features land.

Usage Examples

import { createQueryFunction } from './src/query-factory.js';
import { WikiGenerator } from './src/wiki-generator.js';
import { loadRepoStructure } from './src/repo-crawler.js'; // hypothetical helper

async function generateDocs(config) {
  const repoStructure = await loadRepoStructure(config.repoPath);
  const query = createQueryFunction(config, config.repoPath);
  const generator = new WikiGenerator(query, config);

  const home = await generator.generateHomePage(repoStructure);
  const architecture = await generator.generateArchitecturalOverview(repoStructure);
  const areas = await generator.extractArchitecturalAreas(architecture);

  const pages = new Map<string, string>([
    ['Home', home],
    ['Architecture', architecture],
  ]);

  for (const area of areas) {
    const relevantFiles = await generator.identifyRelevantFiles(area, /* allFiles */ [], repoStructure);
    const areaDoc = await generator.generateAreaDocumentation(area, relevantFiles);
    pages.set(area, areaDoc);
  }

  // hand off to GitHubWikiWriter when persistence is required
  return pages;
}

import { GitHubWikiWriter } from './src/github/github-wiki-writer.js';

async function publishWiki(pages) {
  const writer = new GitHubWikiWriter({
    wikiRepoUrl: '[email protected]:org/project.wiki.git',
    localPath: './.wiki',
    commitMessage: 'Refresh docs',
    mode: 'incremental',
    cleanupOnFresh: false,
  });

  await writer.writeDocumentation(pages);
}