@blkc-code/mapgen 0.3.0 → 0.6.0

package/src/project-files.ts

@@ -0,0 +1,39 @@
+/** Reading what's in a project: names and counts, and package manifests. Never source code. */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+type Json = Record<string, unknown>;
+
+/** What marks a folder as an application, out of the box. */
+export const DEFAULT_APP_MARKERS = ["block.json", "kit.json", "circuit.json", "package.json", "pyproject.toml", "setup.py", "requirements.txt", "go.mod", "Cargo.toml", "pom.xml", "build.gradle", "build.gradle.kts", "Gemfile", "composer.json", "mix.exs", "deno.json", "pubspec.yaml", "Package.swift", "CMakeLists.txt", "*.csproj", "*.sln"];
+
+export const markerMatcher = (marker: string): RegExp =>
+  new RegExp(`^${marker.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`);
+
+export const IGNORE = new Set(["node_modules", ".git", "dist", "build", "out", "target", "coverage", ".next", ".turbo", ".cache", "vendor", "venv", "__pycache__", ".venv", ".idea", ".vscode", ".claude", ".blkc", ".gemini", ".cursor"]);
+
+/** The plain folder names in a .gitignore. Patterns with wildcards aren't followed. */
+export function gitignoredNames(root: string): Set<string> {
+  const names = new Set<string>();
+  try {
+    for (const line of readFileSync(path.join(root, ".gitignore"), "utf8").split("\n")) {
+      const name = line.trim().replace(/^\//, "").replace(/\/$/, "");
+      if (name && !/[*!#/\s]/.test(name)) names.add(name);
+    }
+  } catch {
+    // no .gitignore
+  }
+  return names;
+}
+
+/** A folder with its own .git is another project, even if it sits inside this one. */
+export const isOwnRepo = (dir: string): boolean => existsSync(path.join(dir, ".git"));
+
+export const readPackage = (dir: string): Json | undefined => {
+  try {
+    return JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8")) as Json;
+  } catch {
+    return undefined;
+  }
+};

package/src/roads.ts

@@ -0,0 +1,326 @@
+/**
+ * A map that grows from the project tree, with no size limit. Each road is sized from what's
+ * on it, and its parent road makes room. Buildings are as big as their contents need and
+ * never shrink. Once placed, nothing moves: a new folder takes a spare lot on its road, or
+ * a new stretch of road at the edge of the map.
+ */
+
+import { deskCount, furnish, rng, slug, themeFor, titled, type MapDoor, type MapItem, type MapRoom, type OfficeMap } from "./index.js";
+import { OFFICE_PLAN, worldPlan, type WorldPlan } from "./plan.js";
+import type { ProjectTree, TreeNode } from "./tree.js";
+
+const ROAD_H = 2;
+const CELL = 4;
+const SPARE = { w: 9, h: 6 };
+const PILE_STEP = 8;
+const MARGIN = 2;
+const MARGIN_TOP = 3;
+
+interface Placed { room: MapRoom; node?: TreeNode; side?: "n" | "s" }
+interface Block { w: number; h: number; rooms: Placed[]; doors: MapDoor[] }
+interface Lot { w: number; h: number; key: string; room?: () => MapRoom; node?: TreeNode; block?: Block }
+
+const road = (id: string, name: string, x: number, y: number, w: number, h: number, paths: string[]): MapRoom =>
+  ({ id, name, x, y, w, h, floor: "hall", paths, role: "hall" });
+
+const leadsToBuilding = (node: TreeNode): boolean =>
+  node.children.some((child) => child.kind === "building" || (child.kind === "road" && leadsToBuilding(child)));
+
+/**
+ * Only a road that leads to an application is drawn. Other folders fold into a Folders group
+ * on their parent's road, so tooling and notes can't crowd out the project.
+ */
+function foldFolders(node: TreeNode): TreeNode {
+  const folded = node.children.filter((child) => child.kind === "road" && !leadsToBuilding(child));
+  const kept = node.children.filter((child) => !folded.includes(child)).map((child) => (child.kind === "road" ? foldFolders(child) : child));
+  return {
+    ...node,
+    children: folded.length > 0 ? [...kept, { id: `group:${node.path}:Folders`, kind: "group", name: "Folders", path: node.path, children: folded }] : kept,
+  };
+}
+
+/** A project that is one application has its own folders as buildings. */
+function asRoads(tree: ProjectTree): TreeNode {
+  if (tree.root.kind === "road") return foldFolders(tree.root);
+  return {
+    ...tree.root,
+    id: "road:",
+    kind: "road",
+    name: "/",
+    children: tree.root.children.map((child) => (child.kind === "part" ? { ...child, id: `building:${child.path}`, kind: "building" as const, children: [] } : child)),
+  };
+}
+
+const partsIn = (node: TreeNode): TreeNode[] => node.children.filter((child) => child.kind === "part");
+
+/** Big enough for every part, in cells an agent can walk between. */
+function buildingSize(node: TreeNode): { w: number; h: number } {
+  const parts = partsIn(node).length || deskCount(node.files ?? 1);
+  const across = Math.ceil(Math.sqrt(parts * 1.4));
+  const down = Math.ceil(parts / across);
+  return { w: Math.max(9, across * CELL + 1), h: Math.max(6, down * CELL + 1) };
+}
+
+/** One item for each real part, all reachable: every cell has a free row and column around it. */
+function fillBuilding(room: MapRoom, node: TreeNode, plan: WorldPlan): MapItem[] {
+  const across = Math.max(1, Math.floor((room.w - 1) / CELL));
+  const down = Math.max(1, Math.floor((room.h - 1) / CELL));
+  const parts = partsIn(node);
+  const entries = parts.length > 0
+    ? parts.map((part) => ({ type: plan.partItems?.[part.item ?? ""] ?? plan.workstation, part: part.path }))
+    : Array.from({ length: deskCount(node.files ?? 1) }, () => ({ type: plan.workstation, part: node.path }));
+  return entries.slice(0, across * down).map((entry, index) => ({
+    type: entry.type,
+    x: room.x + 1 + (index % across) * CELL,
+    y: room.y + 1 + Math.floor(index / across) * CELL,
+    room: room.id,
+    part: entry.part,
+  }));
+}
+
+function buildBlock(node: TreeNode, seed: string, plan: WorldPlan, suffix: string, top: boolean, spares: boolean): Block {
+  const id = slug(node.path) || "root";
+  const lots: Lot[] = [];
+  if (top) {
+    plan.specials.forEach((special, index) => {
+      lots.push({ w: special.w, h: special.h, key: special.id, room: () => ({ id: special.id, name: special.name, role: special.role, floor: special.floor, paths: index === 0 ? [""] : [], road: "", x: 0, y: 0, w: special.w, h: special.h }) });
+    });
+  }
+  let buildings = 0;
+  for (const child of node.children) {
+    if (child.kind === "building") {
+      buildings += 1;
+      const size = buildingSize(child);
+      lots.push({
+        ...size,
+        key: child.id,
+        node: child,
+        room: () => ({ id: slug(child.path), name: titled(child.name), floor: themeFor(child.path, plan, rng(`${seed}:theme:${child.path}`)).floor, paths: [`${child.path}/`], files: child.files ?? 0, road: node.path, x: 0, y: 0, ...size }),
+      });
+    } else if (child.kind === "road") {
+      const block = buildBlock(child, seed, plan, suffix, false, spares);
+      lots.push({ w: block.w, h: block.h, key: child.id, block });
+    }
+  }
+  if (spares && buildings > 0) {
+    const count = Math.ceil(buildings / 4);
+    for (let n = 1; n <= count; n++) {
+      lots.push({ ...SPARE, key: `spare:${node.path}:${n}`, room: () => ({ id: `spare-${id}-${n}${suffix}`, name: "Empty", floor: "concrete", paths: [], role: "vacant", road: node.path, x: 0, y: 0, ...SPARE }) });
+    }
+  }
+
+  // Roads wrap into bands, so a long one stays roughly square rather than running forever.
+  const area = lots.reduce((sum, lot) => sum + (lot.w + 1) * (lot.h + 1), 0);
+  const limit = Math.max(44, Math.ceil(Math.sqrt(area) * 1.5), ...lots.map((lot) => lot.w + 4));
+  interface Band { north: Lot[]; south: Lot[]; n: number; s: number }
+  const bands: Band[] = [{ north: [], south: [], n: 3, s: 3 }];
+  for (const lot of lots) {
+    let band = bands[bands.length - 1] as Band;
+    if (Math.min(band.n, band.s) + lot.w > limit) {
+      band = { north: [], south: [], n: 3, s: 3 };
+      bands.push(band);
+    }
+    if (band.n <= band.s) { band.north.push(lot); band.n += lot.w + 1; }
+    else { band.south.push(lot); band.s += lot.w + 1; }
+  }
+
+  const piles = node.children.filter((child) => child.kind === "group");
+  const label = node.path ? `${node.path}/` : "";
+  const wanted = 4 + Math.ceil(label.length * 0.4) + piles.length * PILE_STEP;
+  const width = Math.max(wanted, ...bands.map((band) => Math.max(band.n, band.s) - 1));
+
+  const out: Block = { w: width, h: 0, rooms: [], doors: [] };
+  const place = (lot: Lot, x: number, y: number, side: "n" | "s", wall: number): void => {
+    const random = rng(`${seed}:door:${lot.key}`);
+    if (lot.block) {
+      for (const placed of lot.block.rooms) out.rooms.push({ ...placed, room: { ...placed.room, x: placed.room.x + x, y: placed.room.y + y } });
+      for (const door of lot.block.doors) out.doors.push({ x: door.x + x, y: door.y + y });
+      // The side road's spine runs through the wall to meet this road.
+      out.rooms.push({ room: road(`link-${slug(lot.key)}${suffix}`, "", x, wall, ROAD_H, 1, []) });
+      return;
+    }
+    const room = (lot.room as () => MapRoom)();
+    room.x = x;
+    room.y = y;
+    out.rooms.push({ room, ...(lot.node ? { node: lot.node } : {}), side });
+    out.doors.push({ x: x + 1 + Math.floor(random() * Math.max(1, lot.w - 2)), y: wall });
+  };
+
+  let y = 0;
+  bands.forEach((band, index) => {
+    const north = Math.max(0, ...band.north.map((lot) => lot.h));
+    const south = Math.max(0, ...band.south.map((lot) => lot.h));
+    const street = y + north + (north > 0 ? 1 : 0);
+    let x = 3;
+    for (const lot of band.north) {
+      place(lot, x, street - 1 - lot.h, "n", street - 1);
+      x += lot.w + 1;
+    }
+    x = 3;
+    for (const lot of band.south) {
+      place(lot, x, street + ROAD_H + 1, "s", street + ROAD_H);
+      x += lot.w + 1;
+    }
+    out.rooms.push({ room: road(`road-${id}-${index}${suffix}`, index === 0 ? label : "", 2, street, width - 2, ROAD_H, node.path ? [`${node.path}/`] : []) });
+    y = street + ROAD_H + 1 + (south > 0 ? south + 1 : 0);
+  });
+  out.h = Math.max(1, y - 1);
+  out.rooms.push({ room: road(`road-${id}-spine${suffix}`, "", 0, 0, ROAD_H, out.h, node.path ? [`${node.path}/`] : []) });
+  return out;
+}
+
+/** Loose files, in groups, on the first stretch of their own road. Redrawn whenever they change. */
+function placePiles(map: OfficeMap, top: TreeNode): void {
+  map.furniture = map.furniture.filter((item) => item.type !== "pile");
+  const visit = (node: TreeNode): void => {
+    const street = map.rooms.find((room) => room.role === "hall" && room.id === `road-${slug(node.path) || "root"}-0`);
+    if (street) {
+      const start = street.x + 2 + Math.ceil((node.path ? node.path.length + 1 : 0) * 0.4);
+      const fits = Math.max(1, Math.floor((street.x + street.w - start) / PILE_STEP));
+      node.children.filter((child) => child.kind === "group").slice(0, fits).forEach((group, index) => {
+        map.furniture.push({ type: "pile", x: start + index * PILE_STEP, y: street.y, room: street.id, part: group.id, label: `${group.name} ${group.children.length}` });
+      });
+    }
+    for (const child of node.children) if (child.kind === "road") visit(child);
+  };
+  visit(top);
+}
+
+function shift(map: OfficeMap): void {
+  if (map.rooms.length === 0) return;
+  const minX = Math.min(...map.rooms.map((room) => room.x));
+  const minY = Math.min(...map.rooms.map((room) => room.y));
+  const dx = MARGIN - minX;
+  const dy = MARGIN_TOP - minY;
+  for (const room of map.rooms) { room.x += dx; room.y += dy; }
+  for (const door of map.doors) { door.x += dx; door.y += dy; }
+  for (const item of map.furniture) { item.x += dx; item.y += dy; }
+  map.cols = Math.max(...map.rooms.map((room) => room.x + room.w)) + MARGIN;
+  map.rows = Math.max(...map.rooms.map((room) => room.y + room.h)) + MARGIN;
+}
+
+function collectBuildings(node: TreeNode, into: Map<string, { node: TreeNode; road: TreeNode }> = new Map()): Map<string, { node: TreeNode; road: TreeNode }> {
+  for (const child of node.children) {
+    if (child.kind === "building") into.set(slug(child.path), { node: child, road: node });
+    else if (child.kind === "road") collectBuildings(child, into);
+  }
+  return into;
+}
+
+const setLinks = (map: OfficeMap, tree: ProjectTree): void => {
+  const on = new Set(map.rooms.map((room) => room.id));
+  const links = tree.links
+    .map((link) => ({ from: slug(link.from.replace(/^building:/, "")), to: slug(link.to.replace(/^building:/, "")), door: false }))
+    .filter((link) => on.has(link.from) && on.has(link.to));
+  if (links.length > 0) map.links = links;
+  else delete map.links;
+};
+
+/** Absorb a block into the map, furnishing what it holds. */
+function addBlock(map: OfficeMap, block: Block, x: number, y: number, seed: string, plan: WorldPlan): void {
+  for (const placed of block.rooms) {
+    const room = { ...placed.room, x: placed.room.x + x, y: placed.room.y + y };
+    map.rooms.push(room);
+    if (placed.node) map.furniture.push(...fillBuilding(room, placed.node, plan));
+  }
+  for (const door of block.doors) map.doors.push({ x: door.x + x, y: door.y + y });
+  for (const placed of block.rooms) {
+    const { role, id } = placed.room;
+    if (!role || role === "hall") continue;
+    const room = map.rooms.find((candidate) => candidate.id === id) as MapRoom;
+    map.furniture.push(...furnish(room, map.doors, seed, plan));
+  }
+}
+
+export function layoutRoads(tree: ProjectTree, seed: string, plan: WorldPlan = OFFICE_PLAN): OfficeMap {
+  const top = asRoads(tree);
+  const map: OfficeMap = { version: 1, ...(plan === OFFICE_PLAN ? {} : { world: plan.id }), layout: "roads", seed, evolve: true, cols: 0, rows: 0, rooms: [], doors: [], furniture: [], log: [] };
+  addBlock(map, buildBlock(top, seed, plan, "", true, true), 0, 0, seed, plan);
+  // The first room stays first in the file.
+  map.rooms.sort((a, b) => Number(b.role === "lobby") - Number(a.role === "lobby"));
+  placePiles(map, top);
+  setLinks(map, tree);
+  shift(map);
+  return map;
+}
+
+export function evolveRoads(previous: OfficeMap | undefined, tree: ProjectTree, seed: string, now = new Date().toISOString()): { map: OfficeMap; changes: string[] } {
+  if (!previous) return { map: layoutRoads(tree, seed), changes: [] };
+  const plan = worldPlan(previous.world);
+  const map = JSON.parse(JSON.stringify(previous)) as OfficeMap;
+  const changes: string[] = [];
+  const top = asRoads(tree);
+  const wanted = collectBuildings(top);
+
+  const clearItems = (id: string): void => { map.furniture = map.furniture.filter((item) => item.room !== id); };
+  for (const room of map.rooms) {
+    if (room.role || room.locked || wanted.has(room.id)) continue;
+    changes.push(`${room.name} is now empty: its folder has gone`);
+    clearItems(room.id);
+    room.role = "vacant";
+    room.name = "Empty";
+    room.paths = [];
+    delete room.files;
+    map.furniture.push(...furnish(room, map.doors, map.seed, plan));
+  }
+
+  const newOnRoad = new Map<string, TreeNode[]>();
+  const signature = (items: MapItem[]): string => items.map((item) => `${item.type}:${item.part}`).sort().join("|");
+  for (const [id, { node, road: parent }] of wanted) {
+    const room = map.rooms.find((candidate) => candidate.id === id);
+    if (room?.locked) continue;
+    if (room) {
+      const back = room.role === "vacant";
+      if (back) {
+        delete room.role;
+        room.name = titled(node.name);
+        room.paths = [`${node.path}/`];
+        room.floor = themeFor(node.path, plan, rng(`${map.seed}:theme:${node.path}`)).floor;
+        changes.push(`${room.name} is back`);
+      }
+      room.files = node.files ?? 0;
+      const items = fillBuilding(room, node, plan);
+      if (back || signature(items) !== signature(map.furniture.filter((item) => item.room === id))) {
+        clearItems(id);
+        map.furniture.push(...items);
+      }
+      continue;
+    }
+    // A spare lot on its own road, if there's one big enough.
+    const size = buildingSize(node);
+    const lot = map.rooms.find((candidate) => candidate.role === "vacant" && !candidate.locked && candidate.road === parent.path && candidate.w >= size.w && candidate.h >= size.h);
+    if (lot) {
+      clearItems(lot.id);
+      lot.id = id;
+      delete lot.role;
+      lot.name = titled(node.name);
+      lot.floor = themeFor(node.path, plan, rng(`${map.seed}:theme:${node.path}`)).floor;
+      lot.paths = [`${node.path}/`];
+      lot.files = node.files ?? 0;
+      map.furniture.push(...fillBuilding(lot, node, plan));
+      changes.push(`New room: ${lot.name}`);
+      continue;
+    }
+    newOnRoad.set(parent.path, [...(newOnRoad.get(parent.path) ?? []), node]);
+  }
+
+  // No lot left: a new stretch of road, below everything, so nothing else has to move.
+  const spine = map.rooms.find((room) => room.id === "road-root-spine");
+  for (const [path, nodes] of newOnRoad) {
+    const bottom = Math.max(...map.rooms.map((room) => room.y + room.h));
+    const startX = spine?.x ?? Math.min(...map.rooms.map((room) => room.x));
+    const stretch = map.rooms.filter((room) => room.id.startsWith("road-") && room.id.endsWith("spine")).length;
+    const node: TreeNode = { id: `road:${path}`, kind: "road", name: `${path}/`, path, children: nodes };
+    const y = bottom + 1;
+    addBlock(map, buildBlock(node, map.seed, plan, `-more${stretch}`, false, false), startX, y, map.seed, plan);
+    if (spine) spine.h = y - spine.y;
+    for (const added of nodes) changes.push(`New room: ${titled(added.name)}`);
+  }
+
+  placePiles(map, top);
+
+  setLinks(map, tree);
+  shift(map);
+  if (changes.length > 0) map.log = [...map.log, ...changes.map((text) => ({ at: now, text }))].slice(-30);
+  return { map, changes };
+}

package/src/tree.ts

@@ -0,0 +1,285 @@
+/**
+ * A project as a world, before anything is placed. A folder holding an application is a
+ * building. A folder holding none is a road, at any depth, named by its literal path. Loose
+ * files sit on the road of their own folder, grouped by type. Files that look like secrets
+ * are kept apart, for the vault.
+ *
+ * Only names and counts are read here, and package manifests for links. Never source code.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_APP_MARKERS, IGNORE, gitignoredNames, isOwnRepo, markerMatcher, readPackage } from "./project-files.js";
+
+export type TreeKind = "road" | "building" | "part" | "group" | "file";
+
+export interface TreeNode {
+  /** Stable, from the path: "road:apps", "building:apps/web", "part:apps/web/src/api", "group:apps:Docs", "file:apps/x.md". */
+  id: string;
+  kind: TreeKind;
+  name: string;
+  /** From the top of the project. The root road's is "". */
+  path: string;
+  /** Files git tracks here, or on disk if it isn't tracked yet. */
+  files?: number;
+  /** Which item a part is, such as "Desk". */
+  item?: string;
+  children: TreeNode[];
+}
+
+export interface ProjectTree {
+  root: TreeNode;
+  /** Files that matched the Secrets group: their paths only. */
+  secrets: TreeNode[];
+  /** `from` depends on `to`, by building id. */
+  links: { from: string; to: string }[];
+  /** The scan hit its limit, so this isn't all of the project. */
+  truncated: boolean;
+}
+
+export interface TreeOptions {
+  markers?: string[];
+  replaceDefaults?: boolean;
+  /** Folders that are buildings even with no marker. */
+  include?: string[];
+  /** Never shown: a folder name, or a path from the top. */
+  ignore?: string[];
+  /** Walk these even if gitignored or separate repos. */
+  roads?: string[];
+  /** Added to the built-in groups. Giving a built-in group's name replaces its patterns. */
+  fileGroups?: Record<string, string[]>;
+  /** Added to the built-in items. Each entry is a folder name, or a path ending that folder's path. */
+  partTypes?: Record<string, string[]>;
+}
+
+export const SECRETS_GROUP = "Secrets";
+
+/** Secrets comes first, so a file like .env.json is never left in Config. */
+export const DEFAULT_FILE_GROUPS: Record<string, string[]> = {
+  [SECRETS_GROUP]: [".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa", "id_ed25519", ".npmrc", ".netrc"],
+  Docs: ["*.md", "*.mdx", "*.rst", "LICENSE*", "NOTICE*"],
+  Config: [".env.*", "*.json", "*.jsonc", "*.yaml", "*.yml", "*.toml", "*.config.*", ".*ignore", ".*rc", ".*rc.*", ".editorconfig", "Dockerfile*", "Makefile"],
+  Pages: ["*.html", "*.htm"],
+  Images: ["*.png", "*.jpg", "*.jpeg", "*.gif", "*.svg", "*.webp", "*.ico"],
+  Logs: ["*.log", "*.txt", "*history*"],
+  Code: ["*.ts", "*.tsx", "*.js", "*.mjs", "*.cjs", "*.py", "*.go", "*.rs", "*.java", "*.rb", "*.php", "*.sh", "*.css", "*.sql"],
+};
+const OTHER_GROUP = "Other";
+/** Templates are meant to be committed, and hold no real values. */
+const SECRET_TEMPLATE = /\.(example|sample|template|dist)$/i;
+
+/** What a folder inside an application is, by its name. Anything else under src/ is a Desk. */
+export const DEFAULT_PART_TYPES: Record<string, string[]> = {
+  "Server rack": ["api", "server", "servers", "backend", "supabase", "migrations", "db", "database", "prisma"],
+  Workbench: ["lib", "libs", "shared", "utils", "core", "common", "kernel"],
+  Whiteboard: ["test", "tests", "__tests__", "e2e", "spec", "specs"],
+  Bookshelf: ["docs", "doc", "documentation"],
+  Toolbox: ["scripts", "tools", "bin", "skills"],
+  Plants: ["public", "assets", "static", "images"],
+};
+const FEATURE_ITEM = "Desk";
+const OTHER_ITEM = "Filing cabinet";
+/** Folders inside an application that hold its parts, rather than being one. */
+const PART_CONTAINERS = new Set(["src", "app", "pages", "features", "modules"]);
+
+const MAX_ENTRIES = 400000;
+const MAX_DEPTH = 12;
+
+const clean = (value: string): string => value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+const join = (base: string, name: string): string => (base ? `${base}/${name}` : name);
+const within = (rel: string, parent: string): boolean => rel === parent || rel.startsWith(`${parent}/`);
+
+export function scanTree(root: string, options: TreeOptions = {}): ProjectTree {
+  const gitignored = gitignoredNames(root);
+  const skipped = new Set((options.ignore ?? []).map(clean));
+  const isSkipped = (rel: string): boolean => skipped.has(rel) || skipped.has(path.posix.basename(rel));
+  const roads = (options.roads ?? []).map(clean);
+  /** An added road, somewhere above or below this folder, opens the way through. */
+  const onAddedRoad = (rel: string): boolean => roads.some((road) => within(rel, road) || within(road, rel));
+
+  const markers = [...(options.replaceDefaults ? [] : DEFAULT_APP_MARKERS), ...(options.markers ?? [])].map(markerMatcher);
+  const includes = new Set((options.include ?? []).map(clean));
+
+  const groupMatchers = Object.entries({ ...DEFAULT_FILE_GROUPS, ...options.fileGroups })
+    .sort(([a], [b]) => Number(b === SECRETS_GROUP) - Number(a === SECRETS_GROUP))
+    .map(([name, patterns]) => ({ name, patterns: patterns.map(markerMatcher) }));
+  const groupOf = (file: string): string =>
+    groupMatchers.find((group) => !(group.name === SECRETS_GROUP && SECRET_TEMPLATE.test(file)) && group.patterns.some((pattern) => pattern.test(file)))?.name ?? OTHER_GROUP;
+
+  const customParts = Object.entries(options.partTypes ?? {}).map(([item, folders]) => ({ item, folders: folders.map(clean) }));
+  const itemFor = (rel: string, nested: boolean): string => {
+    const name = path.posix.basename(rel);
+    const custom = customParts.find(({ folders }) => folders.some((folder) => folder === name || rel === folder || rel.endsWith(`/${folder}`)));
+    if (custom) return custom.item;
+    const known = Object.entries(DEFAULT_PART_TYPES).find(([, folders]) => folders.includes(name));
+    if (known) return known[0];
+    return nested ? FEATURE_ITEM : OTHER_ITEM;
+  };
+
+  // What git tracks is the truth, repo by repo, since an added road can hold separate repos.
+  const trackedIn = new Map<string, string[]>();
+  const tracked = (repo: string): string[] => {
+    let files = trackedIn.get(repo);
+    if (!files) {
+      try {
+        files = execFileSync("git", ["ls-files", "-z"], { cwd: path.join(root, repo), encoding: "utf8", maxBuffer: 512 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }).split("\0").filter(Boolean);
+      } catch {
+        files = [];
+      }
+      trackedIn.set(repo, files);
+    }
+    return files;
+  };
+
+  let budget = MAX_ENTRIES;
+  let truncated = false;
+  const list = (rel: string) => {
+    try {
+      const entries = readdirSync(path.join(root, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+      budget -= entries.length;
+      if (budget <= 0) truncated = true;
+      return entries;
+    } catch {
+      return [];
+    }
+  };
+  const countOnDisk = (rel: string, depth = 0): number => {
+    if (budget <= 0 || depth > MAX_DEPTH) return 0;
+    let total = 0;
+    for (const entry of list(rel)) {
+      if (entry.isFile()) total += 1;
+      else if (entry.isDirectory() && !entry.name.startsWith(".") && !IGNORE.has(entry.name) && !gitignored.has(entry.name)) total += countOnDisk(join(rel, entry.name), depth + 1);
+    }
+    return total;
+  };
+  const countFiles = (rel: string, repo: string): number => {
+    const inside = repo ? rel.slice(repo.length + 1) : rel;
+    const prefix = inside ? `${inside}/` : "";
+    const count = tracked(repo).filter((file) => file.startsWith(prefix)).length;
+    return count > 0 ? count : countOnDisk(rel);
+  };
+
+  const secrets: TreeNode[] = [];
+  const looseFiles = (owner: string, files: string[]): TreeNode[] => {
+    const groups = new Map<string, TreeNode[]>();
+    for (const file of files) {
+      const rel = join(owner, file);
+      const node: TreeNode = { id: `file:${rel}`, kind: "file", name: file, path: rel, children: [] };
+      const group = groupOf(file);
+      if (group === SECRETS_GROUP) {
+        secrets.push(node);
+        continue;
+      }
+      groups.set(group, [...(groups.get(group) ?? []), node]);
+    }
+    return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, children]) => ({ id: `group:${owner}:${name}`, kind: "group" as const, name, path: owner, children }));
+  };
+
+  /** A folder is shown unless it's hidden, junk, ignored, or another repo no road opened. */
+  const showFolder = (rel: string, name: string): boolean => {
+    if (IGNORE.has(name) || isSkipped(rel)) return false;
+    const opened = onAddedRoad(rel);
+    if (name.startsWith(".") && name !== ".github" && !opened) return false;
+    if (gitignored.has(name) && !opened) return false;
+    return opened || !isOwnRepo(path.join(root, rel));
+  };
+  const isApp = (rel: string, files: string[]): boolean =>
+    includes.has(rel) || files.some((file) => markers.some((marker) => marker.test(file)));
+
+  const partsOf = (rel: string, repo: string, nested: boolean, depth: number): TreeNode[] => {
+    const parts: TreeNode[] = [];
+    for (const entry of list(rel)) {
+      if (!entry.isDirectory()) continue;
+      const child = join(rel, entry.name);
+      if (entry.name.startsWith(".") || !showFolder(child, entry.name)) continue;
+      if (PART_CONTAINERS.has(entry.name) && depth < 3) {
+        const inner = partsOf(child, repo, true, depth + 1);
+        if (inner.length > 0) {
+          parts.push(...inner);
+          continue;
+        }
+      }
+      const files = countFiles(child, repo);
+      if (files > 0) parts.push({ id: `part:${child}`, kind: "part", name: path.posix.basename(child), path: child, files, item: itemFor(child, nested), children: [] });
+    }
+    return parts;
+  };
+  const building = (rel: string, repo: string, files: string[]): TreeNode => ({
+    id: `building:${rel}`,
+    kind: "building",
+    name: path.posix.basename(rel) || path.basename(path.resolve(root)),
+    path: rel,
+    files: countFiles(rel, repo),
+    children: [...partsOf(rel, repo, false, 0), ...looseFiles(rel, files)],
+  });
+
+  const walk = (rel: string, repo: string, depth: number): TreeNode => {
+    const entries = list(rel);
+    const files = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+    const children: TreeNode[] = [];
+    if (depth < MAX_DEPTH && budget > 0) {
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const child = join(rel, entry.name);
+        if (!showFolder(child, entry.name)) continue;
+        const childRepo = isOwnRepo(path.join(root, child)) ? child : repo;
+        const childFiles = list(child).filter((item) => item.isFile()).map((item) => item.name);
+        if (isApp(child, childFiles)) {
+          children.push(building(child, childRepo, childFiles));
+        } else {
+          const road = walk(child, childRepo, depth + 1);
+          if (road.children.length > 0) children.push(road);
+        }
+      }
+    } else if (depth >= MAX_DEPTH) {
+      truncated = true;
+    }
+    return {
+      id: `road:${rel}`,
+      kind: "road",
+      name: rel ? `${path.posix.basename(rel)}/` : "/",
+      path: rel,
+      children: [...children, ...looseFiles(rel, files)],
+    };
+  };
+
+  const hasBuildings = (node: TreeNode): boolean => node.children.some((child) => child.kind === "building" || (child.kind === "road" && hasBuildings(child)));
+  const topFiles = list("").filter((entry) => entry.isFile()).map((entry) => entry.name);
+  let top = walk("", "", 0);
+  // With no application inside it, the whole project is one, marked or not.
+  if (!hasBuildings(top)) {
+    secrets.length = 0;
+    top = building("", "", topFiles);
+  }
+
+  const buildings: TreeNode[] = [];
+  const collect = (node: TreeNode): void => {
+    if (node.kind === "building") buildings.push(node);
+    for (const child of node.children) if (child.kind === "road") collect(child);
+    if (node.kind === "road") for (const child of node.children) if (child.kind === "building") buildings.push(child);
+  };
+  collect(top);
+  const owners = new Map<string, string>();
+  const manifests = new Map<string, Record<string, unknown>>();
+  for (const node of buildings) {
+    const manifest = readPackage(path.join(root, node.path));
+    if (!manifest) continue;
+    manifests.set(node.id, manifest);
+    if (typeof manifest["name"] === "string") owners.set(manifest["name"], node.id);
+  }
+  const links: { from: string; to: string }[] = [];
+  for (const [from, manifest] of manifests) {
+    const seen = new Set<string>();
+    for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+      for (const name of Object.keys((manifest[field] ?? {}) as Record<string, unknown>)) {
+        const to = owners.get(name);
+        if (to && to !== from && !seen.has(to)) {
+          seen.add(to);
+          links.push({ from, to });
+        }
+      }
+    }
+  }
+  return { root: top, secrets, links, truncated };
+}