Skip to content

Commit 156b89e

Browse files
authored
Merge pull request anomalyco#268 from pangerlkr/patch-6
feat: add scripts/codemaps/generate.ts — fixes anomalyco#247
2 parents 6f94c2e + 41ce1a5 commit 156b89e

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)