@ai-coders/context 0.4.0 → 0.5.1

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

@@ -1,66 +1,204 @@
 "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.renderArchitectureNotes = renderArchitectureNotes;
 const common_1 = require("./common");
+const path = __importStar(require("path"));
+function renderSemanticLayers(context) {
+    const { semantics } = context;
+    if (!semantics || !semantics.architecture.layers.length) {
+        return '- *No architectural layers detected.*';
+    }
+    const lines = [];
+    for (const layer of semantics.architecture.layers) {
+        const symbolCount = layer.symbols.length;
+        const exportedCount = layer.symbols.filter(s => s.exported).length;
+        const deps = layer.dependsOn.length > 0 ? ` → depends on: ${layer.dependsOn.join(', ')}` : '';
+        lines.push(`### ${layer.name}`);
+        lines.push(`${layer.description}`);
+        lines.push(`- **Directories**: ${layer.directories.map(d => `\`${d}\``).join(', ')}`);
+        lines.push(`- **Symbols**: ${symbolCount} total, ${exportedCount} exported${deps}`);
+        // List exported symbols
+        const topSymbols = layer.symbols
+            .filter(s => s.exported);
+        if (topSymbols.length > 0) {
+            lines.push(`- **Key exports**:`);
+            const repoRoot = context.repoStructure.rootPath;
+            for (const sym of topSymbols) {
+                const ref = (0, common_1.formatSymbolRef)(sym, repoRoot);
+                const doc = sym.documentation ? ` — ${sym.documentation}` : '';
+                lines.push(`  - ${ref} (${sym.kind})${doc}`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function renderDetectedPatterns(context) {
+    const { semantics } = context;
+    if (!semantics || !semantics.architecture.patterns.length) {
+        return '- *No design patterns detected yet.*';
+    }
+    const repoRoot = context.repoStructure.rootPath;
+    const lines = ['| Pattern | Confidence | Locations | Description |', '|---------|------------|-----------|-------------|'];
+    for (const pattern of semantics.architecture.patterns) {
+        const confidence = Math.round(pattern.confidence * 100);
+        // Format locations with file refs
+        const locationRefs = pattern.locations.map(l => {
+            const relPath = path.relative(repoRoot, l.file);
+            return `\`${l.symbol}\` ([${path.basename(l.file)}](${relPath}))`;
+        });
+        lines.push(`| ${pattern.name} | ${confidence}% | ${locationRefs.join(', ')} | ${pattern.description} |`);
+    }
+    return lines.join('\n');
+}
+function renderPublicAPI(context) {
+    const { semantics } = context;
+    if (!semantics || !semantics.architecture.publicAPI.length) {
+        return '- *No public API detected.*';
+    }
+    const repoRoot = context.repoStructure.rootPath;
+    // Use buildSymbolTable for consistent formatting
+    return (0, common_1.buildSymbolTable)(semantics.architecture.publicAPI, repoRoot, ['name', 'kind', 'location']);
+}
+function renderEntryPoints(context) {
+    const { semantics } = context;
+    if (!semantics || !semantics.architecture.entryPoints.length) {
+        return '- *No entry points detected.*';
+    }
+    const repoRoot = context.repoStructure.rootPath;
+    return semantics.architecture.entryPoints.map(ep => {
+        const relPath = path.relative(repoRoot, ep);
+        return `- [\`${relPath}\`](${relPath})`;
+    }).join('\n');
+}
+function renderSemanticStats(context) {
+    const { semantics } = context;
+    if (!semantics) {
+        return '';
+    }
+    const { stats, symbols } = semantics;
+    const lines = [
+        `- **Total Files Analyzed**: ${stats.totalFiles}`,
+        `- **Total Symbols**: ${stats.totalSymbols}`,
+        `- **Classes**: ${symbols.classes.length}`,
+        `- **Interfaces**: ${symbols.interfaces.length}`,
+        `- **Functions**: ${symbols.functions.length}`,
+        `- **Types**: ${symbols.types.length}`,
+        `- **Enums**: ${symbols.enums.length}`,
+        `- **Analysis Time**: ${stats.analysisTimeMs}ms`,
+    ];
+    if (Object.keys(stats.languageBreakdown).length > 0) {
+        lines.push('', '**Languages**:');
+        for (const [ext, count] of Object.entries(stats.languageBreakdown)) {
+            lines.push(`- ${ext}: ${count} files`);
+        }
+    }
+    return lines.join('\n');
+}
 function renderArchitectureNotes(context) {
     const directorySnapshot = (0, common_1.formatDirectoryStats)(context.directoryStats);
-    const coreComponentsSection = directorySnapshot || '- *Add notes for each core component or module.*';
-    return `<!-- agent-update:start:architecture-notes -->
-# Architecture Notes
-
-> TODO: Describe how the system is assembled and why the current design exists.
+    const hasSemantics = !!context.semantics;
+    // Use semantic data if available, otherwise fall back to directory stats
+    const layersSection = hasSemantics
+        ? renderSemanticLayers(context)
+        : directorySnapshot || '- *Add notes for each core component or module.*';
+    const patternsSection = hasSemantics
+        ? renderDetectedPatterns(context)
+        : '- *No design patterns detected.*';
+    const publicAPISection = hasSemantics
+        ? renderPublicAPI(context)
+        : '- *No public API detected.*';
+    const entryPointsSection = hasSemantics
+        ? renderEntryPoints(context)
+        : '- *Document the main entry points of the application.*';
+    const statsSection = hasSemantics
+        ? renderSemanticStats(context)
+        : '';
+    const semanticSection = hasSemantics ? `
+## Codebase Analysis
+${statsSection}
+` : '';
+    const content = `# Architecture Notes
 
+Describe how the system is assembled and why the current design exists.
+${semanticSection}
 ## System Architecture Overview
-- Summarize the top-level topology (monolith, modular service, microservices) and deployment model.
-- Highlight how requests traverse the system and where control pivots between layers.
 
-## Core System Components
-${coreComponentsSection}
+Summarize the top-level topology (monolith, modular service, microservices) and deployment model. Highlight how requests traverse the system and where control pivots between layers.
+
+## Architectural Layers
+${layersSection}
+
+## Detected Design Patterns
+${patternsSection}
+
+## Entry Points
+${entryPointsSection}
+
+## Public API
+${publicAPISection}
 
 ## Internal System Boundaries
-- Document seams between domains, bounded contexts, or service ownership.
-- Note data ownership, synchronization strategies, and shared contract enforcement.
 
-## System Integration Points
-- Map inbound interfaces (APIs, events, webhooks) and the modules that own them.
-- Capture orchestration touchpoints where this system calls or coordinates other internal services.
+Document seams between domains, bounded contexts, or service ownership. Note data ownership, synchronization strategies, and shared contract enforcement.
 
 ## External Service Dependencies
-- List SaaS platforms, third-party APIs, or infrastructure services the system relies on.
-- Describe authentication methods, rate limits, and failure considerations for each dependency.
+
+List SaaS platforms, third-party APIs, or infrastructure services the system relies on. Describe authentication methods, rate limits, and failure considerations for each dependency.
 
 ## Key Decisions & Trade-offs
-- Summarize architectural decisions, experiments, or ADR outcomes that shape the current design.
-- Reference supporting documents and explain why selected approaches won over alternatives.
+
+Summarize architectural decisions, experiments, or ADR outcomes that shape the current design. Reference supporting documents and explain why selected approaches won over alternatives.
 
 ## Diagrams
-- Link architectural diagrams or add mermaid definitions here.
+
+Link architectural diagrams or add mermaid definitions here.
 
 ## Risks & Constraints
-- Document performance constraints, scaling considerations, or external system assumptions.
+
+Document performance constraints, scaling considerations, or external system assumptions.
 
 ## Top Directories Snapshot
 ${directorySnapshot}
 
-<!-- agent-readonly:guidance -->
-## AI Update Checklist
-1. Review ADRs, design docs, or major PRs for architectural changes.
-2. Verify that each documented decision still holds; mark superseded choices clearly.
-3. Capture upstream/downstream impacts (APIs, events, data flows).
-4. Update Risks & Constraints with active incident learnings or TODO debt.
-5. Link any new diagrams or dashboards referenced in recent work.
-
-<!-- agent-readonly:sources -->
-## Acceptable Sources
-- ADR folders, \`/docs/architecture\` notes, or RFC threads.
-- Dependency visualisations from build tooling or scripts.
-- Issue tracker discussions vetted by maintainers.
-
 ## Related Resources
+
 - [Project Overview](./project-overview.md)
 - Update [agents/README.md](../agents/README.md) when architecture changes.
-
-<!-- agent-update:end -->
 `;
+    return (0, common_1.wrapWithFrontMatter)(content);
 }
 //# sourceMappingURL=architectureTemplate.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"architectureTemplate.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/architectureTemplate.ts"],"names":[],"mappings":";;AAGA,0DA6DC;AA/DD,qCAAgD;AAEhD,SAAgB,uBAAuB,CAAC,OAAqC;IAC3E,MAAM,iBAAiB,GAAG,IAAA,6BAAoB,EAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,MAAM,qBAAqB,GAAG,iBAAiB,IAAI,kDAAkD,CAAC;IAEtG,OAAO;;;;;;;;;;EAUP,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;EAyBrB,iBAAiB;;;;;;;;;;;;;;;;;;;;;CAqBlB,CAAC;AACF,CAAC"}
+{"version":3,"file":"architectureTemplate.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/architectureTemplate.ts"],"names":[],"mappings":"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"}

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

@@ -1,7 +1,39 @@
 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): 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;
-export declare function slugify(value: 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

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAWtE,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,4BAA4B,EACrC,mBAAmB,EAAE,OAAO,GAC3B,MAAM,CAoBR;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;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7C"}
+{"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,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ3D;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

@@ -1,10 +1,63 @@
 "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.slugify = slugify;
+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) {
+    const date = new Date().toISOString().split('T')[0];
+    return `---
+status: unfilled
+generated: ${date}
+---
+
+${content}`;
+}
 const KNOWN_DESCRIPTIONS = {
     src: 'TypeScript source files and CLI entrypoints.',
     dist: 'Compiled JavaScript output generated by the build step.',
@@ -26,14 +79,13 @@ function formatDirectoryList(context, includePlaceholders) {
         if (!includePlaceholders) {
             return `- \`${dir}/\``;
         }
-        const slotId = slugify(dir);
-        return `- <!-- agent-fill:directory-${slotId} -->\`${dir}/\` — TODO: Describe the purpose of this directory.<!-- /agent-fill -->`;
+        return `- \`${dir}/\` — TODO: Describe the purpose of this directory.`;
     })
         .join('\n');
 }
 function buildDocumentMapTable(guides) {
-    const rows = guides.map(meta => `| ${meta.title} | \`${meta.file}\` | ${meta.marker} | ${meta.primaryInputs} |`);
-    return ['| Guide | File | AI Marker | Primary Inputs |', '| --- | --- | --- | --- |', ...rows].join('\n');
+    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) {
@@ -49,10 +101,92 @@ function formatInlineDirectoryList(directories) {
     }
     return directories.map(dir => `\`${dir}\``).join(', ');
 }
-function slugify(value) {
-    return value
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
+// 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

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/common.ts"],"names":[],"mappings":";;AAWA,kDAuBC;AAED,sDAGC;AAED,oDAQC;AAED,8DAMC;AAED,0BAKC;AA9DD,MAAM,kBAAkB,GAA2B;IACjD,GAAG,EAAE,8CAA8C;IACnD,IAAI,EAAE,yDAAyD;IAC/D,IAAI,EAAE,6CAA6C;IACnD,MAAM,EAAE,iCAAiC;IACzC,KAAK,EAAE,+BAA+B;IACtC,QAAQ,EAAE,gCAAgC;CAC3C,CAAC;AAEF,SAAgB,mBAAmB,CACjC,OAAqC,EACrC,mBAA4B;IAE5B,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,mBAAmB;SAC/B,GAAG,CAAC,GAAG,CAAC,EAAE;QACT,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,OAAO,GAAG,SAAS,WAAW,EAAE,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACzB,OAAO,OAAO,GAAG,KAAK,CAAC;QACzB,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,+BAA+B,MAAM,SAAS,GAAG,yEAAyE,CAAC;IACpI,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,qBAAqB,CAAC,MAA8C;IAClF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;IACjH,OAAO,CAAC,+CAA+C,EAAE,2BAA2B,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5G,CAAC;AAED,SAAgB,oBAAoB,CAAC,KAAsB;IACzD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,4BAA4B,CAAC;IACtC,CAAC;IAED,OAAO,KAAK;SACT,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,CAAC,IAAI,uBAAuB,IAAI,CAAC,SAAS,QAAQ,CAAC;SAC1E,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,yBAAyB,CAAC,WAAqB;IAC7D,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,SAAgB,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/common.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,kDAQC;AAWD,kDAsBC;AAED,sDAGC;AAED,oDAQC;AAED,8DAMC;AAQD,0CAMC;AAMD,gDAOC;AAMD,sCASC;AAKD,4CAsCC;AAKD,0CAeC;AAKD,0DAeC;AArMD,2CAA6B;AAI7B;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,OAAe;IACjD,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO;;aAEI,IAAI;;;EAGf,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,kBAAkB,GAA2B;IACjD,GAAG,EAAE,8CAA8C;IACnD,IAAI,EAAE,yDAAyD;IAC/D,IAAI,EAAE,6CAA6C;IACnD,MAAM,EAAE,iCAAiC;IACzC,KAAK,EAAE,+BAA+B;IACtC,QAAQ,EAAE,gCAAgC;CAC3C,CAAC;AAEF,SAAgB,mBAAmB,CACjC,OAAqC,EACrC,mBAA4B;IAE5B,IAAI,OAAO,CAAC,mBAAmB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,mBAAmB;SAC/B,GAAG,CAAC,GAAG,CAAC,EAAE;QACT,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAC5C,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,OAAO,GAAG,SAAS,WAAW,EAAE,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACzB,OAAO,OAAO,GAAG,KAAK,CAAC;QACzB,CAAC;QAED,OAAO,OAAO,GAAG,qDAAqD,CAAC;IACzE,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,qBAAqB,CAAC,MAA8C;IAClF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;IAChG,OAAO,CAAC,mCAAmC,EAAE,qBAAqB,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1F,CAAC;AAED,SAAgB,oBAAoB,CAAC,KAAsB;IACzD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,4BAA4B,CAAC;IACtC,CAAC;IAED,OAAO,KAAK;SACT,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,CAAC,IAAI,uBAAuB,IAAI,CAAC,SAAS,QAAQ,CAAC;SAC1E,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAgB,yBAAyB,CAAC,WAAqB;IAC7D,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,yBAAyB;AAEzB;;;GAGG;AACH,SAAgB,eAAe,CAC7B,MAAuB,EACvB,QAAgB;IAEhB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9D,OAAO,MAAM,MAAM,CAAC,IAAI,OAAO,OAAO,KAAK,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAChC,QAAgB,EAChB,IAAY,EACZ,QAAgB;IAEhB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAClD,OAAO,GAAG,OAAO,IAAI,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAC3B,QAAgB,EAChB,IAAY,EACZ,QAAgB,EAChB,WAAoB;IAEpB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACpD,OAAO,MAAM,IAAI,OAAO,OAAO,KAAK,IAAI,GAAG,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,SAAgB,gBAAgB,CAC9B,OAA0B,EAC1B,QAAgB,EAChB,UAA4D,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC;IAExF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,UAAU;QACpB,WAAW,EAAE,aAAa;KAC3B,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACzE,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAExE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;QACjC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;YAC9B,QAAQ,GAAG,EAAE,CAAC;gBACZ,KAAK,MAAM;oBACT,OAAO,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;gBACxC,KAAK,MAAM;oBACT,OAAO,GAAG,CAAC,IAAI,CAAC;gBAClB,KAAK,UAAU;oBACb,OAAO,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;gBAC5E,KAAK,aAAa;oBAChB,OAAO,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC;gBAClC;oBACE,OAAO,GAAG,CAAC;YACf,CAAC;QACH,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAC7B,OAA0B,EAC1B,QAAgB,EAChB,cAAuB,IAAI;IAE3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;QACvB,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC3C,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,MAAM,SAAS,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,OAAO,KAAK,GAAG,GAAG,UAAU,GAAG,SAAS,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAgB,uBAAuB,CACrC,OAA0B,EAC1B,QAAgB;IAEhB,MAAM,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEpD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"dataFlowTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/dataFlowTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAGvD,wBAAgB,cAAc,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAkC5E"}
+{"version":3,"file":"dataFlowTemplate.d.ts","sourceRoot":"","sources":["../../../../src/generators/documentation/templates/dataFlowTemplate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,SAAS,CAAC;AAwEvD,wBAAgB,cAAc,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAgC5E"}

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

@@ -1,40 +1,124 @@
 "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.renderDataFlow = renderDataFlow;
+const path = __importStar(require("path"));
 const common_1 = require("./common");
+function renderModuleDependencies(context) {
+    const { semantics, repoStructure } = context;
+    if (!semantics || !semantics.dependencies?.graph) {
+        return '- *No module dependencies detected.*';
+    }
+    const repoRoot = repoStructure.rootPath;
+    const graph = semantics.dependencies.graph;
+    if (graph.size === 0) {
+        return '- *No module dependencies detected.*';
+    }
+    // Group dependencies by top-level directory
+    const moduleGroups = new Map();
+    for (const [source, targets] of graph) {
+        const relSource = path.relative(repoRoot, source);
+        const sourceDir = relSource.split('/')[0] || relSource;
+        for (const target of targets) {
+            const relTarget = path.relative(repoRoot, target);
+            const targetDir = relTarget.split('/')[0] || relTarget;
+            if (sourceDir !== targetDir) {
+                const key = sourceDir;
+                const deps = moduleGroups.get(key) || new Set();
+                deps.add(targetDir);
+                moduleGroups.set(key, deps);
+            }
+        }
+    }
+    if (moduleGroups.size === 0) {
+        return '- *No cross-module dependencies detected.*';
+    }
+    const lines = [];
+    for (const [module, deps] of moduleGroups) {
+        const depList = Array.from(deps).sort().map(d => `\`${d}\``).join(', ');
+        lines.push(`- **${module}/** → ${depList}`);
+    }
+    return lines.join('\n');
+}
+function renderServiceLayer(context) {
+    const { semantics, repoStructure } = context;
+    if (!semantics) {
+        return '- *No service classes detected.*';
+    }
+    const repoRoot = repoStructure.rootPath;
+    // Find service classes (classes ending in Service)
+    const services = semantics.symbols.classes
+        .filter(s => s.name.endsWith('Service') && s.exported);
+    if (services.length === 0) {
+        return '- *No service classes detected.*';
+    }
+    return services.map(sym => {
+        const relPath = path.relative(repoRoot, sym.location.file);
+        const doc = sym.documentation ? ` — ${sym.documentation}` : '';
+        return `- [\`${sym.name}\`](${relPath}#L${sym.location.line})${doc}`;
+    }).join('\n');
+}
 function renderDataFlow(context) {
-    return `<!-- agent-update:start:data-flow -->
-# Data Flow & Integrations
+    const moduleDependencies = renderModuleDependencies(context);
+    const serviceLayer = renderServiceLayer(context);
+    const content = `# Data Flow & Integrations
 
 Explain how data enters, moves through, and exits the system, including interactions with external services.
 
+## Module Dependencies
+${moduleDependencies}
+
+## Service Layer
+${serviceLayer}
+
 ## High-level Flow
-- Summarize the primary pipeline from input to output. Reference diagrams or embed Mermaid definitions when available.
+
+Summarize the primary pipeline from input to output. Reference diagrams or embed Mermaid definitions when available.
 
 ## Internal Movement
-- Describe how modules within ${(0, common_1.formatInlineDirectoryList)(context.topLevelDirectories)} collaborate (queues, events, RPC calls, shared databases).
+
+Describe how modules within ${(0, common_1.formatInlineDirectoryList)(context.topLevelDirectories)} collaborate (queues, events, RPC calls, shared databases).
 
 ## External Integrations
-- <!-- agent-fill:integration -->**Integration** — Purpose, authentication, payload shapes, retry strategy.<!-- /agent-fill -->
+
+Document each integration with purpose, authentication, payload shapes, and retry strategy.
 
 ## Observability & Failure Modes
-- Metrics, traces, or logs that monitor the flow.
-- Backoff, dead-letter, or compensating actions when downstream systems fail.
-
-<!-- agent-readonly:guidance -->
-## AI Update Checklist
-1. Validate flows against the latest integration contracts or diagrams.
-2. Update authentication, scopes, or rate limits when they change.
-3. Capture recent incidents or lessons learned that influenced reliability.
-4. Link to runbooks or dashboards used during triage.
-
-<!-- agent-readonly:sources -->
-## Acceptable Sources
-- Architecture diagrams, ADRs, integration playbooks.
-- API specs, queue/topic definitions, infrastructure code.
-- Postmortems or incident reviews impacting data movement.
-
-<!-- agent-update:end -->
+
+Describe metrics, traces, or logs that monitor the flow. Note backoff, dead-letter, or compensating actions when downstream systems fail.
 `;
+    return (0, common_1.wrapWithFrontMatter)(content);
 }
 //# sourceMappingURL=dataFlowTemplate.js.map