Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat: add scripts/codemaps/generate.ts codemap generator Fixes #247 - The generate.ts script referenced in agents/doc-updater.md was missing from the repository. This adds the actual implementation. The script: - Recursively walks the src directory (skipping node_modules, dist, etc.) - Classifies files into 5 areas: frontend, backend, database, integrations, workers - Generates docs/CODEMAPS/INDEX.md + one .md per area - Uses the codemap format defined in doc-updater.md - Supports optional srcDir argument: npx tsx scripts/codemaps/generate.ts [srcDir]

Pangerkumzuk Longkumer41ce1a52e500
diff --git a/scripts/codemaps/generate.ts b/scripts/codemaps/generate.ts
new file mode 100644
index 000000000..bd6dd9cb0
--- /dev/null
+++ b/scripts/codemaps/generate.ts
@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+/**
+ * scripts/codemaps/generate.ts
+ *
+ * Codemap Generator for everything-claude-code (ECC)
+ *
+ * Scans the current working directory and generates architectural
+ * codemap documentation under docs/CODEMAPS/ as specified by the
+ * doc-updater agent.
+ *
+ * Usage:
+ * npx tsx scripts/codemaps/generate.ts [srcDir]
+ *
+ * Output:
+ * docs/CODEMAPS/INDEX.md
+ * docs/CODEMAPS/frontend.md
+ * docs/CODEMAPS/backend.md
+ * docs/CODEMAPS/database.md
+ * docs/CODEMAPS/integrations.md
+ * docs/CODEMAPS/workers.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const ROOT = process.cwd();
+const SRC_DIR = process.argv[2] ? path.resolve(process.argv[2]) : ROOT;
+const OUTPUT_DIR = path.join(ROOT, 'docs', 'CODEMAPS');
+const TODAY = new Date().toISOString().split('T')[0];
+
+// Patterns used to classify files into codemap areas
+const AREA_PATTERNS: Record<string, RegExp[]> = {
+ frontend: [
+ /\/(app|pages|components|hooks|contexts|ui|views|layouts|styles)\//i,
+ /\.(tsx|jsx|css|scss|sass|less|vue|svelte)$/i,
+ ],
+ backend: [
+ /\/(api|routes|controllers|middleware|server|services|handlers)\//i,
+ /\.(route|controller|handler|middleware|service)\.(ts|js)$/i,
+ ],
+ database: [
+ /\/(models|schemas|migrations|prisma|drizzle|db|database|repositories)\//i,
+ /\.(model|schema|migration|seed)\.(ts|js)$/i,
+ /prisma\/schema\.prisma$/,
+ /schema\.sql$/,
+ ],
+ integrations: [
+ /\/(integrations?|third-party|external|plugins?|adapters?|connectors?)\//i,
+ /\.(integration|adapter|connector)\.(ts|js)$/i,
+ ],
+ workers: [
+ /\/(workers?|jobs?|queues?|tasks?|cron|background)\//i,
+ /\.(worker|job|queue|task|cron)\.(ts|js)$/i,
+ ],
+};
+
+// ---------------------------------------------------------------------------
+// File System Helpers
+// ---------------------------------------------------------------------------
+
+/** Recursively collect all files under a directory, skipping common noise dirs. */
+function walkDir(dir: string, results: string[] = []): string[] {
+ const SKIP = new Set([
+ 'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
+ '.turbo', 'coverage', '.cache', '__pycache__', '.venv', 'venv',
+ ]);
+
+ let entries: fs.Dirent[];
+ try {
+ entries = fs.readdirSync(dir, { withFileTypes: true });
+ } catch {
+ return results;
+ }
+
+ for (const entry of entries) {
+ if (SKIP.has(entry.name)) continue;
+ const fullPath = path.join(dir, entry.name);
+ if (entry.isDirectory()) {
+ walkDir(fullPath, results);
+ } else if (entry.isFile()) {
+ results.push(fullPath);
+ }
+ }
+ return results;
+}
+
+/** Return path relative to ROOT, always using forward slashes. */
+function rel(p: string): string {
+ return path.relative(ROOT, p).replace(/\\/g, '/');
+}
+
+// ---------------------------------------------------------------------------
+// Analysis
+// ---------------------------------------------------------------------------
+
+interface AreaInfo {
+ name: string;
+ files: string[];
+ entryPoints: string[];
+ directories: string[];
+}
+
+function classifyFiles(allFiles: string[]): Record<string, AreaInfo> {
+ const areas: Record<string, AreaInfo> = {
+ frontend: { name: 'Frontend', files: [], entryPoints: [], directories: [] },
+ backend: { name: 'Backend/API', files: [], entryPoints: [], directories: [] },
+ database: { name: 'Database', files: [], entryPoints: [], directories: [] },
+ integrations: { name: 'Integrations', files: [], entryPoints: [], directories: [] },
+ workers: { name: 'Workers', files: [], entryPoints: [], directories: [] },
+ };
+
+ for (const file of allFiles) {
+ const relPath = rel(file);
+ for (const [area, patterns] of Object.entries(AREA_PATTERNS)) {
+ if (patterns.some((p) => p.test(relPath))) {
+ areas[area].files.push(relPath);
+ break;
+ }
+ }
+ }
+
+ // Derive unique directories and entry points per area
+ for (const area of Object.values(areas)) {
+ const dirs = new Set(area.files.map((f) => path.dirname(f)));
+ area.directories = [...dirs].sort();
+
+ area.entryPoints = area.files
+ .filter((f) => /index\.(ts|tsx|js|jsx)$/.test(f) || /main\.(ts|tsx|js|jsx)$/.test(f))
+ .slice(0, 10);
+ }
+
+ return areas;
+}
+
+/** Count lines in a file (returns 0 on error). */
+function lineCount(p: string): number {
+ try {
+ const content = fs.readFileSync(p, 'utf8');
+ return content.split('\n').length;
+ } catch {
+ return 0;
+ }
+}
+
+/** Build a simple directory tree ASCII diagram (max 3 levels deep). */
+function buildTree(dir: string, prefix = '', depth = 0): string {
+ if (depth > 2) return '';
+ const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage']);
+
+ let entries: fs.Dirent[];
+ try {
+ entries = fs.readdirSync(dir, { withFileTypes: true });
+ } catch {
+ return '';
+ }
+
+ const dirs = entries.filter((e) => e.isDirectory() && !SKIP.has(e.name));
+ const files = entries.filter((e) => e.isFile());
+
+ let result = '';
+ const items = [...dirs, ...files];
+ items.forEach((entry, i) => {
+ const isLast = i === items.length - 1;
+ const connector = isLast ? '└── ' : '├── ';
+ result += `${prefix}${connector}${entry.name}\n`;
+ if (entry.isDirectory()) {
+ const newPrefix = prefix + (isLast ? ' ' : '│ ');
+ result += buildTree(path.join(dir, entry.name), newPrefix, depth + 1);
+ }
+ });
+ return result;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown Generators
+// ---------------------------------------------------------------------------
+
+function generateAreaDoc(areaKey: string, area: AreaInfo, allFiles: string[]): string {
+ const fileCount = area.files.length;
+ const totalLines = area.files.reduce((sum, f) => sum + lineCount(path.join(ROOT, f)), 0);
+
+ const entrySection = area.entryPoints.length > 0
+ ? area.entryPoints.map((e) => `- \`${e}\``).join('\n')
+ : '- *(no index/main entry points detected)*';
+
+ const dirSection = area.directories.slice(0, 20)
+ .map((d) => `- \`${d}/\``)
+ .join('\n') || '- *(no dedicated directories detected)*';
+
+ const fileSection = area.files.slice(0, 30)
+ .map((f) => `| \`${f}\` | ${lineCount(path.join(ROOT, f))} |`)
+ .join('\n');
+
+ const moreFiles = area.files.length > 30
+ ? `\n*...and ${area.files.length - 30} more files*`
+ : '';
+
+ return `# ${area.name} Codemap
+
+**Last Updated:** ${TODAY}
+**Total Files:** ${fileCount}
+**Total Lines:** ${totalLines}
+
+## Entry Points
+
+${entrySection}
+
+## Architecture
+
+\`\`\`
+${area.name} Directory Structure
+${dirSection.replace(/- `/g, '').replace(/`\/$/gm, '/')}
+\`\`\`
+
+## Key Modules
+
+| File | Lines |
+|------|-------|
+${fileSection}${moreFiles}
+
+## Data Flow
+
+> Detected from file patterns. Review individual files for detailed data flow.
+
+## External Dependencies
+
+> Run \`npx jsdoc2md src/**/*.ts\` to extract JSDoc and identify external dependencies.
+
+## Related Areas
+
+- [INDEX](./INDEX.md) — Full overview
+- [Frontend](./frontend.md)
+- [Backend/API](./backend.md)
+- [Database](./database.md)
+- [Integrations](./integrations.md)
+- [Workers](./workers.md)
+`;
+}
+
+function generateIndex(areas: Record<string, AreaInfo>, allFiles: string[]): string {
+ const totalFiles = allFiles.length;
+ const areaRows = Object.entries(areas)
+ .map(([key, area]) => `| [${area.name}](./${key}.md) | ${area.files.length} files | ${area.directories.slice(0, 3).map((d) => `\`${d}\``).join(', ') || '—'} |`)
+ .join('\n');
+
+ const topLevelTree = buildTree(SRC_DIR);
+
+ return `# Codebase Overview — CODEMAPS Index
+
+**Last Updated:** ${TODAY}
+**Root:** \`${rel(SRC_DIR) || '.'}\`
+**Total Files Scanned:** ${totalFiles}
+
+## Areas
+
+| Area | Size | Key Directories |
+|------|------|-----------------|
+${areaRows}
+
+## Repository Structure
+
+\`\`\`
+${rel(SRC_DIR) || path.basename(SRC_DIR)}/
+${topLevelTree}\`\`\`
+
+## How to Regenerate
+
+\`\`\`bash
+npx tsx scripts/codemaps/generate.ts # Regenerate codemaps
+npx madge --image graph.svg src/ # Dependency graph (requires graphviz)
+npx jsdoc2md src/**/*.ts # Extract JSDoc
+\`\`\`
+
+## Related Documentation
+
+- [Frontend](./frontend.md) — UI components, pages, hooks
+- [Backend/API](./backend.md) — API routes, controllers, middleware
+- [Database](./database.md) — Models, schemas, migrations
+- [Integrations](./integrations.md) — External services & adapters
+- [Workers](./workers.md) — Background jobs, queues, cron tasks
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main(): void {
+ console.log(`[generate.ts] Scanning: ${SRC_DIR}`);
+ console.log(`[generate.ts] Output: ${OUTPUT_DIR}`);
+
+ // Ensure output directory exists
+ fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+
+ // Walk the directory tree
+ const allFiles = walkDir(SRC_DIR);
+ console.log(`[generate.ts] Found ${allFiles.length} files`);
+
+ // Classify files into areas
+ const areas = classifyFiles(allFiles);
+
+ // Generate INDEX.md
+ const indexContent = generateIndex(areas, allFiles);
+ const indexPath = path.join(OUTPUT_DIR, 'INDEX.md');
+ fs.writeFileSync(indexPath, indexContent, 'utf8');
+ console.log(`[generate.ts] Written: ${rel(indexPath)}`);
+
+ // Generate per-area codemaps
+ for (const [key, area] of Object.entries(areas)) {
+ const content = generateAreaDoc(key, area, allFiles);
+ const outPath = path.join(OUTPUT_DIR, `${key}.md`);
+ fs.writeFileSync(outPath, content, 'utf8');
+ console.log(`[generate.ts] Written: ${rel(outPath)} (${area.files.length} files)`);
+ }
+
+ console.log('\n[generate.ts] Done! Codemaps written to docs/CODEMAPS/');
+ console.log('[generate.ts] Files generated:');
+ console.log(' docs/CODEMAPS/INDEX.md');
+ console.log(' docs/CODEMAPS/frontend.md');
+ console.log(' docs/CODEMAPS/backend.md');
+ console.log(' docs/CODEMAPS/database.md');
+ console.log(' docs/CODEMAPS/integrations.md');
+ console.log(' docs/CODEMAPS/workers.md');
+}
+
+main();