claude: tool to find cycles with transitive dependencies to async modules

If you have a dependency cycle where all of the modules are async
(transitively because of their dependencies) then it would probably
deadlock if you ran it.

esbuild gives up and emits invalid JS.

So you must either break these cycles, or prevent the async from
propagating to the cycles.

This tool uses ILP to show
- Minimal places to break remove static imports to stop transitive
dependencies before they hit cycles (minimal hitting set)
- Minimal places to remove static imports to break these cycles
(minimum feedback arc set)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: gordonwoodhull

package/src/common/import-report/deno-info.ts

@@ -7,6 +7,8 @@
 *
 */
 
+import { architectureToolsPath } from "../../../../src/core/resources.ts";
+
 ////////////////////////////////////////////////////////////////////////////////
 
 export interface DenoInfoDependency {
@@ -61,8 +63,9 @@ export interface Edge {
 ////////////////////////////////////////////////////////////////////////////////
 
 export async function getDenoInfo(_root: string): Promise<DenoInfoJSON> {
+  const denoBinary = Deno.env.get("QUARTO_DENO") || architectureToolsPath("deno");
   const process = Deno.run({
-    cmd: ["deno", "info", Deno.args[0], "--json"],
+    cmd: [denoBinary, "info", Deno.args[0], "--json"],
     stdout: "piped",
   });
   const rawOutput = await process.output();

package/src/common/import-report/explain-all-cycles.ts

@@ -156,15 +156,19 @@ if (import.meta.main) {
 between all files reachable from some source file.
 
 Usage:
-  $ quarto run explain-all-cycles.ts <entry-point.ts> 
+  $ quarto run --dev explain-all-cycles.ts <entry-point.ts> [--simplify <prefixes...>] [--graph|--toon [filename]]
 
-Examples:
-
-  From ./src:
+Options:
+  --simplify <prefixes...>  Collapse paths with given prefixes (must be first if used)
+  --graph [filename]        Output .dot specification (default: graph.dot)
+  --toon [filename]         Output edges in TOON format (default: cycles.toon)
 
-  $ quarto run quarto.ts
+Examples:
+  $ quarto run --dev package/src/common/import-report/explain-all-cycles.ts src/quarto.ts
+  $ quarto run --dev package/src/common/import-report/explain-all-cycles.ts src/quarto.ts --simplify core/ command/ --toon
+  $ quarto run --dev package/src/common/import-report/explain-all-cycles.ts src/quarto.ts --graph cycles.dot
 
-If the second parameter is "--graph", then this program outputs the .dot specification to the file given by the third parameter, rather opening a full report.
+If no output option is given, opens an interactive preview.
 `,
     );
     Deno.exit(1);
@@ -187,7 +191,17 @@ If the second parameter is "--graph", then this program outputs the .dot specifi
 
   result = dropTypesFiles(result);
 
-  if (args[1] === "--graph") {
+  if (args[1] === "--toon") {
+    // Output in TOON format
+    const lines = [`edges[${result.length}]{from,to}:`];
+    for (const { from, to } of result) {
+      lines.push(`  ${from},${to}`);
+    }
+    Deno.writeTextFileSync(
+      args[2] ?? "cycles.toon",
+      lines.join("\n") + "\n",
+    );
+  } else if (args[1] === "--graph") {
     Deno.writeTextFileSync(
       args[2] ?? "graph.dot",
       generateGraph(result),

package/src/common/import-report/explain-import-chain.ts

@@ -152,37 +152,72 @@ if (import.meta.main) {
 between files in quarto.
 
 Usage:
-  $ quarto run explain-import-chain.ts <source-file.ts> <target-file.ts>
+  $ quarto run --dev explain-import-chain.ts <source-file.ts> <target-file.ts> [--simplify] [--graph|--toon [filename]]
+
+Options:
+  --simplify       Simplify paths by removing common prefix
+  --graph [file]   Output .dot specification (default: import-chain.dot)
+  --toon [file]    Output edges in TOON format (default: import-chain.toon)
 
 Examples:
 
-  From ./src:
+  From project root:
 
-  $ quarto run ../package/scripts/common/explain-import-chain.ts command/render/render.ts core/esbuild.ts
-  $ quarto run ../package/scripts/common/explain-import-chain.ts command/check/cmd.ts core/lib/external/regexpp.mjs
+  $ quarto run --dev package/src/common/import-report/explain-import-chain.ts src/command/render/render.ts src/core/esbuild.ts
+  $ quarto run --dev package/src/common/import-report/explain-import-chain.ts src/command/check/cmd.ts src/core/lib/external/regexpp.mjs
+  $ quarto run --dev package/src/common/import-report/explain-import-chain.ts src/command/render/render.ts src/core/esbuild.ts --simplify --toon
 
 If no dependencies exist, this script will report that:
 
-  $ quarto run ../package/scripts/common/explain-import-chain.ts ../package/src/bld.ts core/lib/external/tree-sitter-deno.js
+  $ quarto run --dev package/src/common/import-report/explain-import-chain.ts package/src/bld.ts src/core/lib/external/tree-sitter-deno.js
 
     package/src/bld.ts does not depend on src/core/lib/external/tree-sitter-deno.js
 
-If the third parameter is "--graph", then this program outputs the .dot specification to the file given by the fourth parameter, rather opening a full report.
+If no output option is given, opens an interactive preview.
 `,
     );
     Deno.exit(1);
   }
-  const json = await getDenoInfo(Deno.args[0]);
+  // Parse arguments
+  let simplify = false;
+  let args = Deno.args;
+
+  if (args[2] === "--simplify") {
+    simplify = true;
+    args = [args[0], args[1], ...args.slice(3)];
+  }
+
+  const json = await getDenoInfo(args[0]);
   const { graph } = moduleGraph(json);
 
-  const targetName = Deno.args[1];
+  const targetName = args[1];
   const target = toFileUrl(resolve(targetName)).href;
-  const result = explain(graph, json.roots[0], target);
-  if (Deno.args[2] === "--graph") {
+  let result = explain(graph, json.roots[0], target);
+
+  // Apply simplification if requested
+  if (simplify && result.length > 0) {
+    const allPaths = result.map(e => [e.from, e.to]).flat();
+    const prefix = longestCommonDirPrefix(allPaths);
+    result = result.map(({ from, to }) => ({
+      from: from.slice(prefix.length),
+      to: to.slice(prefix.length),
+    }));
+  }
+
+  if (args[2] === "--graph") {
     Deno.writeTextFileSync(
-      Deno.args[3],
+      args[3] || "import-chain.dot",
       generateGraph(result, json.roots[0], target),
     );
+  } else if (args[2] === "--toon") {
+    const lines = [`edges[${result.length}]{from,to}:`];
+    for (const { from, to } of result) {
+      lines.push(`  ${from},${to}`);
+    }
+    Deno.writeTextFileSync(
+      args[3] || "import-chain.toon",
+      lines.join("\n") + "\n",
+    );
   } else {
     await buildOutput(result, json.roots[0], target);
   }

package/src/common/import-report/package_report.qmd

@@ -11,7 +11,7 @@ import subprocess
 def run(what):
     ansi_escape = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])')
     str = subprocess.run(
-      ("quarto run %s ../../../../src/quarto.ts" % what).split(" "),
+      ("quarto run --dev %s ../../../../src/quarto.ts" % what).split(" "),
       capture_output = True
     ).stdout.decode('utf-8').replace("Bad import from ", "").replace(" to ", " -> ")
     return ansi_escape.sub("", str)