codeflowmap 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -5
- package/bin/code-mapper.js +623 -109
- package/package.json +2 -3
- package/web/assets/{index-C_ISsC7i.css → index-BkQ6cFaF.css} +1 -1
- package/web/assets/index-DUr1zMp_.js +330 -0
- package/web/graph.json +1 -1
- package/web/index.html +2 -2
- package/web/assets/index-6OE6CzFu.js +0 -330
package/bin/code-mapper.js
CHANGED
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
// @bun
|
|
3
3
|
|
|
4
4
|
// packages/cli/src/index.ts
|
|
5
|
-
import
|
|
5
|
+
import fs8 from "fs";
|
|
6
|
+
import path9 from "path";
|
|
6
7
|
import { Command } from "commander";
|
|
7
8
|
// packages/core/src/scan.ts
|
|
8
9
|
import fs2 from "fs";
|
|
@@ -179,31 +180,51 @@ async function init() {
|
|
|
179
180
|
extract(fileId, content, pyIds) {
|
|
180
181
|
const symbols = [];
|
|
181
182
|
const edges = [];
|
|
182
|
-
const
|
|
183
|
+
const calls = [];
|
|
183
184
|
const tree = parser.parse(content);
|
|
184
|
-
if (tree)
|
|
185
|
-
|
|
186
|
-
|
|
185
|
+
if (!tree)
|
|
186
|
+
return { symbols, edges, calls };
|
|
187
|
+
const resolve = getResolver(pyIds);
|
|
188
|
+
const symbolMap = new Map;
|
|
189
|
+
const moduleMap = new Map;
|
|
190
|
+
const seenEdge = new Set;
|
|
191
|
+
collectImports(tree.rootNode, fileId, resolve, symbols, edges, seenEdge, symbolMap, moduleMap);
|
|
192
|
+
const seenCall = new Set;
|
|
193
|
+
collectCalls(tree.rootNode, "<module>", symbolMap, moduleMap, calls, seenCall);
|
|
194
|
+
return { symbols, edges, calls };
|
|
187
195
|
}
|
|
188
196
|
};
|
|
189
197
|
}
|
|
190
|
-
function
|
|
198
|
+
function collectImports(node, fileId, resolve, symbols, edges, seen, symbolMap, moduleMap) {
|
|
191
199
|
for (const child of node.namedChildren) {
|
|
192
200
|
if (!child)
|
|
193
201
|
continue;
|
|
194
202
|
switch (child.type) {
|
|
195
203
|
case "import_statement":
|
|
196
|
-
for (const mod of importedModules(child)) {
|
|
197
|
-
const target =
|
|
198
|
-
if (target)
|
|
204
|
+
for (const { mod, alias } of importedModules(child)) {
|
|
205
|
+
const target = resolve(fileId, "", mod);
|
|
206
|
+
if (target) {
|
|
199
207
|
addEdge(edges, seen, fileId, target);
|
|
208
|
+
moduleMap.set(alias ?? mod, target);
|
|
209
|
+
}
|
|
200
210
|
}
|
|
201
211
|
break;
|
|
202
212
|
case "import_from_statement": {
|
|
203
|
-
const { dots, mod } =
|
|
204
|
-
const
|
|
205
|
-
if (
|
|
206
|
-
addEdge(edges, seen, fileId,
|
|
213
|
+
const { dots, mod, names, wildcard } = fromImports(child);
|
|
214
|
+
const modTarget = resolve(fileId, dots, mod);
|
|
215
|
+
if (modTarget)
|
|
216
|
+
addEdge(edges, seen, fileId, modTarget);
|
|
217
|
+
if (wildcard)
|
|
218
|
+
break;
|
|
219
|
+
for (const { local, orig } of names) {
|
|
220
|
+
const sub = resolve(fileId, dots, mod ? `${mod}.${orig}` : orig);
|
|
221
|
+
if (sub) {
|
|
222
|
+
addEdge(edges, seen, fileId, sub);
|
|
223
|
+
moduleMap.set(local, sub);
|
|
224
|
+
} else if (modTarget) {
|
|
225
|
+
symbolMap.set(local, { file: modTarget, symbol: orig });
|
|
226
|
+
}
|
|
227
|
+
}
|
|
207
228
|
break;
|
|
208
229
|
}
|
|
209
230
|
case "function_definition":
|
|
@@ -219,7 +240,39 @@ function walk(node, fileId, pyIds, symbols, edges, seen) {
|
|
|
219
240
|
}
|
|
220
241
|
break;
|
|
221
242
|
}
|
|
222
|
-
|
|
243
|
+
collectImports(child, fileId, resolve, symbols, edges, seen, symbolMap, moduleMap);
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
function collectCalls(node, fn, symbolMap, moduleMap, calls, seen) {
|
|
247
|
+
for (const child of node.namedChildren) {
|
|
248
|
+
if (!child)
|
|
249
|
+
continue;
|
|
250
|
+
if (child.type === "function_definition") {
|
|
251
|
+
const name = child.childForFieldName("name")?.text ?? fn;
|
|
252
|
+
collectCalls(child, name, symbolMap, moduleMap, calls, seen);
|
|
253
|
+
continue;
|
|
254
|
+
}
|
|
255
|
+
if (child.type === "call")
|
|
256
|
+
resolveCall(child, fn, symbolMap, moduleMap, calls, seen);
|
|
257
|
+
collectCalls(child, fn, symbolMap, moduleMap, calls, seen);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
function resolveCall(call, fn, symbolMap, moduleMap, calls, seen) {
|
|
261
|
+
const callee = call.childForFieldName("function");
|
|
262
|
+
if (!callee)
|
|
263
|
+
return;
|
|
264
|
+
if (callee.type === "identifier") {
|
|
265
|
+
const t = symbolMap.get(callee.text);
|
|
266
|
+
if (t)
|
|
267
|
+
addCall(calls, seen, fn, t.file, t.symbol);
|
|
268
|
+
} else if (callee.type === "attribute") {
|
|
269
|
+
const obj = callee.childForFieldName("object");
|
|
270
|
+
const attr = callee.childForFieldName("attribute");
|
|
271
|
+
if (obj && attr) {
|
|
272
|
+
const file = moduleMap.get(obj.text);
|
|
273
|
+
if (file)
|
|
274
|
+
addCall(calls, seen, fn, file, attr.text);
|
|
275
|
+
}
|
|
223
276
|
}
|
|
224
277
|
}
|
|
225
278
|
function importedModules(node) {
|
|
@@ -227,30 +280,44 @@ function importedModules(node) {
|
|
|
227
280
|
for (const c of node.namedChildren) {
|
|
228
281
|
if (!c)
|
|
229
282
|
continue;
|
|
230
|
-
if (c.type === "dotted_name")
|
|
231
|
-
mods.push(c.text);
|
|
232
|
-
else if (c.type === "aliased_import") {
|
|
233
|
-
const dn = c.
|
|
283
|
+
if (c.type === "dotted_name") {
|
|
284
|
+
mods.push({ mod: c.text });
|
|
285
|
+
} else if (c.type === "aliased_import") {
|
|
286
|
+
const dn = c.childForFieldName("name");
|
|
287
|
+
const alias = c.childForFieldName("alias");
|
|
234
288
|
if (dn)
|
|
235
|
-
mods.push(dn.text);
|
|
289
|
+
mods.push({ mod: dn.text, alias: alias?.text });
|
|
236
290
|
}
|
|
237
291
|
}
|
|
238
292
|
return mods;
|
|
239
293
|
}
|
|
240
|
-
function
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
294
|
+
function fromImports(node) {
|
|
295
|
+
const named = node.namedChildren.filter((c) => Boolean(c));
|
|
296
|
+
const first = named[0];
|
|
297
|
+
let dots = "";
|
|
298
|
+
let mod = "";
|
|
299
|
+
if (first?.type === "dotted_name") {
|
|
300
|
+
mod = first.text;
|
|
301
|
+
} else if (first?.type === "relative_import") {
|
|
302
|
+
const m = /^(\.+)(.*)$/.exec(first.text);
|
|
303
|
+
dots = m?.[1] ?? "";
|
|
304
|
+
mod = m?.[2] ?? "";
|
|
305
|
+
}
|
|
306
|
+
const names = [];
|
|
307
|
+
let wildcard = false;
|
|
308
|
+
for (const c of named.slice(1)) {
|
|
309
|
+
if (c.type === "wildcard_import")
|
|
310
|
+
wildcard = true;
|
|
311
|
+
else if (c.type === "dotted_name")
|
|
312
|
+
names.push({ local: c.text, orig: c.text });
|
|
313
|
+
else if (c.type === "aliased_import") {
|
|
314
|
+
const orig = c.childForFieldName("name")?.text;
|
|
315
|
+
const alias = c.childForFieldName("alias")?.text;
|
|
316
|
+
if (orig)
|
|
317
|
+
names.push({ local: alias ?? orig, orig });
|
|
249
318
|
}
|
|
250
|
-
if (c.type === "import_list" || c.type === "wildcard_import")
|
|
251
|
-
break;
|
|
252
319
|
}
|
|
253
|
-
return { dots
|
|
320
|
+
return { dots, mod, names, wildcard };
|
|
254
321
|
}
|
|
255
322
|
function addEdge(edges, seen, from, to) {
|
|
256
323
|
if (to === from || seen.has(to))
|
|
@@ -258,27 +325,62 @@ function addEdge(edges, seen, from, to) {
|
|
|
258
325
|
seen.add(to);
|
|
259
326
|
edges.push({ from, to, kind: "import" });
|
|
260
327
|
}
|
|
261
|
-
function
|
|
262
|
-
|
|
263
|
-
if (
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
const
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
return candidate;
|
|
328
|
+
function addCall(calls, seen, fromSymbol, to, toSymbol) {
|
|
329
|
+
const key = `${fromSymbol}\x00${to}\x00${toSymbol}`;
|
|
330
|
+
if (seen.has(key))
|
|
331
|
+
return;
|
|
332
|
+
seen.add(key);
|
|
333
|
+
calls.push({ fromSymbol, to, toSymbol });
|
|
334
|
+
}
|
|
335
|
+
var resolverCache = new WeakMap;
|
|
336
|
+
function getResolver(pyIds) {
|
|
337
|
+
const cached2 = resolverCache.get(pyIds);
|
|
338
|
+
if (cached2)
|
|
339
|
+
return cached2;
|
|
340
|
+
const byLastSegment = new Map;
|
|
341
|
+
for (const id of pyIds) {
|
|
342
|
+
const seg = id.endsWith("/__init__.py") ? id.slice(0, -"/__init__.py".length).split("/").pop() : id.endsWith(".py") ? id.slice(0, -3).split("/").pop() : undefined;
|
|
343
|
+
if (!seg)
|
|
344
|
+
continue;
|
|
345
|
+
(byLastSegment.get(seg) ?? byLastSegment.set(seg, []).get(seg)).push(id);
|
|
280
346
|
}
|
|
281
|
-
|
|
347
|
+
const moduleStem = (id) => id.endsWith("/__init__.py") ? id.slice(0, -"/__init__.py".length) : id.slice(0, -3);
|
|
348
|
+
const resolve = (fromId, dots, mod) => {
|
|
349
|
+
if (dots.length > 0) {
|
|
350
|
+
const parts = fromId.split("/");
|
|
351
|
+
parts.pop();
|
|
352
|
+
for (let i = 1;i < dots.length; i++)
|
|
353
|
+
parts.pop();
|
|
354
|
+
const full = [...parts, ...mod ? mod.split(".") : []].filter(Boolean);
|
|
355
|
+
if (full.length === 0)
|
|
356
|
+
return null;
|
|
357
|
+
const stem2 = full.join("/");
|
|
358
|
+
for (const c of [`${stem2}.py`, `${stem2}/__init__.py`])
|
|
359
|
+
if (pyIds.has(c))
|
|
360
|
+
return c;
|
|
361
|
+
return null;
|
|
362
|
+
}
|
|
363
|
+
const modParts = mod ? mod.split(".") : [];
|
|
364
|
+
if (modParts.length === 0)
|
|
365
|
+
return null;
|
|
366
|
+
const stem = modParts.join("/");
|
|
367
|
+
for (const c of [`${stem}.py`, `${stem}/__init__.py`])
|
|
368
|
+
if (pyIds.has(c))
|
|
369
|
+
return c;
|
|
370
|
+
if (modParts.length < 2)
|
|
371
|
+
return null;
|
|
372
|
+
const last = modParts[modParts.length - 1];
|
|
373
|
+
const matches = (byLastSegment.get(last) ?? []).filter((id) => {
|
|
374
|
+
const s = moduleStem(id);
|
|
375
|
+
return s === stem || s.endsWith(`/${stem}`);
|
|
376
|
+
});
|
|
377
|
+
if (matches.length === 0)
|
|
378
|
+
return null;
|
|
379
|
+
matches.sort((a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b));
|
|
380
|
+
return matches[0];
|
|
381
|
+
};
|
|
382
|
+
resolverCache.set(pyIds, resolve);
|
|
383
|
+
return resolve;
|
|
282
384
|
}
|
|
283
385
|
|
|
284
386
|
// packages/core/src/scan.ts
|
|
@@ -302,7 +404,7 @@ async function scanRepo(rootInput, opts = {}) {
|
|
|
302
404
|
}
|
|
303
405
|
const tsFiles = [];
|
|
304
406
|
const pyFiles = [];
|
|
305
|
-
|
|
407
|
+
walk(root, opts.outDirName, tsFiles, pyFiles);
|
|
306
408
|
const nodes = [];
|
|
307
409
|
const edges = [];
|
|
308
410
|
const calls = [];
|
|
@@ -315,12 +417,22 @@ async function scanRepo(rootInput, opts = {}) {
|
|
|
315
417
|
if (pyFiles.length) {
|
|
316
418
|
const pyIds = new Set(pyFiles.map((f) => toId(root, f)));
|
|
317
419
|
const python = await createPythonExtractor();
|
|
420
|
+
const declaredByFile = new Map;
|
|
421
|
+
const pendingCalls = [];
|
|
318
422
|
for (const f of pyFiles) {
|
|
319
423
|
const id = toId(root, f);
|
|
320
424
|
const content = fs2.readFileSync(assertInside(root, f), "utf8");
|
|
321
|
-
const { symbols, edges: e } = python.extract(id, content, pyIds);
|
|
425
|
+
const { symbols, edges: e, calls: c } = python.extract(id, content, pyIds);
|
|
322
426
|
nodes.push({ id, path: id, language: "python", symbols });
|
|
323
427
|
edges.push(...e);
|
|
428
|
+
declaredByFile.set(id, new Set(symbols.map((s) => s.name)));
|
|
429
|
+
for (const call of c)
|
|
430
|
+
pendingCalls.push({ from: id, ...call });
|
|
431
|
+
}
|
|
432
|
+
for (const call of pendingCalls) {
|
|
433
|
+
if (declaredByFile.get(call.to)?.has(call.toSymbol)) {
|
|
434
|
+
calls.push({ from: call.from, fromSymbol: call.fromSymbol, to: call.to, toSymbol: call.toSymbol });
|
|
435
|
+
}
|
|
324
436
|
}
|
|
325
437
|
}
|
|
326
438
|
nodes.sort((a, b) => a.id.localeCompare(b.id));
|
|
@@ -328,14 +440,14 @@ async function scanRepo(rootInput, opts = {}) {
|
|
|
328
440
|
calls.sort((a, b) => a.from.localeCompare(b.from) || a.fromSymbol.localeCompare(b.fromSymbol) || a.to.localeCompare(b.to) || a.toSymbol.localeCompare(b.toSymbol));
|
|
329
441
|
return { root, nodes, edges, calls };
|
|
330
442
|
}
|
|
331
|
-
function
|
|
443
|
+
function walk(dir, outDirName, tsFiles, pyFiles) {
|
|
332
444
|
for (const entry of fs2.readdirSync(dir, { withFileTypes: true })) {
|
|
333
445
|
const full = path3.join(dir, entry.name);
|
|
334
446
|
if (entry.isDirectory()) {
|
|
335
447
|
if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name) || entry.name === outDirName) {
|
|
336
448
|
continue;
|
|
337
449
|
}
|
|
338
|
-
|
|
450
|
+
walk(full, outDirName, tsFiles, pyFiles);
|
|
339
451
|
} else if (entry.isFile()) {
|
|
340
452
|
const ext = path3.extname(entry.name);
|
|
341
453
|
if (TS_JS_EXT.has(ext))
|
|
@@ -425,16 +537,374 @@ function renderNote(node, deps, dependents, callsOut, callsIn) {
|
|
|
425
537
|
return [...frontmatter, ...body].join(`
|
|
426
538
|
`);
|
|
427
539
|
}
|
|
540
|
+
// packages/core/src/curriculum/curriculum.ts
|
|
541
|
+
var ENTRYPOINT_RE = /(^|\/)(index|main|server|app|cli|routes?|mod|__main__)\.(ts|tsx|js|jsx|mjs|cjs|py)$/;
|
|
542
|
+
var TEST_RE = /(^|\/)(__tests__|tests?|__mocks__)\/|\.(test|spec|stories)\.|_test\.py$/;
|
|
543
|
+
var GENERATED_RE = /\.d\.ts$|\.(gen|generated|min)\.|(^|\/)migrations?\//;
|
|
544
|
+
function exclusionOf(id, hasSymbols, degree) {
|
|
545
|
+
if (TEST_RE.test(id))
|
|
546
|
+
return "tests";
|
|
547
|
+
if (GENERATED_RE.test(id))
|
|
548
|
+
return "generated";
|
|
549
|
+
if (!hasSymbols && degree === 0)
|
|
550
|
+
return "trivial";
|
|
551
|
+
return null;
|
|
552
|
+
}
|
|
553
|
+
function moduleOf(id) {
|
|
554
|
+
const slash = id.indexOf("/");
|
|
555
|
+
return slash === -1 ? "(root)" : id.slice(0, slash);
|
|
556
|
+
}
|
|
557
|
+
function buildCurriculum(graph, opts = {}) {
|
|
558
|
+
const order = opts.order ?? "foundations";
|
|
559
|
+
const spineSize = opts.spineSize ?? 7;
|
|
560
|
+
const maxSymbols = opts.maxSymbols ?? 8;
|
|
561
|
+
const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
|
|
562
|
+
const rawDegree = new Map;
|
|
563
|
+
for (const e of graph.edges) {
|
|
564
|
+
if (e.from === e.to)
|
|
565
|
+
continue;
|
|
566
|
+
rawDegree.set(e.from, (rawDegree.get(e.from) ?? 0) + 1);
|
|
567
|
+
rawDegree.set(e.to, (rawDegree.get(e.to) ?? 0) + 1);
|
|
568
|
+
}
|
|
569
|
+
const excluded = { tests: 0, generated: 0, trivial: 0, total: 0 };
|
|
570
|
+
const inScope = new Set;
|
|
571
|
+
for (const n of graph.nodes) {
|
|
572
|
+
const reason = exclusionOf(n.id, n.symbols.length > 0, rawDegree.get(n.id) ?? 0);
|
|
573
|
+
if (reason) {
|
|
574
|
+
excluded[reason]++;
|
|
575
|
+
excluded.total++;
|
|
576
|
+
} else {
|
|
577
|
+
inScope.add(n.id);
|
|
578
|
+
}
|
|
579
|
+
}
|
|
580
|
+
const deps = new Map;
|
|
581
|
+
const dependents = new Map;
|
|
582
|
+
for (const id of inScope) {
|
|
583
|
+
deps.set(id, new Set);
|
|
584
|
+
dependents.set(id, new Set);
|
|
585
|
+
}
|
|
586
|
+
for (const e of graph.edges) {
|
|
587
|
+
if (e.from === e.to || !inScope.has(e.from) || !inScope.has(e.to))
|
|
588
|
+
continue;
|
|
589
|
+
deps.get(e.from).add(e.to);
|
|
590
|
+
dependents.get(e.to).add(e.from);
|
|
591
|
+
}
|
|
592
|
+
const centrality = (id) => dependents.get(id)?.size ?? 0;
|
|
593
|
+
const { components, compOf } = tarjanScc(inScope, deps);
|
|
594
|
+
const cycles = components.filter((c) => c.length > 1).length;
|
|
595
|
+
const compDeps = new Map;
|
|
596
|
+
const compDependents = new Map;
|
|
597
|
+
const compImportance = new Map;
|
|
598
|
+
components.forEach((_, ci) => {
|
|
599
|
+
compDeps.set(ci, new Set);
|
|
600
|
+
compDependents.set(ci, new Set);
|
|
601
|
+
compImportance.set(ci, 0);
|
|
602
|
+
});
|
|
603
|
+
for (const id of inScope) {
|
|
604
|
+
const ci = compOf.get(id);
|
|
605
|
+
compImportance.set(ci, Math.max(compImportance.get(ci), centrality(id)));
|
|
606
|
+
for (const d of deps.get(id)) {
|
|
607
|
+
const cj = compOf.get(d);
|
|
608
|
+
if (cj !== ci) {
|
|
609
|
+
compDeps.get(ci).add(cj);
|
|
610
|
+
compDependents.get(cj).add(ci);
|
|
611
|
+
}
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
const blockedBy = order === "entrypoints" ? compDependents : compDeps;
|
|
615
|
+
const unblocks = order === "entrypoints" ? compDeps : compDependents;
|
|
616
|
+
const compOrder = topoSort(blockedBy, unblocks, compImportance);
|
|
617
|
+
const globalOrder = [];
|
|
618
|
+
for (const ci of compOrder) {
|
|
619
|
+
const members = [...components[ci]].sort((a, b) => centrality(b) - centrality(a) || a.localeCompare(b));
|
|
620
|
+
globalOrder.push(...members);
|
|
621
|
+
}
|
|
622
|
+
const rank = new Map(globalOrder.map((id, i) => [id, i]));
|
|
623
|
+
const isEntrypoint = (id) => ENTRYPOINT_RE.test(id) && centrality(id) === 0;
|
|
624
|
+
const spineIds = [...inScope].sort((a, b) => {
|
|
625
|
+
const ea = isEntrypoint(a) ? 1 : 0;
|
|
626
|
+
const eb = isEntrypoint(b) ? 1 : 0;
|
|
627
|
+
if (ea !== eb)
|
|
628
|
+
return eb - ea;
|
|
629
|
+
return centrality(b) - centrality(a) || a.localeCompare(b);
|
|
630
|
+
}).filter((id, i) => i < spineSize && (isEntrypoint(id) || centrality(id) > 1)).slice(0, spineSize);
|
|
631
|
+
const spineSet = new Set(spineIds);
|
|
632
|
+
const byModule = new Map;
|
|
633
|
+
for (const id of globalOrder) {
|
|
634
|
+
if (spineSet.has(id))
|
|
635
|
+
continue;
|
|
636
|
+
const m = moduleOf(id);
|
|
637
|
+
(byModule.get(m) ?? byModule.set(m, []).get(m)).push(id);
|
|
638
|
+
}
|
|
639
|
+
const moduleImportance = (ids) => ids.reduce((mx, id) => Math.max(mx, centrality(id)), 0);
|
|
640
|
+
const moduleChapters = [...byModule.entries()].sort((a, b) => moduleImportance(b[1]) - moduleImportance(a[1]) || a[0].localeCompare(b[0]));
|
|
641
|
+
const chapters = [];
|
|
642
|
+
if (spineIds.length) {
|
|
643
|
+
const spineSorted = spineIds.slice().sort((a, b) => {
|
|
644
|
+
if (order === "entrypoints") {
|
|
645
|
+
const ea = isEntrypoint(a) ? 1 : 0;
|
|
646
|
+
const eb = isEntrypoint(b) ? 1 : 0;
|
|
647
|
+
if (ea !== eb)
|
|
648
|
+
return eb - ea;
|
|
649
|
+
}
|
|
650
|
+
return centrality(b) - centrality(a) || a.localeCompare(b);
|
|
651
|
+
});
|
|
652
|
+
chapters.push({
|
|
653
|
+
title: "The spine",
|
|
654
|
+
kind: "spine",
|
|
655
|
+
blurb: order === "entrypoints" ? "The landmarks, entry points first: where execution begins and the modules the most code leans on. Start here, then follow the imports down." : "The load-bearing files: entry points that wire things together and the modules the most code depends on. Skim these first to get the map; you'll revisit them in context.",
|
|
656
|
+
stops: spineSorted.map((id) => makeStop(id))
|
|
657
|
+
});
|
|
658
|
+
}
|
|
659
|
+
const moduleTail = order === "entrypoints" ? "ordered top-down \u2014 each file before the things it pulls in." : "ordered so each file's dependencies come before it.";
|
|
660
|
+
for (const [mod, ids] of moduleChapters) {
|
|
661
|
+
ids.sort((a, b) => rank.get(a) - rank.get(b));
|
|
662
|
+
chapters.push({
|
|
663
|
+
title: mod,
|
|
664
|
+
kind: "module",
|
|
665
|
+
blurb: `${ids.length} file${ids.length === 1 ? "" : "s"} in ${mod}, ${moduleTail}`,
|
|
666
|
+
stops: ids.map((id) => makeStop(id))
|
|
667
|
+
});
|
|
668
|
+
}
|
|
669
|
+
const seen = new Set;
|
|
670
|
+
let stopNo = 0;
|
|
671
|
+
for (const ch of chapters) {
|
|
672
|
+
for (const stop of ch.stops) {
|
|
673
|
+
stop.order = ++stopNo;
|
|
674
|
+
const all = [...deps.get(stop.id) ?? []].sort();
|
|
675
|
+
stop.seenDeps = all.filter((d) => seen.has(d));
|
|
676
|
+
stop.newDeps = all.filter((d) => !seen.has(d));
|
|
677
|
+
seen.add(stop.id);
|
|
678
|
+
}
|
|
679
|
+
}
|
|
680
|
+
return {
|
|
681
|
+
root: graph.root,
|
|
682
|
+
order,
|
|
683
|
+
chapters,
|
|
684
|
+
totalStops: stopNo,
|
|
685
|
+
totalFiles: inScope.size,
|
|
686
|
+
excluded,
|
|
687
|
+
cycles
|
|
688
|
+
};
|
|
689
|
+
function roleOf(id) {
|
|
690
|
+
const inDeg = centrality(id);
|
|
691
|
+
const outDeg = deps.get(id)?.size ?? 0;
|
|
692
|
+
if (isEntrypoint(id))
|
|
693
|
+
return "entrypoint";
|
|
694
|
+
if (inDeg >= 8)
|
|
695
|
+
return "hub";
|
|
696
|
+
if (inDeg > 0 && outDeg === 0)
|
|
697
|
+
return "foundation";
|
|
698
|
+
if (inDeg === 0)
|
|
699
|
+
return "leaf";
|
|
700
|
+
return "core";
|
|
701
|
+
}
|
|
702
|
+
function makeStop(id) {
|
|
703
|
+
const node = nodeById.get(id);
|
|
704
|
+
const inDeg = centrality(id);
|
|
705
|
+
const outDeg = deps.get(id)?.size ?? 0;
|
|
706
|
+
const cluster = (components[compOf.get(id)] ?? []).filter((m) => m !== id);
|
|
707
|
+
const role = roleOf(id);
|
|
708
|
+
return {
|
|
709
|
+
id,
|
|
710
|
+
order: 0,
|
|
711
|
+
role,
|
|
712
|
+
dependedOnBy: inDeg,
|
|
713
|
+
dependsOn: outDeg,
|
|
714
|
+
seenDeps: [],
|
|
715
|
+
newDeps: [],
|
|
716
|
+
cluster: cluster.sort(),
|
|
717
|
+
symbols: node.symbols.slice(0, maxSymbols).map((s) => s.name),
|
|
718
|
+
summary: node.annotation?.summary,
|
|
719
|
+
why: whyLine(role, inDeg, outDeg, cluster.length)
|
|
720
|
+
};
|
|
721
|
+
}
|
|
722
|
+
}
|
|
723
|
+
function whyLine(role, inDeg, outDeg, clusterSiblings) {
|
|
724
|
+
if (clusterSiblings > 0) {
|
|
725
|
+
return `In an import cycle with ${clusterSiblings} other file${clusterSiblings === 1 ? "" : "s"} \u2014 read them as one unit.`;
|
|
726
|
+
}
|
|
727
|
+
switch (role) {
|
|
728
|
+
case "entrypoint":
|
|
729
|
+
return `Entry point \u2014 wires the app together and pulls in ${outDeg} module${outDeg === 1 ? "" : "s"} you'll meet next.`;
|
|
730
|
+
case "hub":
|
|
731
|
+
return `Hub: imported by ${inDeg} files. Load-bearing \u2014 learn its shape and names.`;
|
|
732
|
+
case "foundation":
|
|
733
|
+
return `Foundation: depends on nothing internal, and ${inDeg} file${inDeg === 1 ? "" : "s"} build on it.`;
|
|
734
|
+
case "leaf":
|
|
735
|
+
return `Standalone \u2014 nothing imports it; depends on ${outDeg} module${outDeg === 1 ? "" : "s"}.`;
|
|
736
|
+
default:
|
|
737
|
+
return `${inDeg} importer${inDeg === 1 ? "" : "s"}, ${outDeg} dependenc${outDeg === 1 ? "y" : "ies"}.`;
|
|
738
|
+
}
|
|
739
|
+
}
|
|
740
|
+
function tarjanScc(nodes, deps) {
|
|
741
|
+
const index = new Map;
|
|
742
|
+
const low = new Map;
|
|
743
|
+
const onStack = new Set;
|
|
744
|
+
const stack = [];
|
|
745
|
+
const components = [];
|
|
746
|
+
const compOf = new Map;
|
|
747
|
+
let counter = 0;
|
|
748
|
+
const order = [...nodes].sort();
|
|
749
|
+
for (const start of order) {
|
|
750
|
+
if (index.has(start))
|
|
751
|
+
continue;
|
|
752
|
+
const work = [];
|
|
753
|
+
const pushNode = (node) => {
|
|
754
|
+
index.set(node, counter);
|
|
755
|
+
low.set(node, counter);
|
|
756
|
+
counter++;
|
|
757
|
+
stack.push(node);
|
|
758
|
+
onStack.add(node);
|
|
759
|
+
work.push({ node, nbrs: [...deps.get(node) ?? []].sort(), i: 0 });
|
|
760
|
+
};
|
|
761
|
+
pushNode(start);
|
|
762
|
+
while (work.length) {
|
|
763
|
+
const frame = work[work.length - 1];
|
|
764
|
+
if (frame.i < frame.nbrs.length) {
|
|
765
|
+
const w = frame.nbrs[frame.i++];
|
|
766
|
+
if (!nodes.has(w))
|
|
767
|
+
continue;
|
|
768
|
+
if (!index.has(w)) {
|
|
769
|
+
pushNode(w);
|
|
770
|
+
} else if (onStack.has(w)) {
|
|
771
|
+
low.set(frame.node, Math.min(low.get(frame.node), index.get(w)));
|
|
772
|
+
}
|
|
773
|
+
} else {
|
|
774
|
+
if (low.get(frame.node) === index.get(frame.node)) {
|
|
775
|
+
const comp = [];
|
|
776
|
+
for (;; ) {
|
|
777
|
+
const w = stack.pop();
|
|
778
|
+
onStack.delete(w);
|
|
779
|
+
comp.push(w);
|
|
780
|
+
compOf.set(w, components.length);
|
|
781
|
+
if (w === frame.node)
|
|
782
|
+
break;
|
|
783
|
+
}
|
|
784
|
+
components.push(comp);
|
|
785
|
+
}
|
|
786
|
+
work.pop();
|
|
787
|
+
const parent = work[work.length - 1];
|
|
788
|
+
if (parent) {
|
|
789
|
+
parent.node && low.set(parent.node, Math.min(low.get(parent.node), low.get(frame.node)));
|
|
790
|
+
}
|
|
791
|
+
}
|
|
792
|
+
}
|
|
793
|
+
}
|
|
794
|
+
return { components, compOf };
|
|
795
|
+
}
|
|
796
|
+
function topoSort(blockedBy, unblocks, importance) {
|
|
797
|
+
const remaining = new Map;
|
|
798
|
+
for (const [c, set] of blockedBy)
|
|
799
|
+
remaining.set(c, set.size);
|
|
800
|
+
const pick = (a, b) => (importance.get(b) ?? 0) - (importance.get(a) ?? 0) || a - b;
|
|
801
|
+
let ready = [...remaining.entries()].filter(([, n]) => n === 0).map(([c]) => c);
|
|
802
|
+
const out = [];
|
|
803
|
+
const emitted = new Set;
|
|
804
|
+
while (ready.length) {
|
|
805
|
+
ready.sort(pick);
|
|
806
|
+
const c = ready.shift();
|
|
807
|
+
if (emitted.has(c))
|
|
808
|
+
continue;
|
|
809
|
+
emitted.add(c);
|
|
810
|
+
out.push(c);
|
|
811
|
+
for (const succ of unblocks.get(c) ?? []) {
|
|
812
|
+
remaining.set(succ, (remaining.get(succ) ?? 0) - 1);
|
|
813
|
+
if (remaining.get(succ) === 0)
|
|
814
|
+
ready.push(succ);
|
|
815
|
+
}
|
|
816
|
+
}
|
|
817
|
+
if (out.length < blockedBy.size) {
|
|
818
|
+
for (const c of [...blockedBy.keys()].sort(pick))
|
|
819
|
+
if (!emitted.has(c))
|
|
820
|
+
out.push(c);
|
|
821
|
+
}
|
|
822
|
+
return out;
|
|
823
|
+
}
|
|
824
|
+
// packages/core/src/curriculum/tour-md.ts
|
|
825
|
+
function renderTour(cur) {
|
|
826
|
+
const lines = [];
|
|
827
|
+
const story = cur.order === "entrypoints" ? "starting at the entry points and following imports downward, so you see how the app branches into detail" : "each file is introduced after the files it depends on, so you never read a file before its building blocks";
|
|
828
|
+
lines.push("---", "title: Guided reading order", `order: ${cur.order}`, `stops: ${cur.totalStops}`, `files: ${cur.totalFiles}`, `cycles: ${cur.cycles}`, "---", "", `# Guided reading order \u2014 ${cur.order === "entrypoints" ? "entry points first" : "foundations first"}`, "", `A deterministic tour of this repo \u2014 **${cur.totalStops} stops** across ${cur.chapters.length} chapters. ` + `Order is derived from the import graph: import cycles are folded together and ${story}.`, "");
|
|
829
|
+
if (cur.excluded.total > 0) {
|
|
830
|
+
const parts = [];
|
|
831
|
+
if (cur.excluded.tests)
|
|
832
|
+
parts.push(`${cur.excluded.tests} test`);
|
|
833
|
+
if (cur.excluded.generated)
|
|
834
|
+
parts.push(`${cur.excluded.generated} generated`);
|
|
835
|
+
if (cur.excluded.trivial)
|
|
836
|
+
parts.push(`${cur.excluded.trivial} inert`);
|
|
837
|
+
lines.push(`> Skipped ${cur.excluded.total} file${cur.excluded.total === 1 ? "" : "s"} (${parts.join(", ")}).`, "");
|
|
838
|
+
}
|
|
839
|
+
if (cur.cycles > 0) {
|
|
840
|
+
lines.push(`> ${cur.cycles} import cycle${cur.cycles === 1 ? "" : "s"} folded \u2014 cyclic files are flagged "read together".`, "");
|
|
841
|
+
}
|
|
842
|
+
lines.push("## Chapters", "");
|
|
843
|
+
cur.chapters.forEach((ch, i) => {
|
|
844
|
+
lines.push(`${i + 1}. **${ch.title}** \u2014 ${ch.stops.length} stop${ch.stops.length === 1 ? "" : "s"}`);
|
|
845
|
+
});
|
|
846
|
+
lines.push("");
|
|
847
|
+
for (const ch of cur.chapters) {
|
|
848
|
+
lines.push("---", "", `## ${ch.title}`, "", `_${ch.blurb}_`, "");
|
|
849
|
+
for (const stop of ch.stops) {
|
|
850
|
+
lines.push(...renderStop(stop));
|
|
851
|
+
}
|
|
852
|
+
}
|
|
853
|
+
lines.push("---", "", "_Generated by codeflowmap \u2014 order is from static analysis, not an LLM. " + "Summaries (if present) come from the annotation pass._", "");
|
|
854
|
+
return lines.join(`
|
|
855
|
+
`);
|
|
856
|
+
}
|
|
857
|
+
function renderStop(stop) {
|
|
858
|
+
const out = [];
|
|
859
|
+
out.push(`### ${stop.order}. [[${stop.id}]]`, "");
|
|
860
|
+
out.push(`\`${roleLabel(stop)}\` \xB7 ${stop.why}`, "");
|
|
861
|
+
if (stop.summary)
|
|
862
|
+
out.push(stop.summary, "");
|
|
863
|
+
if (stop.cluster.length) {
|
|
864
|
+
out.push(`**Read together:** ${stop.cluster.map((c) => `[[${c}]]`).join(", ")}`, "");
|
|
865
|
+
}
|
|
866
|
+
if (stop.seenDeps.length) {
|
|
867
|
+
out.push(`**Builds on (already seen):** ${stop.seenDeps.map((d) => `[[${d}]]`).join(", ")}`, "");
|
|
868
|
+
}
|
|
869
|
+
if (stop.newDeps.length) {
|
|
870
|
+
out.push(`**Pulls in (coming up):** ${stop.newDeps.map((d) => `[[${d}]]`).join(", ")}`, "");
|
|
871
|
+
}
|
|
872
|
+
if (stop.symbols.length) {
|
|
873
|
+
out.push(`**Symbols:** ${stop.symbols.map((s) => `\`${s}\``).join(", ")}`, "");
|
|
874
|
+
}
|
|
875
|
+
return out;
|
|
876
|
+
}
|
|
877
|
+
function roleLabel(stop) {
|
|
878
|
+
switch (stop.role) {
|
|
879
|
+
case "entrypoint":
|
|
880
|
+
return "entry point";
|
|
881
|
+
default:
|
|
882
|
+
return stop.role;
|
|
883
|
+
}
|
|
884
|
+
}
|
|
885
|
+
// packages/core/src/curriculum/write.ts
|
|
886
|
+
import fs4 from "fs";
|
|
887
|
+
import path5 from "path";
|
|
888
|
+
function writeTour(cur, outDirInput) {
|
|
889
|
+
const outDir = assertSafeOutputDir(outDirInput);
|
|
890
|
+
fs4.mkdirSync(outDir, { recursive: true });
|
|
891
|
+
const file = assertInside(outDir, path5.join(outDir, "TOUR.md"));
|
|
892
|
+
fs4.writeFileSync(file, renderTour(cur));
|
|
893
|
+
return { file, stops: cur.totalStops };
|
|
894
|
+
}
|
|
428
895
|
// packages/annotate/src/types.ts
|
|
429
|
-
|
|
430
|
-
var
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
896
|
+
var LIST_FIELDS = ["writes", "reads", "config", "auth", "flows"];
|
|
897
|
+
var isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
|
|
898
|
+
function validateAnnotation(raw) {
|
|
899
|
+
if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
|
|
900
|
+
throw new Error("Model output is not a JSON object");
|
|
901
|
+
}
|
|
902
|
+
const o = raw;
|
|
903
|
+
const out = { summary: typeof o.summary === "string" ? o.summary : "" };
|
|
904
|
+
for (const k of LIST_FIELDS)
|
|
905
|
+
out[k] = isStringArray(o[k]) ? o[k] : [];
|
|
906
|
+
return out;
|
|
907
|
+
}
|
|
438
908
|
|
|
439
909
|
// packages/annotate/src/prompt.ts
|
|
440
910
|
var MAX_SOURCE_CHARS = 12000;
|
|
@@ -502,7 +972,7 @@ class OpenAICompatAnnotator {
|
|
|
502
972
|
}
|
|
503
973
|
}
|
|
504
974
|
function parseAnnotation(content) {
|
|
505
|
-
return
|
|
975
|
+
return validateAnnotation(extractJson(content));
|
|
506
976
|
}
|
|
507
977
|
function extractJson(content) {
|
|
508
978
|
const trimmed = content.trim();
|
|
@@ -564,22 +1034,22 @@ function requireKey(key, provider, envName) {
|
|
|
564
1034
|
}
|
|
565
1035
|
}
|
|
566
1036
|
// packages/annotate/src/annotate.ts
|
|
567
|
-
import
|
|
568
|
-
import
|
|
1037
|
+
import fs6 from "fs";
|
|
1038
|
+
import path7 from "path";
|
|
569
1039
|
|
|
570
1040
|
// packages/annotate/src/cache.ts
|
|
571
1041
|
import { createHash } from "crypto";
|
|
572
|
-
import
|
|
573
|
-
import
|
|
1042
|
+
import fs5 from "fs";
|
|
1043
|
+
import path6 from "path";
|
|
574
1044
|
var ANNOTATION_SCHEMA_VERSION = "2";
|
|
575
1045
|
|
|
576
1046
|
class AnnotationCache {
|
|
577
1047
|
file;
|
|
578
1048
|
data = {};
|
|
579
1049
|
constructor(cacheDir) {
|
|
580
|
-
this.file =
|
|
1050
|
+
this.file = path6.join(cacheDir, "annotations.json");
|
|
581
1051
|
try {
|
|
582
|
-
this.data = JSON.parse(
|
|
1052
|
+
this.data = JSON.parse(fs5.readFileSync(this.file, "utf8"));
|
|
583
1053
|
} catch {
|
|
584
1054
|
this.data = {};
|
|
585
1055
|
}
|
|
@@ -594,22 +1064,22 @@ class AnnotationCache {
|
|
|
594
1064
|
this.data[key] = annotation;
|
|
595
1065
|
}
|
|
596
1066
|
save() {
|
|
597
|
-
|
|
598
|
-
|
|
1067
|
+
fs5.mkdirSync(path6.dirname(this.file), { recursive: true });
|
|
1068
|
+
fs5.writeFileSync(this.file, JSON.stringify(this.data, null, 2));
|
|
599
1069
|
}
|
|
600
1070
|
}
|
|
601
1071
|
|
|
602
1072
|
// packages/annotate/src/annotate.ts
|
|
603
1073
|
async function annotateGraph(outDir, annotator, opts = {}) {
|
|
604
|
-
const graphPath =
|
|
605
|
-
const graph = JSON.parse(
|
|
1074
|
+
const graphPath = path7.join(outDir, "graph.json");
|
|
1075
|
+
const graph = JSON.parse(fs6.readFileSync(graphPath, "utf8"));
|
|
606
1076
|
const deps = new Map;
|
|
607
1077
|
const dependents = new Map;
|
|
608
1078
|
for (const e of graph.edges) {
|
|
609
1079
|
(deps.get(e.from) ?? deps.set(e.from, []).get(e.from)).push(e.to);
|
|
610
1080
|
(dependents.get(e.to) ?? dependents.set(e.to, []).get(e.to)).push(e.from);
|
|
611
1081
|
}
|
|
612
|
-
const cache = new AnnotationCache(
|
|
1082
|
+
const cache = new AnnotationCache(path7.join(outDir, ".cache"));
|
|
613
1083
|
const result = {
|
|
614
1084
|
annotated: 0,
|
|
615
1085
|
cached: 0,
|
|
@@ -625,8 +1095,8 @@ async function annotateGraph(outDir, annotator, opts = {}) {
|
|
|
625
1095
|
if (!node)
|
|
626
1096
|
return;
|
|
627
1097
|
try {
|
|
628
|
-
const abs = assertInside(graph.root,
|
|
629
|
-
const source =
|
|
1098
|
+
const abs = assertInside(graph.root, path7.join(graph.root, node.id));
|
|
1099
|
+
const source = fs6.readFileSync(abs, "utf8");
|
|
630
1100
|
const key = AnnotationCache.key(annotator.model, source);
|
|
631
1101
|
const hit = cache.get(key);
|
|
632
1102
|
if (hit) {
|
|
@@ -654,7 +1124,7 @@ async function annotateGraph(outDir, annotator, opts = {}) {
|
|
|
654
1124
|
}
|
|
655
1125
|
await Promise.all(Array.from({ length: workers }, () => worker()));
|
|
656
1126
|
cache.save();
|
|
657
|
-
|
|
1127
|
+
fs6.writeFileSync(graphPath, JSON.stringify(graph, null, 2));
|
|
658
1128
|
writeVault(graph, outDir);
|
|
659
1129
|
return result;
|
|
660
1130
|
}
|
|
@@ -680,14 +1150,14 @@ function isRetryable(err) {
|
|
|
680
1150
|
return status === 429 || status >= 500;
|
|
681
1151
|
}
|
|
682
1152
|
// packages/cli/src/serve.ts
|
|
683
|
-
import
|
|
1153
|
+
import fs7 from "fs";
|
|
684
1154
|
import os from "os";
|
|
685
|
-
import
|
|
1155
|
+
import path8 from "path";
|
|
686
1156
|
function expandHome(p) {
|
|
687
1157
|
if (p === "~")
|
|
688
1158
|
return os.homedir();
|
|
689
1159
|
if (p.startsWith("~/") || p.startsWith("~\\"))
|
|
690
|
-
return
|
|
1160
|
+
return path8.join(os.homedir(), p.slice(2));
|
|
691
1161
|
return p;
|
|
692
1162
|
}
|
|
693
1163
|
function guardLocal(req, port) {
|
|
@@ -727,12 +1197,12 @@ function createMutex() {
|
|
|
727
1197
|
};
|
|
728
1198
|
}
|
|
729
1199
|
async function serve(vaultInput, opts = {}) {
|
|
730
|
-
const webDir = opts.webDir ?
|
|
1200
|
+
const webDir = opts.webDir ? path8.resolve(opts.webDir) : resolveWebDir();
|
|
731
1201
|
await ensureWebBuilt(webDir);
|
|
732
1202
|
let currentVault = null;
|
|
733
1203
|
if (vaultInput) {
|
|
734
|
-
const v =
|
|
735
|
-
if (
|
|
1204
|
+
const v = path8.resolve(vaultInput);
|
|
1205
|
+
if (fs7.existsSync(path8.join(v, "graph.json")))
|
|
736
1206
|
currentVault = v;
|
|
737
1207
|
else
|
|
738
1208
|
console.warn(`No graph.json in ${v} yet \u2014 scan a directory from the UI.`);
|
|
@@ -754,13 +1224,16 @@ async function serve(vaultInput, opts = {}) {
|
|
|
754
1224
|
if (pathname === "/graph.json") {
|
|
755
1225
|
if (!currentVault)
|
|
756
1226
|
return new Response("No vault scanned yet.", { status: 404 });
|
|
757
|
-
return new Response(Bun.file(
|
|
1227
|
+
return new Response(Bun.file(path8.join(currentVault, "graph.json")), {
|
|
758
1228
|
headers: { "content-type": "application/json", "cache-control": "no-store" }
|
|
759
1229
|
});
|
|
760
1230
|
}
|
|
761
1231
|
if (pathname === "/api/ls") {
|
|
762
1232
|
return handleLs(new URL(req.url).searchParams.get("path"));
|
|
763
1233
|
}
|
|
1234
|
+
if (pathname === "/api/curriculum") {
|
|
1235
|
+
return handleCurriculum(currentVault, new URL(req.url).searchParams.get("order"));
|
|
1236
|
+
}
|
|
764
1237
|
if (pathname === "/api/scan" && req.method === "POST") {
|
|
765
1238
|
return withVaultLock(async () => {
|
|
766
1239
|
const { response, vault } = await handleScan(req);
|
|
@@ -783,10 +1256,10 @@ async function serve(vaultInput, opts = {}) {
|
|
|
783
1256
|
}
|
|
784
1257
|
function handleLs(query) {
|
|
785
1258
|
const target = query?.trim() ? expandHome(query.trim()) : process.cwd();
|
|
786
|
-
const dir =
|
|
1259
|
+
const dir = path8.resolve(target);
|
|
787
1260
|
let stat;
|
|
788
1261
|
try {
|
|
789
|
-
stat =
|
|
1262
|
+
stat = fs7.statSync(dir);
|
|
790
1263
|
} catch {
|
|
791
1264
|
return Response.json({ error: `Cannot access: ${dir}` }, { status: 400 });
|
|
792
1265
|
}
|
|
@@ -795,21 +1268,36 @@ function handleLs(query) {
|
|
|
795
1268
|
}
|
|
796
1269
|
let entries = [];
|
|
797
1270
|
try {
|
|
798
|
-
entries =
|
|
1271
|
+
entries = fs7.readdirSync(dir, { withFileTypes: true }).filter((e) => {
|
|
799
1272
|
try {
|
|
800
1273
|
if (e.isDirectory())
|
|
801
1274
|
return true;
|
|
802
|
-
return e.isSymbolicLink() &&
|
|
1275
|
+
return e.isSymbolicLink() && fs7.statSync(path8.join(dir, e.name)).isDirectory();
|
|
803
1276
|
} catch {
|
|
804
1277
|
return false;
|
|
805
1278
|
}
|
|
806
|
-
}).map((e) => ({ name: e.name, path:
|
|
1279
|
+
}).map((e) => ({ name: e.name, path: path8.join(dir, e.name) })).sort((a, b) => a.name.localeCompare(b.name));
|
|
807
1280
|
} catch (err) {
|
|
808
1281
|
return Response.json({ error: err.message }, { status: 400 });
|
|
809
1282
|
}
|
|
810
|
-
const parent =
|
|
1283
|
+
const parent = path8.dirname(dir);
|
|
811
1284
|
return Response.json({ path: dir, parent: parent === dir ? null : parent, entries });
|
|
812
1285
|
}
|
|
1286
|
+
function handleCurriculum(currentVault, orderParam) {
|
|
1287
|
+
if (!currentVault)
|
|
1288
|
+
return Response.json({ error: "Scan a directory first." }, { status: 400 });
|
|
1289
|
+
const graphJson = path8.join(currentVault, "graph.json");
|
|
1290
|
+
if (!fs7.existsSync(graphJson)) {
|
|
1291
|
+
return Response.json({ error: "No graph.json in the current vault." }, { status: 404 });
|
|
1292
|
+
}
|
|
1293
|
+
const order = orderParam === "entrypoints" ? "entrypoints" : "foundations";
|
|
1294
|
+
try {
|
|
1295
|
+
const graph = JSON.parse(fs7.readFileSync(graphJson, "utf8"));
|
|
1296
|
+
return Response.json(buildCurriculum(graph, { order }));
|
|
1297
|
+
} catch (err) {
|
|
1298
|
+
return Response.json({ error: err.message }, { status: 500 });
|
|
1299
|
+
}
|
|
1300
|
+
}
|
|
813
1301
|
async function handleScan(req) {
|
|
814
1302
|
let body;
|
|
815
1303
|
try {
|
|
@@ -821,16 +1309,16 @@ async function handleScan(req) {
|
|
|
821
1309
|
if (!target) {
|
|
822
1310
|
return { response: Response.json({ error: "A directory path is required." }, { status: 400 }) };
|
|
823
1311
|
}
|
|
824
|
-
const root =
|
|
825
|
-
if (!
|
|
1312
|
+
const root = path8.resolve(expandHome(target));
|
|
1313
|
+
if (!fs7.existsSync(root)) {
|
|
826
1314
|
return { response: Response.json({ error: `Path not found: ${root}` }, { status: 400 }) };
|
|
827
1315
|
}
|
|
828
|
-
if (!
|
|
1316
|
+
if (!fs7.statSync(root).isDirectory()) {
|
|
829
1317
|
return { response: Response.json({ error: `Not a directory: ${root}` }, { status: 400 }) };
|
|
830
1318
|
}
|
|
831
|
-
const out = body.out?.trim() ?
|
|
1319
|
+
const out = body.out?.trim() ? path8.resolve(body.out) : path8.join(root, ".codemap");
|
|
832
1320
|
try {
|
|
833
|
-
const graph = await scanRepo(root, { outDirName:
|
|
1321
|
+
const graph = await scanRepo(root, { outDirName: path8.basename(out) });
|
|
834
1322
|
const { files } = writeVault(graph, out);
|
|
835
1323
|
return {
|
|
836
1324
|
response: Response.json({
|
|
@@ -892,39 +1380,39 @@ async function handleAnnotate(req, currentVault, lock) {
|
|
|
892
1380
|
}
|
|
893
1381
|
function serveStatic(webDir, pathname) {
|
|
894
1382
|
const rel = pathname === "/" ? "index.html" : pathname.replace(/^\/+/, "");
|
|
895
|
-
const resolved =
|
|
896
|
-
if (resolved !== webDir && !resolved.startsWith(webDir +
|
|
1383
|
+
const resolved = path8.resolve(webDir, rel);
|
|
1384
|
+
if (resolved !== webDir && !resolved.startsWith(webDir + path8.sep)) {
|
|
897
1385
|
return new Response("Forbidden", { status: 403 });
|
|
898
1386
|
}
|
|
899
|
-
if (
|
|
1387
|
+
if (fs7.existsSync(resolved) && fs7.statSync(resolved).isFile()) {
|
|
900
1388
|
return new Response(Bun.file(resolved));
|
|
901
1389
|
}
|
|
902
|
-
return new Response(Bun.file(
|
|
1390
|
+
return new Response(Bun.file(path8.join(webDir, "index.html")), {
|
|
903
1391
|
headers: { "content-type": "text/html" }
|
|
904
1392
|
});
|
|
905
1393
|
}
|
|
906
1394
|
function resolveWebDir() {
|
|
907
1395
|
const candidates = [
|
|
908
|
-
|
|
909
|
-
|
|
1396
|
+
path8.resolve(import.meta.dir, "../../web/dist"),
|
|
1397
|
+
path8.resolve(import.meta.dir, "../web")
|
|
910
1398
|
];
|
|
911
1399
|
for (const c of candidates) {
|
|
912
|
-
if (
|
|
1400
|
+
if (fs7.existsSync(path8.join(c, "index.html")))
|
|
913
1401
|
return c;
|
|
914
1402
|
}
|
|
915
1403
|
return candidates[0];
|
|
916
1404
|
}
|
|
917
1405
|
async function ensureWebBuilt(webDir) {
|
|
918
|
-
if (
|
|
1406
|
+
if (fs7.existsSync(path8.join(webDir, "index.html")))
|
|
919
1407
|
return;
|
|
920
|
-
const webPkg =
|
|
921
|
-
if (!
|
|
1408
|
+
const webPkg = path8.resolve(webDir, "..");
|
|
1409
|
+
if (!fs7.existsSync(path8.join(webPkg, "vite.config.ts"))) {
|
|
922
1410
|
throw new Error(`Web UI assets missing at ${webDir}. Try reinstalling code-mapper.`);
|
|
923
1411
|
}
|
|
924
1412
|
console.log("Building web UI (first run)\u2026");
|
|
925
1413
|
const proc = Bun.spawn(["bunx", "vite", "build", webPkg], { stdout: "inherit", stderr: "inherit" });
|
|
926
1414
|
const code = await proc.exited;
|
|
927
|
-
if (code !== 0 || !
|
|
1415
|
+
if (code !== 0 || !fs7.existsSync(path8.join(webDir, "index.html"))) {
|
|
928
1416
|
throw new Error(`Failed to build the web UI at ${webPkg}.`);
|
|
929
1417
|
}
|
|
930
1418
|
}
|
|
@@ -933,7 +1421,7 @@ async function ensureWebBuilt(webDir) {
|
|
|
933
1421
|
var program = new Command;
|
|
934
1422
|
program.name("codemap").description("Map your codebase's dependencies and data flows into an Obsidian-linkable vault").version("0.1.1");
|
|
935
1423
|
program.command("scan").description("Scan a directory and generate the dependency graph + Markdown vault").argument("<dir>", "target directory to scan").option("-o, --out <dir>", "output vault directory", ".codemap").action(async (dir, options) => {
|
|
936
|
-
const graph = await scanRepo(dir, { outDirName:
|
|
1424
|
+
const graph = await scanRepo(dir, { outDirName: path9.basename(options.out) });
|
|
937
1425
|
const { files, outDir } = writeVault(graph, options.out);
|
|
938
1426
|
console.log(`Scanned ${graph.nodes.length} files, ${graph.edges.length} import edges.`);
|
|
939
1427
|
console.log(`Wrote ${files} notes + graph.json -> ${outDir}`);
|
|
@@ -955,6 +1443,32 @@ program.command("annotate").description("Add the LLM semantic layer (summary, wr
|
|
|
955
1443
|
`);
|
|
956
1444
|
console.log(`Done: ${res.annotated} annotated, ${res.cached} cached, ${res.failed} failed (of ${res.total}).`);
|
|
957
1445
|
});
|
|
1446
|
+
program.command("onboard").description("Build a guided reading order (TOUR.md) \u2014 where to start and what to read next").argument("<dir>", "target directory to onboard into").option("-o, --out <dir>", "vault directory", ".codemap").option("--order <mode>", "reading order: foundations | entrypoints", "foundations").action(async (dir, options) => {
|
|
1447
|
+
const order = options.order === "entrypoints" ? "entrypoints" : "foundations";
|
|
1448
|
+
const out = path9.isAbsolute(options.out) ? options.out : path9.join(path9.resolve(dir), options.out);
|
|
1449
|
+
const graphJson = path9.join(out, "graph.json");
|
|
1450
|
+
let graph;
|
|
1451
|
+
if (fs8.existsSync(graphJson)) {
|
|
1452
|
+
graph = JSON.parse(fs8.readFileSync(graphJson, "utf8"));
|
|
1453
|
+
console.log(`Using existing graph: ${graphJson}`);
|
|
1454
|
+
} else {
|
|
1455
|
+
graph = await scanRepo(dir, { outDirName: path9.basename(out) });
|
|
1456
|
+
writeVault(graph, out);
|
|
1457
|
+
console.log(`Scanned ${graph.nodes.length} files, ${graph.edges.length} import edges.`);
|
|
1458
|
+
}
|
|
1459
|
+
const cur = buildCurriculum(graph, { order });
|
|
1460
|
+
const { file, stops } = writeTour(cur, out);
|
|
1461
|
+
console.log(`
|
|
1462
|
+
Tour (${order} first): ${stops} stops across ${cur.chapters.length} chapters \u2192 ${file}`);
|
|
1463
|
+
for (const ch of cur.chapters) {
|
|
1464
|
+
console.log(` \u2022 ${ch.title} (${ch.stops.length})`);
|
|
1465
|
+
}
|
|
1466
|
+
if (cur.cycles)
|
|
1467
|
+
console.log(` ${cur.cycles} import cycle(s) folded.`);
|
|
1468
|
+
if (cur.excluded.total) {
|
|
1469
|
+
console.log(` skipped ${cur.excluded.total} files (${cur.excluded.tests} test, ${cur.excluded.generated} generated, ${cur.excluded.trivial} inert).`);
|
|
1470
|
+
}
|
|
1471
|
+
});
|
|
958
1472
|
program.command("serve").description("Launch the web UI \u2014 scan, annotate, and explore from the browser").argument("[vault]", "existing vault to open (optional; you can scan from the UI)").option("--port <n>", "port to listen on", "4321").option("--web <dir>", "path to the built web UI (defaults to packages/web/dist)").action(async (vault, options) => {
|
|
959
1473
|
await serve(vault, { port: Number(options.port), webDir: options.web });
|
|
960
1474
|
});
|