refactor: dedupe tooling helpers

scripts/lib/arg-utils.mjs

@@ -7,6 +7,19 @@ export function readEnvNumber(name, env = process.env) {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+export function readFlagValue(args, name) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === name) {
+      return args[index + 1];
+    }
+    if (arg.startsWith(`${name}=`)) {
+      return arg.slice(name.length + 1);
+    }
+  }
+  return undefined;
+}
+
 export function consumeStringFlag(argv, index, flag, currentValue) {
   if (argv[index] !== flag) {
     return null;

scripts/lib/import-cycle-graph.ts

@@ -0,0 +1,134 @@
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+type SourceFileCollectionOptions = {
+  repoRoot: string;
+  sourceExtensions: readonly string[];
+  shouldSkipRepoPath?: (repoPath: string) => boolean;
+};
+
+export function normalizeRepoPath(filePath: string, repoRoot: string): string {
+  return path.relative(repoRoot, filePath).split(path.sep).join("/");
+}
+
+export function cycleSignature(files: readonly string[]): string {
+  return files.toSorted((left, right) => left.localeCompare(right)).join("\n");
+}
+
+export function collectSourceFiles(root: string, options: SourceFileCollectionOptions): string[] {
+  const repoPath = normalizeRepoPath(root, options.repoRoot);
+  if (options.shouldSkipRepoPath?.(repoPath)) {
+    return [];
+  }
+  const stats = statSync(root);
+  if (stats.isFile()) {
+    return options.sourceExtensions.some((extension) => repoPath.endsWith(extension))
+      ? [repoPath]
+      : [];
+  }
+  if (!stats.isDirectory()) {
+    return [];
+  }
+  return readdirSync(root, { withFileTypes: true })
+    .flatMap((entry) => collectSourceFiles(path.join(root, entry.name), options))
+    .toSorted((left, right) => left.localeCompare(right));
+}
+
+export function collectStronglyConnectedComponents(
+  graph: ReadonlyMap<string, readonly string[]>,
+): string[][] {
+  let nextIndex = 0;
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const indexByNode = new Map<string, number>();
+  const lowLinkByNode = new Map<string, number>();
+  const components: string[][] = [];
+
+  const visit = (node: string) => {
+    indexByNode.set(node, nextIndex);
+    lowLinkByNode.set(node, nextIndex);
+    nextIndex += 1;
+    stack.push(node);
+    onStack.add(node);
+
+    for (const next of graph.get(node) ?? []) {
+      if (!indexByNode.has(next)) {
+        visit(next);
+        lowLinkByNode.set(node, Math.min(lowLinkByNode.get(node)!, lowLinkByNode.get(next)!));
+      } else if (onStack.has(next)) {
+        lowLinkByNode.set(node, Math.min(lowLinkByNode.get(node)!, indexByNode.get(next)!));
+      }
+    }
+
+    if (lowLinkByNode.get(node) !== indexByNode.get(node)) {
+      return;
+    }
+    const component: string[] = [];
+    let current: string | undefined;
+    do {
+      current = stack.pop();
+      if (!current) {
+        throw new Error("Import cycle stack underflow");
+      }
+      onStack.delete(current);
+      component.push(current);
+    } while (current !== node);
+    if (component.length > 1 || (graph.get(node) ?? []).includes(node)) {
+      components.push(component.toSorted((left, right) => left.localeCompare(right)));
+    }
+  };
+
+  for (const node of graph.keys()) {
+    if (!indexByNode.has(node)) {
+      visit(node);
+    }
+  }
+
+  return components.toSorted(
+    (left, right) =>
+      right.length - left.length || cycleSignature(left).localeCompare(cycleSignature(right)),
+  );
+}
+
+export function findCycleWitness(
+  component: readonly string[],
+  graph: ReadonlyMap<string, readonly string[]>,
+): string[] {
+  const componentSet = new Set(component);
+  const start = component[0];
+  if (!start) {
+    return [];
+  }
+  const activePath: string[] = [];
+  const visited = new Set<string>();
+  const visit = (node: string): string[] | null => {
+    activePath.push(node);
+    visited.add(node);
+    for (const next of graph.get(node) ?? []) {
+      if (!componentSet.has(next)) {
+        continue;
+      }
+      const existingIndex = activePath.indexOf(next);
+      if (existingIndex >= 0) {
+        return [...activePath.slice(existingIndex), next];
+      }
+      if (!visited.has(next)) {
+        const result = visit(next);
+        if (result) {
+          return result;
+        }
+      }
+    }
+    activePath.pop();
+    return null;
+  };
+  return visit(start) ?? [...component];
+}
+
+export function formatCycle(
+  component: readonly string[],
+  graph: ReadonlyMap<string, readonly string[]>,
+): string {
+  const witness = findCycleWitness(component, graph);
+  return witness.map((file, index) => `${index === 0 ? "  " : "  -> "}${file}`).join("\n");
+}

scripts/lib/tsgo-sparse-guard.mjs

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { readFlagValue } from "./arg-utils.mjs";
 
 const CORE_TEST_CONFIGS = new Set([
   "tsconfig.core.test.json",
@@ -73,16 +74,3 @@ function isMetadataOnlyCommand(args) {
     ["--help", "-h", "--version", "-v", "--init", "--showConfig"].includes(arg),
   );
 }
-
-function readFlagValue(args, name) {
-  for (let index = 0; index < args.length; index++) {
-    const arg = args[index];
-    if (arg === name) {
-      return args[index + 1];
-    }
-    if (arg.startsWith(`${name}=`)) {
-      return arg.slice(name.length + 1);
-    }
-  }
-  return undefined;
-}