codeflowmap 0.1.0 → 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.
@@ -2,7 +2,8 @@
2
2
  // @bun
3
3
 
4
4
  // packages/cli/src/index.ts
5
- import path8 from "path";
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 seen = new Set;
183
+ const calls = [];
183
184
  const tree = parser.parse(content);
184
- if (tree)
185
- walk(tree.rootNode, fileId, pyIds, symbols, edges, seen);
186
- return { symbols, edges };
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 walk(node, fileId, pyIds, symbols, edges, seen) {
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 = resolvePy(fileId, "", mod, pyIds);
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 } = fromModule(child);
204
- const target = resolvePy(fileId, dots, mod, pyIds);
205
- if (target)
206
- addEdge(edges, seen, fileId, target);
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
- walk(child, fileId, pyIds, symbols, edges, seen);
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.namedChildren.find((x) => x?.type === "dotted_name");
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 fromModule(node) {
241
- for (const c of node.namedChildren) {
242
- if (!c)
243
- continue;
244
- if (c.type === "dotted_name")
245
- return { dots: "", mod: c.text };
246
- if (c.type === "relative_import") {
247
- const m = /^(\.+)(.*)$/.exec(c.text);
248
- return { dots: m?.[1] ?? "", mod: m?.[2] ?? "" };
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: "", mod: "" };
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 resolvePy(fromId, dots, mod, pyIds) {
262
- let baseDir;
263
- if (dots.length > 0) {
264
- const parts = fromId.split("/");
265
- parts.pop();
266
- for (let i = 1;i < dots.length; i++)
267
- parts.pop();
268
- baseDir = parts;
269
- } else {
270
- baseDir = [];
271
- }
272
- const modParts = mod ? mod.split(".") : [];
273
- const full = [...baseDir, ...modParts].filter(Boolean);
274
- if (full.length === 0)
275
- return null;
276
- const stem = full.join("/");
277
- for (const candidate of [`${stem}.py`, `${stem}/__init__.py`]) {
278
- if (pyIds.has(candidate))
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
- return null;
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
- walk2(root, opts.outDirName, tsFiles, pyFiles);
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 walk2(dir, outDirName, tsFiles, pyFiles) {
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
- walk2(full, outDirName, tsFiles, pyFiles);
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
- import { z } from "zod";
430
- var AnnotationSchema = z.object({
431
- summary: z.string().catch(""),
432
- writes: z.array(z.string()).catch([]),
433
- reads: z.array(z.string()).catch([]),
434
- config: z.array(z.string()).catch([]),
435
- auth: z.array(z.string()).catch([]),
436
- flows: z.array(z.string()).catch([])
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 AnnotationSchema.parse(extractJson(content));
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 fs5 from "fs";
568
- import path6 from "path";
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 fs4 from "fs";
573
- import path5 from "path";
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 = path5.join(cacheDir, "annotations.json");
1050
+ this.file = path6.join(cacheDir, "annotations.json");
581
1051
  try {
582
- this.data = JSON.parse(fs4.readFileSync(this.file, "utf8"));
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
- fs4.mkdirSync(path5.dirname(this.file), { recursive: true });
598
- fs4.writeFileSync(this.file, JSON.stringify(this.data, null, 2));
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 = path6.join(outDir, "graph.json");
605
- const graph = JSON.parse(fs5.readFileSync(graphPath, "utf8"));
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(path6.join(outDir, ".cache"));
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, path6.join(graph.root, node.id));
629
- const source = fs5.readFileSync(abs, "utf8");
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
- fs5.writeFileSync(graphPath, JSON.stringify(graph, null, 2));
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 fs6 from "fs";
1153
+ import fs7 from "fs";
684
1154
  import os from "os";
685
- import path7 from "path";
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 path7.join(os.homedir(), p.slice(2));
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 ? path7.resolve(opts.webDir) : resolveWebDir();
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 = path7.resolve(vaultInput);
735
- if (fs6.existsSync(path7.join(v, "graph.json")))
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(path7.join(currentVault, "graph.json")), {
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 = path7.resolve(target);
1259
+ const dir = path8.resolve(target);
787
1260
  let stat;
788
1261
  try {
789
- stat = fs6.statSync(dir);
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 = fs6.readdirSync(dir, { withFileTypes: true }).filter((e) => {
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() && fs6.statSync(path7.join(dir, e.name)).isDirectory();
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: path7.join(dir, e.name) })).sort((a, b) => a.name.localeCompare(b.name));
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 = path7.dirname(dir);
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 = path7.resolve(expandHome(target));
825
- if (!fs6.existsSync(root)) {
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 (!fs6.statSync(root).isDirectory()) {
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() ? path7.resolve(body.out) : path7.join(root, ".codemap");
1319
+ const out = body.out?.trim() ? path8.resolve(body.out) : path8.join(root, ".codemap");
832
1320
  try {
833
- const graph = await scanRepo(root, { outDirName: path7.basename(out) });
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,48 +1380,48 @@ 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 = path7.resolve(webDir, rel);
896
- if (resolved !== webDir && !resolved.startsWith(webDir + path7.sep)) {
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 (fs6.existsSync(resolved) && fs6.statSync(resolved).isFile()) {
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(path7.join(webDir, "index.html")), {
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
- path7.resolve(import.meta.dir, "../../web/dist"),
909
- path7.resolve(import.meta.dir, "../web")
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 (fs6.existsSync(path7.join(c, "index.html")))
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 (fs6.existsSync(path7.join(webDir, "index.html")))
1406
+ if (fs7.existsSync(path8.join(webDir, "index.html")))
919
1407
  return;
920
- const webPkg = path7.resolve(webDir, "..");
921
- if (!fs6.existsSync(path7.join(webPkg, "vite.config.ts"))) {
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 || !fs6.existsSync(path7.join(webDir, "index.html"))) {
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
  }
931
1419
 
932
1420
  // packages/cli/src/index.ts
933
1421
  var program = new Command;
934
- program.name("codemap").description("Map your codebase's dependencies and data flows into an Obsidian-linkable vault").version("0.1.0");
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: path8.basename(options.out) });
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
  });