Skip to content

Commit 41ce1a5

Browse files
authored
feat: add scripts/codemaps/generate.ts codemap generator Fixes anomalyco#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]
This script scans the current working directory and generates architectural codemap documentation in the specified output directory. It classifies files into areas such as frontend, backend, database, integrations, and workers, and creates markdown files for each area along with an index.
1 parent 6f94c2e commit 41ce1a5

1 file changed

Lines changed: 330 additions & 0 deletions

File tree

‎scripts/codemaps/generate.ts‎

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
#!/usr/bin/env node
2+
/**
3+
* scripts/codemaps/generate.ts
4+
*
5+
* Codemap Generator for everything-claude-code (ECC)
6+
*
7+
* Scans the current working directory and generates architectural
8+
* codemap documentation under docs/CODEMAPS/ as specified by the
9+
* doc-updater agent.
10+
*
11+
* Usage:
12+
* npx tsx scripts/codemaps/generate.ts [srcDir]
13+
*
14+
* Output:
15+
* docs/CODEMAPS/INDEX.md
16+
* docs/CODEMAPS/frontend.md
17+
* docs/CODEMAPS/backend.md
18+
* docs/CODEMAPS/database.md
19+
* docs/CODEMAPS/integrations.md
20+
* docs/CODEMAPS/workers.md
21+
*/
22+
23+
import fs from 'fs';
24+
import path from 'path';
25+
26+
// ---------------------------------------------------------------------------
27+
// Config
28+
// ---------------------------------------------------------------------------
29+
30+
const ROOT = process.cwd();
31+
const SRC_DIR = process.argv[2] ? path.resolve(process.argv[2]) : ROOT;
32+
const OUTPUT_DIR = path.join(ROOT, 'docs', 'CODEMAPS');
33+
const TODAY = new Date().toISOString().split('T')[0];
34+
35+
// Patterns used to classify files into codemap areas
36+
const AREA_PATTERNS: Record<string, RegExp[]> = {
37+
frontend: [
38+
/\/(app|pages|components|hooks|contexts|ui|views|layouts|styles)\//i,
39+
/\.(tsx|jsx|css|scss|sass|less|vue|svelte)$/i,
40+
],
41+
backend: [
42+
/\/(api|routes|controllers|middleware|server|services|handlers)\//i,
43+
/\.(route|controller|handler|middleware|service)\.(ts|js)$/i,
44+
],
45+
database: [
46+
/\/(models|schemas|migrations|prisma|drizzle|db|database|repositories)\//i,
47+
/\.(model|schema|migration|seed)\.(ts|js)$/i,
48+
/prisma\/schema\.prisma$/,
49+
/schema\.sql$/,
50+
],
51+
integrations: [
52+
/\/(integrations?|third-party|external|plugins?|adapters?|connectors?)\//i,
53+
/\.(integration|adapter|connector)\.(ts|js)$/i,
54+
],
55+
workers: [
56+
/\/(workers?|jobs?|queues?|tasks?|cron|background)\//i,
57+
/\.(worker|job|queue|task|cron)\.(ts|js)$/i,
58+
],
59+
};
60+
61+
// ---------------------------------------------------------------------------
62+
// File System Helpers
63+
// ---------------------------------------------------------------------------
64+
65+
/** Recursively collect all files under a directory, skipping common noise dirs. */
66+
function walkDir(dir: string, results: string[] = []): string[] {
67+
const SKIP = new Set([
68+
'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
69+
'.turbo', 'coverage', '.cache', '__pycache__', '.venv', 'venv',
70+
]);
71+
72+
let entries: fs.Dirent[];
73+
try {
74+
entries = fs.readdirSync(dir, { withFileTypes: true });
75+
} catch {
76+
return results;
77+
}
78+
79+
for (const entry of entries) {
80+
if (SKIP.has(entry.name)) continue;
81+
const fullPath = path.join(dir, entry.name);
82+
if (entry.isDirectory()) {
83+
walkDir(fullPath, results);
84+
} else if (entry.isFile()) {
85+
results.push(fullPath);
86+
}
87+
}
88+
return results;
89+
}
90+
91+
/** Return path relative to ROOT, always using forward slashes. */
92+
function rel(p: string): string {
93+
return path.relative(ROOT, p).replace(/\\/g, '/');
94+
}
95+
96+
// ---------------------------------------------------------------------------
97+
// Analysis
98+
// ---------------------------------------------------------------------------
99+
100+
interface AreaInfo {
101+
name: string;
102+
files: string[];
103+
entryPoints: string[];
104+
directories: string[];
105+
}
106+
107+
function classifyFiles(allFiles: string[]): Record<string, AreaInfo> {
108+
const areas: Record<string, AreaInfo> = {
109+
frontend: { name: 'Frontend', files: [], entryPoints: [], directories: [] },
110+
backend: { name: 'Backend/API', files: [], entryPoints: [], directories: [] },
111+
database: { name: 'Database', files: [], entryPoints: [], directories: [] },
112+
integrations: { name: 'Integrations', files: [], entryPoints: [], directories: [] },
113+
workers: { name: 'Workers', files: [], entryPoints: [], directories: [] },
114+
};
115+
116+
for (const file of allFiles) {
117+
const relPath = rel(file);
118+
for (const [area, patterns] of Object.entries(AREA_PATTERNS)) {
119+
if (patterns.some((p) => p.test(relPath))) {
120+
areas[area].files.push(relPath);
121+
break;
122+
}
123+
}
124+
}
125+
126+
// Derive unique directories and entry points per area
127+
for (const area of Object.values(areas)) {
128+
const dirs = new Set(area.files.map((f) => path.dirname(f)));
129+
area.directories = [...dirs].sort();
130+
131+
area.entryPoints = area.files
132+
.filter((f) => /index\.(ts|tsx|js|jsx)$/.test(f) || /main\.(ts|tsx|js|jsx)$/.test(f))
133+
.slice(0, 10);
134+
}
135+
136+
return areas;
137+
}
138+
139+
/** Count lines in a file (returns 0 on error). */
140+
function lineCount(p: string): number {
141+
try {
142+
const content = fs.readFileSync(p, 'utf8');
143+
return content.split('\n').length;
144+
} catch {
145+
return 0;
146+
}
147+
}
148+
149+
/** Build a simple directory tree ASCII diagram (max 3 levels deep). */
150+
function buildTree(dir: string, prefix = '', depth = 0): string {
151+
if (depth > 2) return '';
152+
const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage']);
153+
154+
let entries: fs.Dirent[];
155+
try {
156+
entries = fs.readdirSync(dir, { withFileTypes: true });
157+
} catch {
158+
return '';
159+
}
160+
161+
const dirs = entries.filter((e) => e.isDirectory() && !SKIP.has(e.name));
162+
const files = entries.filter((e) => e.isFile());
163+
164+
let result = '';
165+
const items = [...dirs, ...files];
166+
items.forEach((entry, i) => {
167+
const isLast = i === items.length - 1;
168+
const connector = isLast ? '└── ' : '├── ';
169+
result += `${prefix}${connector}${entry.name}\n`;
170+
if (entry.isDirectory()) {
171+
const newPrefix = prefix + (isLast ? ' ' : '│ ');
172+
result += buildTree(path.join(dir, entry.name), newPrefix, depth + 1);
173+
}
174+
});
175+
return result;
176+
}
177+
178+
// ---------------------------------------------------------------------------
179+
// Markdown Generators
180+
// ---------------------------------------------------------------------------
181+
182+
function generateAreaDoc(areaKey: string, area: AreaInfo, allFiles: string[]): string {
183+
const fileCount = area.files.length;
184+
const totalLines = area.files.reduce((sum, f) => sum + lineCount(path.join(ROOT, f)), 0);
185+
186+
const entrySection = area.entryPoints.length > 0
187+
? area.entryPoints.map((e) => `- \`${e}\``).join('\n')
188+
: '- *(no index/main entry points detected)*';
189+
190+
const dirSection = area.directories.slice(0, 20)
191+
.map((d) => `- \`${d}/\``)
192+
.join('\n') || '- *(no dedicated directories detected)*';
193+
194+
const fileSection = area.files.slice(0, 30)
195+
.map((f) => `| \`${f}\` | ${lineCount(path.join(ROOT, f))} |`)
196+
.join('\n');
197+
198+
const moreFiles = area.files.length > 30
199+
? `\n*...and ${area.files.length - 30} more files*`
200+
: '';
201+
202+
return `# ${area.name} Codemap
203+
204+
**Last Updated:** ${TODAY}
205+
**Total Files:** ${fileCount}
206+
**Total Lines:** ${totalLines}
207+
208+
## Entry Points
209+
210+
${entrySection}
211+
212+
## Architecture
213+
214+
\`\`\`
215+
${area.name} Directory Structure
216+
${dirSection.replace(/- `/g, '').replace(/`\/$/gm, '/')}
217+
\`\`\`
218+
219+
## Key Modules
220+
221+
| File | Lines |
222+
|------|-------|
223+
${fileSection}${moreFiles}
224+
225+
## Data Flow
226+
227+
> Detected from file patterns. Review individual files for detailed data flow.
228+
229+
## External Dependencies
230+
231+
> Run \`npx jsdoc2md src/**/*.ts\` to extract JSDoc and identify external dependencies.
232+
233+
## Related Areas
234+
235+
- [INDEX](./INDEX.md) — Full overview
236+
- [Frontend](./frontend.md)
237+
- [Backend/API](./backend.md)
238+
- [Database](./database.md)
239+
- [Integrations](./integrations.md)
240+
- [Workers](./workers.md)
241+
`;
242+
}
243+
244+
function generateIndex(areas: Record<string, AreaInfo>, allFiles: string[]): string {
245+
const totalFiles = allFiles.length;
246+
const areaRows = Object.entries(areas)
247+
.map(([key, area]) => `| [${area.name}](./${key}.md) | ${area.files.length} files | ${area.directories.slice(0, 3).map((d) => `\`${d}\``).join(', ') || '—'} |`)
248+
.join('\n');
249+
250+
const topLevelTree = buildTree(SRC_DIR);
251+
252+
return `# Codebase Overview — CODEMAPS Index
253+
254+
**Last Updated:** ${TODAY}
255+
**Root:** \`${rel(SRC_DIR) || '.'}\`
256+
**Total Files Scanned:** ${totalFiles}
257+
258+
## Areas
259+
260+
| Area | Size | Key Directories |
261+
|------|------|-----------------|
262+
${areaRows}
263+
264+
## Repository Structure
265+
266+
\`\`\`
267+
${rel(SRC_DIR) || path.basename(SRC_DIR)}/
268+
${topLevelTree}\`\`\`
269+
270+
## How to Regenerate
271+
272+
\`\`\`bash
273+
npx tsx scripts/codemaps/generate.ts # Regenerate codemaps
274+
npx madge --image graph.svg src/ # Dependency graph (requires graphviz)
275+
npx jsdoc2md src/**/*.ts # Extract JSDoc
276+
\`\`\`
277+
278+
## Related Documentation
279+
280+
- [Frontend](./frontend.md) — UI components, pages, hooks
281+
- [Backend/API](./backend.md) — API routes, controllers, middleware
282+
- [Database](./database.md) — Models, schemas, migrations
283+
- [Integrations](./integrations.md) — External services & adapters
284+
- [Workers](./workers.md) — Background jobs, queues, cron tasks
285+
`;
286+
}
287+
288+
// ---------------------------------------------------------------------------
289+
// Main
290+
// ---------------------------------------------------------------------------
291+
292+
function main(): void {
293+
console.log(`[generate.ts] Scanning: ${SRC_DIR}`);
294+
console.log(`[generate.ts] Output: ${OUTPUT_DIR}`);
295+
296+
// Ensure output directory exists
297+
fs.mkdirSync(OUTPUT_DIR, { recursive: true });
298+
299+
// Walk the directory tree
300+
const allFiles = walkDir(SRC_DIR);
301+
console.log(`[generate.ts] Found ${allFiles.length} files`);
302+
303+
// Classify files into areas
304+
const areas = classifyFiles(allFiles);
305+
306+
// Generate INDEX.md
307+
const indexContent = generateIndex(areas, allFiles);
308+
const indexPath = path.join(OUTPUT_DIR, 'INDEX.md');
309+
fs.writeFileSync(indexPath, indexContent, 'utf8');
310+
console.log(`[generate.ts] Written: ${rel(indexPath)}`);
311+
312+
// Generate per-area codemaps
313+
for (const [key, area] of Object.entries(areas)) {
314+
const content = generateAreaDoc(key, area, allFiles);
315+
const outPath = path.join(OUTPUT_DIR, `${key}.md`);
316+
fs.writeFileSync(outPath, content, 'utf8');
317+
console.log(`[generate.ts] Written: ${rel(outPath)} (${area.files.length} files)`);
318+
}
319+
320+
console.log('\n[generate.ts] Done! Codemaps written to docs/CODEMAPS/');
321+
console.log('[generate.ts] Files generated:');
322+
console.log(' docs/CODEMAPS/INDEX.md');
323+
console.log(' docs/CODEMAPS/frontend.md');
324+
console.log(' docs/CODEMAPS/backend.md');
325+
console.log(' docs/CODEMAPS/database.md');
326+
console.log(' docs/CODEMAPS/integrations.md');
327+
console.log(' docs/CODEMAPS/workers.md');
328+
}
329+
330+
main();

0 commit comments

Comments
 (0)