chore: add script to visualise import tree

Author: Miodec

frontend/package.json

@@ -20,7 +20,8 @@
     "dev-test": "concurrently --kill-others \"vite dev\" \"vitest\"",
     "tsc": "tsc",
     "docker": "docker compose -f docker/compose.dev.yml up",
-    "storybook": "cd storybook && pnpm run storybook"
+    "storybook": "cd storybook && pnpm run storybook",
+    "import-tree": "tsx ./scripts/import-tree.ts"
   },
   "dependencies": {
     "@date-fns/utc": "1.2.0",

frontend/scripts/import-tree.ts

@@ -0,0 +1,284 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const ROOT = path.resolve(import.meta.dirname, "..");
+
+// --- Argument handling ---
+
+const args = process.argv.slice(2);
+const maxDepthFlagIdx = args.indexOf("--depth");
+let maxDepthLimit = Infinity;
+if (maxDepthFlagIdx !== -1) {
+  maxDepthLimit = Number(args[maxDepthFlagIdx + 1]);
+  args.splice(maxDepthFlagIdx, 2);
+}
+
+const target = args[0];
+if (target === undefined || target === "") {
+  console.log("Usage: pnpm import-tree <file-or-directory> [--depth <n>]");
+  process.exit(1);
+}
+
+const resolved = path.resolve(target);
+
+function collectTsFiles(dir: string): string[] {
+  const results: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectTsFiles(full));
+    } else if (/\.tsx?$/.test(entry.name)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+let entryPoints: string[];
+if (fs.statSync(resolved).isDirectory()) {
+  entryPoints = collectTsFiles(resolved);
+} else {
+  entryPoints = [resolved];
+}
+
+if (entryPoints.length === 0) {
+  console.log("No .ts/.tsx files found.");
+  process.exit(1);
+}
+
+// --- Import extraction ---
+
+const IMPORT_RE =
+  /(?:import|export)\s+(?:type\s+)?(?:(?:\{[^}]*\}|[\w*]+(?:\s*,\s*\{[^}]*\})?)\s+from\s+)?["']([^"']+)["']/g;
+
+function extractImports(filePath: string): string[] {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const specifiers: string[] = [];
+  for (const match of content.matchAll(IMPORT_RE)) {
+    const spec = match[1];
+    if (spec !== undefined) specifiers.push(spec);
+  }
+  return specifiers;
+}
+
+// --- Resolution ---
+
+const EXTENSIONS = [".ts", ".tsx", "/index.ts", "/index.tsx"];
+
+function resolveSpecifier(
+  specifier: string,
+  importerDir: string,
+): string | null {
+  if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    const base = path.resolve(importerDir, specifier);
+    // exact match
+    if (fs.existsSync(base) && fs.statSync(base).isFile()) return base;
+    for (const ext of EXTENSIONS) {
+      const candidate = base + ext;
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    return null;
+  }
+
+  // @monkeytype packages are treated as leaf nodes (no recursion into them)
+  if (specifier.startsWith("@monkeytype/")) return specifier;
+
+  return null; // third-party / virtual
+}
+
+const printed = new Set<string>();
+
+// --- Graph traversal ---
+
+type NodeInfo = {
+  directImports: string[];
+  totalReachable: number;
+  maxDepth: number;
+};
+
+const cache = new Map<string, NodeInfo>();
+
+function walk(
+  filePath: string,
+  ancestors: Set<string>,
+): { reachable: Set<string>; maxDepth: number } {
+  const cached = cache.get(filePath);
+  if (cached !== undefined) {
+    return {
+      reachable: new Set(getAllReachable(filePath, new Set())),
+      maxDepth: cached.maxDepth,
+    };
+  }
+
+  const importerDir = path.dirname(filePath);
+  const specifiers = extractImports(filePath);
+  const directImports: string[] = [];
+
+  const reachable = new Set<string>();
+  let maxDepth = 0;
+
+  for (const spec of specifiers) {
+    const resolved = resolveSpecifier(spec, importerDir);
+    if (resolved === null) continue;
+    if (directImports.includes(resolved)) continue;
+    directImports.push(resolved);
+
+    if (ancestors.has(resolved)) continue; // circular
+
+    reachable.add(resolved);
+
+    // @monkeytype packages are leaf nodes — don't recurse
+    if (resolved.startsWith("@monkeytype/")) {
+      maxDepth = Math.max(maxDepth, 1);
+      continue;
+    }
+
+    ancestors.add(resolved);
+    const sub = walk(resolved, ancestors);
+    ancestors.delete(resolved);
+
+    for (const r of sub.reachable) reachable.add(r);
+    maxDepth = Math.max(maxDepth, 1 + sub.maxDepth);
+  }
+
+  if (directImports.length > 0 && maxDepth === 0) {
+    maxDepth = 1;
+  }
+
+  cache.set(filePath, {
+    directImports,
+    totalReachable: reachable.size,
+    maxDepth,
+  });
+
+  return { reachable, maxDepth };
+}
+
+function getAllReachable(filePath: string, visited: Set<string>): string[] {
+  const info = cache.get(filePath);
+  if (!info) return [];
+  const result: string[] = [];
+  for (const dep of info.directImports) {
+    if (visited.has(dep)) continue;
+    visited.add(dep);
+    result.push(dep);
+    result.push(...getAllReachable(dep, visited));
+  }
+  return result;
+}
+
+// --- Colors ---
+
+const c = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  magenta: "\x1b[35m",
+  red: "\x1b[31m",
+  blue: "\x1b[34m",
+  white: "\x1b[37m",
+};
+
+const DEPTH_COLORS = [c.cyan, c.green, c.yellow, c.blue, c.magenta, c.white];
+
+function depthColor(depth: number): string {
+  return DEPTH_COLORS[depth % DEPTH_COLORS.length] ?? c.cyan;
+}
+
+// --- Display ---
+
+function displayPath(filePath: string): string {
+  if (filePath.startsWith(ROOT + "/")) {
+    return path.relative(ROOT, filePath);
+  }
+  return filePath;
+}
+
+function printTree(
+  filePath: string,
+  ancestors: Set<string>,
+  prefix: string,
+  isLast: boolean,
+  isRoot: boolean,
+  depth: number = 0,
+): void {
+  const info = cache.get(filePath);
+  const dp = displayPath(filePath);
+  const connector = isRoot ? "" : isLast ? "└── " : "├── ";
+  const dc = depthColor(depth);
+
+  if (!info) {
+    // leaf node (e.g. @monkeytype package)
+    console.log(`${c.dim}${prefix}${connector}${dp}${c.reset}`);
+    return;
+  }
+
+  const stats =
+    info.directImports.length > 0
+      ? ` ${c.dim}(direct: ${info.directImports.length}, total: ${info.totalReachable}, depth: ${info.maxDepth})${c.reset}`
+      : "";
+
+  const nameStyle = isRoot ? c.bold + dc : dc;
+  const seen = !isRoot && printed.has(filePath);
+  const seenTag = seen ? ` ${c.dim}[seen above]${c.reset}` : "";
+  console.log(
+    `${c.dim}${prefix}${connector}${c.reset}${nameStyle}${dp}${c.reset}${stats}${seenTag}`,
+  );
+
+  if (seen || depth >= maxDepthLimit) return;
+  printed.add(filePath);
+
+  const childPrefix = isRoot ? "" : prefix + (isLast ? "    " : "│   ");
+
+  const deps = [...info.directImports];
+  if (depth === 0) {
+    deps.sort((a, b) => {
+      const ta = cache.get(a)?.totalReachable ?? 0;
+      const tb = cache.get(b)?.totalReachable ?? 0;
+      return tb - ta;
+    });
+  }
+
+  for (let i = 0; i < deps.length; i++) {
+    const dep = deps[i];
+    if (dep === undefined) continue;
+    const last = i === deps.length - 1;
+
+    if (ancestors.has(dep)) {
+      const cc = last ? "└── " : "├── ";
+      console.log(
+        `${c.dim}${childPrefix}${cc}${c.reset}${c.red}[circular] ${displayPath(dep)}${c.reset}`,
+      );
+      continue;
+    }
+
+    ancestors.add(dep);
+    printTree(dep, ancestors, childPrefix, last, false, depth + 1);
+    ancestors.delete(dep);
+  }
+}
+
+// --- Main ---
+
+for (const entry of entryPoints) {
+  if (!fs.existsSync(entry)) {
+    console.log(`File not found: ${entry}`);
+    continue;
+  }
+  walk(entry, new Set([entry]));
+}
+
+entryPoints.sort((a, b) => {
+  const ta = cache.get(a)?.totalReachable ?? 0;
+  const tb = cache.get(b)?.totalReachable ?? 0;
+  return tb - ta;
+});
+
+for (const entry of entryPoints) {
+  if (!cache.has(entry)) continue;
+  printTree(entry, new Set([entry]), "", true, true);
+  if (entryPoints.length > 1) console.log();
+}