@dotcontext/mcp 0.9.0

package/dist/generators/documentation/documentationGenerator.js

@@ -0,0 +1,268 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentationGenerator = void 0;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs-extra"));
+const shared_1 = require("../shared");
+const templates_1 = require("./templates");
+const guideRegistry_1 = require("./guideRegistry");
+const semantic_1 = require("../../services/semantic");
+const stack_1 = require("../../services/stack");
+const scaffoldFrontmatter_1 = require("../../types/scaffoldFrontmatter");
+const scaffoldStructures_1 = require("../shared/scaffoldStructures");
+const autoFill_1 = require("../../services/autoFill");
+/**
+ * Category mapping from document name to frontmatter category.
+ * Using SCAFFOLD_STRUCTURES as single source of truth for descriptions/titles.
+ */
+const DOC_CATEGORY_MAP = {
+    'project-overview': 'overview',
+    'architecture': 'architecture',
+    'development-workflow': 'workflow',
+    'testing-strategy': 'testing',
+    'glossary': 'glossary',
+    'data-flow': 'data-flow',
+    'security': 'security',
+    'tooling': 'tooling',
+};
+/**
+ * Get document info from scaffold structure (single source of truth)
+ */
+function getDocInfo(key) {
+    const structure = (0, scaffoldStructures_1.getScaffoldStructure)(key);
+    if (!structure || structure.fileType !== 'doc') {
+        return undefined;
+    }
+    return {
+        title: structure.title,
+        description: structure.description,
+        category: DOC_CATEGORY_MAP[key],
+    };
+}
+class DocumentationGenerator {
+    constructor(..._legacyArgs) { }
+    async generateDocumentation(repoStructure, outputDir, config = {}, verbose = false) {
+        const docsDir = path.join(outputDir, 'docs');
+        await shared_1.GeneratorUtils.ensureDirectoryAndLog(docsDir, verbose, 'Generating documentation scaffold in');
+        const snapshotService = config.semantic ? new semantic_1.SemanticSnapshotService() : null;
+        // Perform semantic analysis if enabled
+        let semantics;
+        let snapshotFingerprint;
+        if (config.semantic) {
+            shared_1.GeneratorUtils.logProgress('Running semantic analysis...', verbose);
+            this.analyzer = new semantic_1.CodebaseAnalyzer();
+            try {
+                snapshotFingerprint = await snapshotService.captureRepoFingerprint(repoStructure.rootPath);
+                semantics = await this.analyzer.analyze(repoStructure.rootPath);
+                shared_1.GeneratorUtils.logProgress(`Analyzed ${semantics.stats.totalFiles} files, found ${semantics.stats.totalSymbols} symbols in ${semantics.stats.analysisTimeMs}ms`, verbose);
+            }
+            catch (error) {
+                shared_1.GeneratorUtils.logError('Semantic analysis failed, continuing without it', error, verbose);
+            }
+        }
+        // Detect stack info for codebase map and autoFill
+        let stackInfo;
+        if (semantics || config.autoFill) {
+            try {
+                const stackDetector = new stack_1.StackDetector();
+                stackInfo = await stackDetector.detect(repoStructure.rootPath);
+            }
+            catch (error) {
+                shared_1.GeneratorUtils.logError('Stack detection failed, continuing without it', error, verbose);
+            }
+        }
+        // Persist semantic snapshot into the semantic cache
+        if (semantics) {
+            try {
+                shared_1.GeneratorUtils.logProgress('Persisting semantic snapshot...', verbose);
+                const snapshot = await snapshotService.writeSnapshot(repoStructure, {
+                    outputDir,
+                    semantics,
+                    stackInfo,
+                    repoFingerprint: snapshotFingerprint,
+                });
+                shared_1.GeneratorUtils.logProgress(`Created semantic snapshot summary at ${path.relative(outputDir, snapshot.publishedSummaryPath)}`, verbose);
+            }
+            catch (error) {
+                shared_1.GeneratorUtils.logError('Semantic snapshot generation failed, continuing without it', error, verbose);
+            }
+        }
+        // Prioritize explicitly selected docs, then filtered by project type
+        const docKeys = config.selectedDocs ?? config.filteredDocs;
+        const guidesToGenerate = (0, guideRegistry_1.getGuidesByKeys)(docKeys);
+        const context = this.buildContext(repoStructure, guidesToGenerate, semantics);
+        let created = 0;
+        // Generate README.md index (still uses template rendering for summary)
+        const readmePath = path.join(docsDir, 'README.md');
+        const readmeContent = (0, templates_1.renderIndex)(context);
+        await shared_1.GeneratorUtils.writeFileWithLogging(readmePath, readmeContent, verbose, 'Created README.md');
+        created += 1;
+        // Generate frontmatter-only files for each guide (scaffold v2)
+        for (const guide of guidesToGenerate) {
+            const docInfo = getDocInfo(guide.key);
+            if (!docInfo) {
+                continue;
+            }
+            const filename = `${guide.key}.md`;
+            const targetPath = path.join(docsDir, filename);
+            const frontmatter = (0, scaffoldFrontmatter_1.createDocFrontmatter)(guide.key, docInfo.description, docInfo.category);
+            let content = (0, scaffoldFrontmatter_1.serializeFrontmatter)(frontmatter) + '\n';
+            // Add content based on mode
+            const structure = (0, scaffoldStructures_1.getScaffoldStructure)(guide.key);
+            if (structure) {
+                if (config.autoFill && semantics) {
+                    // AutoFill: generate content from semantic analysis (no LLM needed)
+                    const autoFillService = new autoFill_1.AutoFillService();
+                    const autoFillContext = {
+                        semantics,
+                        stackInfo,
+                        repoPath: repoStructure.rootPath,
+                        topLevelDirectories: context.topLevelDirectories
+                    };
+                    content += autoFillService.fillDocumentation(guide.key, structure, autoFillContext);
+                }
+                else if (config.includeContentStubs) {
+                    // Content stubs: section headings with guidance comments
+                    content += (0, scaffoldStructures_1.serializeStructureAsMarkdown)(structure);
+                }
+            }
+            await shared_1.GeneratorUtils.writeFileWithLogging(targetPath, content, verbose, `Created ${filename}`);
+            created += 1;
+        }
+        await this.updateAgentGuideReferences(repoStructure, verbose);
+        return created;
+    }
+    buildContext(repoStructure, guides, semantics) {
+        const topLevelStats = repoStructure.topLevelDirectoryStats ?? [];
+        const topLevelDirectories = topLevelStats.length
+            ? topLevelStats.map(stat => stat.name)
+            : this.deriveTopLevelDirectories(repoStructure);
+        const directoryStats = topLevelStats.length
+            ? topLevelStats.map(stat => ({ name: stat.name, fileCount: stat.fileCount }))
+            : topLevelDirectories.map(name => ({
+                name,
+                fileCount: repoStructure.files.filter(file => file.relativePath.startsWith(`${name}/`)).length
+            }));
+        const primaryLanguages = shared_1.GeneratorUtils.getTopFileExtensions(repoStructure, 5)
+            .filter(([ext]) => !!ext)
+            .map(([extension, count]) => ({ extension, count }));
+        return {
+            repoStructure,
+            topLevelDirectories,
+            primaryLanguages,
+            directoryStats,
+            guides,
+            semantics
+        };
+    }
+    deriveTopLevelDirectories(repoStructure) {
+        const directorySet = new Set();
+        repoStructure.directories.forEach(dir => {
+            const [firstSegment] = dir.relativePath.split(/[\\/]/).filter(Boolean);
+            if (firstSegment) {
+                directorySet.add(firstSegment);
+            }
+        });
+        return Array.from(directorySet).sort();
+    }
+    async updateAgentGuideReferences(repoStructure, verbose) {
+        const repoRoot = repoStructure.rootPath;
+        const agentGuidePath = path.join(repoRoot, 'AGENTS.md');
+        try {
+            const exists = await fs.pathExists(agentGuidePath);
+            if (!exists) {
+                const template = this.createDefaultAgentGuide(repoStructure);
+                await fs.writeFile(agentGuidePath, template, 'utf-8');
+                shared_1.GeneratorUtils.logProgress('Created AGENTS.md using the agents.md example starter.', verbose);
+                return;
+            }
+            const content = await fs.readFile(agentGuidePath, 'utf-8');
+            const docsReference = '.context/docs/README.md';
+            const agentsReference = '.context/agents/README.md';
+            if (content.includes(docsReference) && content.includes(agentsReference)) {
+                return;
+            }
+            const referencesBlock = `\n## AI Context References\n- Documentation index: \`${docsReference}\`\n- Agent playbooks: \`${agentsReference}\`\n`;
+            const updatedContent = `${content.trimEnd()}${referencesBlock}\n`;
+            await fs.writeFile(agentGuidePath, updatedContent, 'utf-8');
+            shared_1.GeneratorUtils.logProgress('Linked AGENTS.md to generated docs and agent indexes.', verbose);
+        }
+        catch (error) {
+            shared_1.GeneratorUtils.logError('Failed to update AGENTS.md with documentation references', error, verbose);
+        }
+    }
+    createDefaultAgentGuide(repoStructure) {
+        const directories = (repoStructure.topLevelDirectoryStats?.length
+            ? repoStructure.topLevelDirectoryStats.map(stat => stat.name)
+            : this.deriveTopLevelDirectories(repoStructure)).filter(Boolean);
+        const directorySection = directories.length
+            ? directories
+                .slice(0, 8)
+                .map(dir => `- \`${dir}/\` — explain what lives here and when agents should edit it.`)
+                .join('\n')
+            : '- Document the major directories so agents know where to work.';
+        return `# AGENTS.md
+
+## Dev environment tips
+- Install dependencies with \`npm install\` before running scaffolds.
+- Use \`npm run dev\` for the interactive TypeScript session that powers local experimentation.
+- Run \`npm run build\` to refresh the CommonJS bundle in \`dist/\` before shipping changes.
+- Store generated artefacts in \`.context/\` so reruns stay deterministic.
+
+## Testing instructions
+- Execute \`npm run test\` to run the Jest suite.
+- Append \`-- --watch\` while iterating on a failing spec.
+- Trigger \`npm run build && npm run test\` before opening a PR to mimic CI.
+- Add or update tests alongside any generator or CLI changes.
+
+## PR instructions
+- Follow Conventional Commits (for example, \`feat(scaffolding): add doc links\`).
+- Cross-link new scaffolds in \`docs/README.md\` and \`agents/README.md\` so future agents can find them.
+- Attach sample CLI output or generated markdown when behaviour shifts.
+- Confirm the built artefacts in \`dist/\` match the new source changes.
+
+## Repository map
+${directorySection}
+
+## AI Context References
+- Documentation index: \`.context/docs/README.md\`
+- Agent playbooks: \`.context/agents/README.md\`
+- Contributor guide: \`CONTRIBUTING.md\`
+`;
+    }
+}
+exports.DocumentationGenerator = DocumentationGenerator;
+//# sourceMappingURL=documentationGenerator.js.map

package/dist/generators/documentation/documentationGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentationGenerator.js","sourceRoot":"","sources":["../../../src/generators/documentation/documentationGenerator.ts"],"names":[],"mappings":"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"}

package/dist/generators/documentation/guideRegistry.d.ts

@@ -0,0 +1,6 @@
+import { GuideMeta } from './templates/types';
+export declare const DOCUMENT_GUIDES: GuideMeta[];
+export declare const DOCUMENT_GUIDE_KEYS: string[];
+export declare function getGuidesByKeys(keys?: string[]): GuideMeta[];
+export declare function getDocFilesByKeys(keys?: string[]): Set<string> | undefined;
+//# sourceMappingURL=guideRegistry.d.ts.map

package/dist/generators/documentation/guideRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guideRegistry.d.ts","sourceRoot":"","sources":["../../../src/generators/documentation/guideRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,eAAO,MAAM,eAAe,EAAE,SAAS,EAiDtC,CAAC;AAEF,eAAO,MAAM,mBAAmB,UAA0C,CAAC;AAE3E,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAQ5D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,CAQ1E"}

package/dist/generators/documentation/guideRegistry.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCUMENT_GUIDE_KEYS = exports.DOCUMENT_GUIDES = void 0;
+exports.getGuidesByKeys = getGuidesByKeys;
+exports.getDocFilesByKeys = getDocFilesByKeys;
+exports.DOCUMENT_GUIDES = [
+    {
+        key: 'project-overview',
+        title: 'Project Overview',
+        file: 'project-overview.md',
+        primaryInputs: 'Roadmap, README, stakeholder notes'
+    },
+    {
+        key: 'architecture',
+        title: 'Architecture Notes',
+        file: 'architecture.md',
+        primaryInputs: 'ADRs, service boundaries, dependency graphs'
+    },
+    {
+        key: 'development-workflow',
+        title: 'Development Workflow',
+        file: 'development-workflow.md',
+        primaryInputs: 'Branching rules, CI config, contributing guide'
+    },
+    {
+        key: 'testing-strategy',
+        title: 'Testing Strategy',
+        file: 'testing-strategy.md',
+        primaryInputs: 'Test configs, CI gates, known flaky suites'
+    },
+    {
+        key: 'glossary',
+        title: 'Glossary & Domain Concepts',
+        file: 'glossary.md',
+        primaryInputs: 'Business terminology, user personas, domain rules'
+    },
+    {
+        key: 'data-flow',
+        title: 'Data Flow & Integrations',
+        file: 'data-flow.md',
+        primaryInputs: 'System diagrams, integration specs, queue topics'
+    },
+    {
+        key: 'security',
+        title: 'Security & Compliance Notes',
+        file: 'security.md',
+        primaryInputs: 'Auth model, secrets management, compliance requirements'
+    },
+    {
+        key: 'tooling',
+        title: 'Tooling & Productivity Guide',
+        file: 'tooling.md',
+        primaryInputs: 'CLI scripts, IDE configs, automation workflows'
+    }
+];
+exports.DOCUMENT_GUIDE_KEYS = exports.DOCUMENT_GUIDES.map(guide => guide.key);
+function getGuidesByKeys(keys) {
+    if (!keys || keys.length === 0) {
+        return exports.DOCUMENT_GUIDES;
+    }
+    const set = new Set(keys);
+    const filtered = exports.DOCUMENT_GUIDES.filter(guide => set.has(guide.key));
+    return filtered.length > 0 ? filtered : exports.DOCUMENT_GUIDES;
+}
+function getDocFilesByKeys(keys) {
+    if (!keys || keys.length === 0) {
+        return undefined;
+    }
+    const files = exports.DOCUMENT_GUIDES
+        .filter(guide => keys.includes(guide.key))
+        .map(guide => guide.file);
+    return files.length ? new Set(files) : undefined;
+}
+//# sourceMappingURL=guideRegistry.js.map

package/dist/generators/documentation/guideRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guideRegistry.js","sourceRoot":"","sources":["../../../src/generators/documentation/guideRegistry.ts"],"names":[],"mappings":";;;AAuDA,0CAQC;AAED,8CAQC;AAvEY,QAAA,eAAe,GAAgB;IAC1C;QACE,GAAG,EAAE,kBAAkB;QACvB,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,qBAAqB;QAC3B,aAAa,EAAE,oCAAoC;KACpD;IACD;QACE,GAAG,EAAE,cAAc;QACnB,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,iBAAiB;QACvB,aAAa,EAAE,6CAA6C;KAC7D;IACD;QACE,GAAG,EAAE,sBAAsB;QAC3B,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,yBAAyB;QAC/B,aAAa,EAAE,gDAAgD;KAChE;IACD;QACE,GAAG,EAAE,kBAAkB;QACvB,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,qBAAqB;QAC3B,aAAa,EAAE,4CAA4C;KAC5D;IACD;QACE,GAAG,EAAE,UAAU;QACf,KAAK,EAAE,4BAA4B;QACnC,IAAI,EAAE,aAAa;QACnB,aAAa,EAAE,mDAAmD;KACnE;IACD;QACE,GAAG,EAAE,WAAW;QAChB,KAAK,EAAE,0BAA0B;QACjC,IAAI,EAAE,cAAc;QACpB,aAAa,EAAE,kDAAkD;KAClE;IACD;QACE,GAAG,EAAE,UAAU;QACf,KAAK,EAAE,6BAA6B;QACpC,IAAI,EAAE,aAAa;QACnB,aAAa,EAAE,yDAAyD;KACzE;IACD;QACE,GAAG,EAAE,SAAS;QACd,KAAK,EAAE,8BAA8B;QACrC,IAAI,EAAE,YAAY;QAClB,aAAa,EAAE,gDAAgD;KAChE;CACF,CAAC;AAEW,QAAA,mBAAmB,GAAG,uBAAe,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAE3E,SAAgB,eAAe,CAAC,IAAe;IAC7C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,uBAAe,CAAC;IACzB,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,QAAQ,GAAG,uBAAe,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACrE,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,uBAAe,CAAC;AAC1D,CAAC;AAED,SAAgB,iBAAiB,CAAC,IAAe;IAC/C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,uBAAe;SAC1B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;SACzC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACnD,CAAC"}

package/dist/generators/documentation/index.d.ts

@@ -0,0 +1,4 @@
+export { DocumentationGenerator } from './documentationGenerator';
+export { CodebaseMapGenerator } from './codebaseMapGenerator';
+export type { CodebaseMap, CodebaseMapOptions, KeyFile, NavigationHints, SemanticSnapshotMetadata } from './codebaseMapGenerator';
+//# sourceMappingURL=index.d.ts.map

package/dist/generators/documentation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/generators/documentation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/generators/documentation/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodebaseMapGenerator = exports.DocumentationGenerator = void 0;
+var documentationGenerator_1 = require("./documentationGenerator");
+Object.defineProperty(exports, "DocumentationGenerator", { enumerable: true, get: function () { return documentationGenerator_1.DocumentationGenerator; } });
+var codebaseMapGenerator_1 = require("./codebaseMapGenerator");
+Object.defineProperty(exports, "CodebaseMapGenerator", { enumerable: true, get: function () { return codebaseMapGenerator_1.CodebaseMapGenerator; } });
+//# sourceMappingURL=index.js.map

package/dist/generators/documentation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/generators/documentation/index.ts"],"names":[],"mappings":";;;AAAA,mEAAkE;AAAzD,gIAAA,sBAAsB,OAAA;AAC/B,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA"}

package/dist/generators/documentation/templates/common.d.ts

@@ -0,0 +1,42 @@
+import { DirectoryStat, DocumentationTemplateContext } from './types';
+import type { ExtractedSymbol } from '../../../services/semantic/types';
+/**
+ * Wrap template content with YAML front matter for status detection.
+ * This allows instant detection of unfilled files by reading only the first line.
+ */
+export declare function wrapWithFrontMatter(content: string, options?: {
+    name?: string;
+    description?: string;
+}): string;
+export declare function formatDirectoryList(context: DocumentationTemplateContext, includePlaceholders: boolean): string;
+export declare function buildDocumentMapTable(guides: DocumentationTemplateContext['guides']): string;
+export declare function formatDirectoryStats(stats: DirectoryStat[]): string;
+export declare function formatInlineDirectoryList(directories: string[]): string;
+/**
+ * Format a symbol as a markdown link with line number
+ * Output: [`SymbolName`](src/path/file.ts#L42)
+ */
+export declare function formatSymbolRef(symbol: ExtractedSymbol, repoRoot: string): string;
+/**
+ * Format a file:line reference (non-link format)
+ * Output: src/path/file.ts:42
+ */
+export declare function formatCodeLocation(filePath: string, line: number, repoRoot: string): string;
+/**
+ * Format a file path as a markdown link with line number
+ * Output: [`file.ts`](src/path/file.ts#L42)
+ */
+export declare function formatFileRef(filePath: string, line: number, repoRoot: string, displayName?: string): string;
+/**
+ * Build a markdown table of symbols with links
+ */
+export declare function buildSymbolTable(symbols: ExtractedSymbol[], repoRoot: string, columns?: ('name' | 'kind' | 'location' | 'description')[]): string;
+/**
+ * Build a bullet list of symbols with links
+ */
+export declare function buildSymbolList(symbols: ExtractedSymbol[], repoRoot: string, includeKind?: boolean): string;
+/**
+ * Group symbols by their containing directory
+ */
+export declare function groupSymbolsByDirectory(symbols: ExtractedSymbol[], repoRoot: string): Map<string, ExtractedSymbol[]>;
+//# sourceMappingURL=common.d.ts.map

package/dist/generators/documentation/templates/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/common.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAExE;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,MAAM,CAUR;AAWD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,4BAA4B,EACrC,mBAAmB,EAAE,OAAO,GAC3B,MAAM,CAmBR;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,4BAA4B,CAAC,QAAQ,CAAC,GAAG,MAAM,CAG5F;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,CAQnE;AAED,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAMvE;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,MAAM,GACf,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,EAAE,EAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,CAAC,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC,EAAiC,GACvF,MAAM,CAkCR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EAAE,EAC1B,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,OAAc,GAC1B,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,eAAe,EAAE,EAC1B,QAAQ,EAAE,MAAM,GACf,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAYhC"}

package/dist/generators/documentation/templates/common.js

@@ -0,0 +1,194 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapWithFrontMatter = wrapWithFrontMatter;
+exports.formatDirectoryList = formatDirectoryList;
+exports.buildDocumentMapTable = buildDocumentMapTable;
+exports.formatDirectoryStats = formatDirectoryStats;
+exports.formatInlineDirectoryList = formatInlineDirectoryList;
+exports.formatSymbolRef = formatSymbolRef;
+exports.formatCodeLocation = formatCodeLocation;
+exports.formatFileRef = formatFileRef;
+exports.buildSymbolTable = buildSymbolTable;
+exports.buildSymbolList = buildSymbolList;
+exports.groupSymbolsByDirectory = groupSymbolsByDirectory;
+const path = __importStar(require("path"));
+/**
+ * Wrap template content with YAML front matter for status detection.
+ * This allows instant detection of unfilled files by reading only the first line.
+ */
+function wrapWithFrontMatter(content, options) {
+    const date = new Date().toISOString().split('T')[0];
+    const nameLine = options?.name ? `name: ${options.name}\n` : '';
+    const descLine = options?.description ? `description: ${options.description}\n` : '';
+    return `---
+${nameLine}${descLine}status: unfilled
+generated: ${date}
+---
+
+${content}`;
+}
+const KNOWN_DESCRIPTIONS = {
+    src: 'TypeScript source files and CLI entrypoints.',
+    dist: 'Compiled JavaScript output generated by the build step.',
+    docs: 'Living documentation produced by this tool.',
+    agents: 'AI agent playbooks and prompts.',
+    tests: 'Automated tests and fixtures.',
+    packages: 'Workspace packages or modules.'
+};
+function formatDirectoryList(context, includePlaceholders) {
+    if (context.topLevelDirectories.length === 0) {
+        return '';
+    }
+    return context.topLevelDirectories
+        .map(dir => {
+        const description = KNOWN_DESCRIPTIONS[dir];
+        if (description) {
+            return `- \`${dir}/\` — ${description}`;
+        }
+        if (!includePlaceholders) {
+            return `- \`${dir}/\``;
+        }
+        return `- \`${dir}/\` — TODO: Describe the purpose of this directory.`;
+    })
+        .join('\n');
+}
+function buildDocumentMapTable(guides) {
+    const rows = guides.map(meta => `| ${meta.title} | \`${meta.file}\` | ${meta.primaryInputs} |`);
+    return ['| Guide | File | Primary Inputs |', '| --- | --- | --- |', ...rows].join('\n');
+}
+function formatDirectoryStats(stats) {
+    if (!stats.length) {
+        return '*No directories detected.*';
+    }
+    return stats
+        .map(stat => `- \`${stat.name}/\` — approximately ${stat.fileCount} files`)
+        .join('\n');
+}
+function formatInlineDirectoryList(directories) {
+    if (!directories.length) {
+        return '`n/a`';
+    }
+    return directories.map(dir => `\`${dir}\``).join(', ');
+}
+// Code Reference Helpers
+/**
+ * Format a symbol as a markdown link with line number
+ * Output: [`SymbolName`](src/path/file.ts#L42)
+ */
+function formatSymbolRef(symbol, repoRoot) {
+    const relPath = path.relative(repoRoot, symbol.location.file);
+    return `[\`${symbol.name}\`](${relPath}#L${symbol.location.line})`;
+}
+/**
+ * Format a file:line reference (non-link format)
+ * Output: src/path/file.ts:42
+ */
+function formatCodeLocation(filePath, line, repoRoot) {
+    const relPath = path.relative(repoRoot, filePath);
+    return `${relPath}:${line}`;
+}
+/**
+ * Format a file path as a markdown link with line number
+ * Output: [`file.ts`](src/path/file.ts#L42)
+ */
+function formatFileRef(filePath, line, repoRoot, displayName) {
+    const relPath = path.relative(repoRoot, filePath);
+    const name = displayName || path.basename(filePath);
+    return `[\`${name}\`](${relPath}#L${line})`;
+}
+/**
+ * Build a markdown table of symbols with links
+ */
+function buildSymbolTable(symbols, repoRoot, columns = ['name', 'kind', 'location']) {
+    if (symbols.length === 0) {
+        return '*No symbols found.*';
+    }
+    const headers = {
+        name: 'Symbol',
+        kind: 'Type',
+        location: 'Location',
+        description: 'Description'
+    };
+    const headerRow = '| ' + columns.map(c => headers[c]).join(' | ') + ' |';
+    const separatorRow = '| ' + columns.map(() => '---').join(' | ') + ' |';
+    const dataRows = symbols.map(sym => {
+        const cells = columns.map(col => {
+            switch (col) {
+                case 'name':
+                    return formatSymbolRef(sym, repoRoot);
+                case 'kind':
+                    return sym.kind;
+                case 'location':
+                    return formatCodeLocation(sym.location.file, sym.location.line, repoRoot);
+                case 'description':
+                    return sym.documentation || '-';
+                default:
+                    return '-';
+            }
+        });
+        return '| ' + cells.join(' | ') + ' |';
+    });
+    return [headerRow, separatorRow, ...dataRows].join('\n');
+}
+/**
+ * Build a bullet list of symbols with links
+ */
+function buildSymbolList(symbols, repoRoot, includeKind = true) {
+    if (symbols.length === 0) {
+        return '*No symbols found.*';
+    }
+    return symbols.map(sym => {
+        const ref = formatSymbolRef(sym, repoRoot);
+        const kindSuffix = includeKind ? ` (${sym.kind})` : '';
+        const docSuffix = sym.documentation ? ` — ${sym.documentation}` : '';
+        return `- ${ref}${kindSuffix}${docSuffix}`;
+    }).join('\n');
+}
+/**
+ * Group symbols by their containing directory
+ */
+function groupSymbolsByDirectory(symbols, repoRoot) {
+    const groups = new Map();
+    for (const sym of symbols) {
+        const relPath = path.relative(repoRoot, sym.location.file);
+        const dir = path.dirname(relPath);
+        const existing = groups.get(dir) || [];
+        existing.push(sym);
+        groups.set(dir, existing);
+    }
+    return groups;
+}
+//# sourceMappingURL=common.js.map

package/dist/generators/documentation/templates/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/common.ts"],"names":[],"mappings":"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"}

package/dist/generators/documentation/templates/index.d.ts

@@ -0,0 +1,3 @@
+export { renderIndex } from './indexTemplate';
+export type { DocumentationTemplateContext, GuideMeta, DirectoryStat } from './types';
+//# sourceMappingURL=index.d.ts.map