@intentius/chant 0.0.1

package/src/discovery/cycles.test.ts

@@ -0,0 +1,238 @@
+import { describe, test, expect } from "bun:test";
+import { detectCycles, normalizeCycleKey } from "./cycles";
+
+describe("detectCycles", () => {
+  test("returns empty array for empty graph", () => {
+    const graph = {};
+    const cycles = detectCycles(graph);
+    expect(cycles).toEqual([]);
+  });
+
+  test("returns empty array for single node with no edges", () => {
+    const graph = {
+      A: [],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles).toEqual([]);
+  });
+
+  test("returns empty array for acyclic graph with multiple nodes", () => {
+    const graph = {
+      A: ["B", "C"],
+      B: ["D"],
+      C: ["D"],
+      D: [],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles).toEqual([]);
+  });
+
+  test("returns empty array for linear chain", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      C: ["D"],
+      D: [],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles).toEqual([]);
+  });
+
+  test("detects simple self-loop", () => {
+    const graph = {
+      A: ["A"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["A"]);
+  });
+
+  test("detects simple two-node cycle", () => {
+    const graph = {
+      A: ["B"],
+      B: ["A"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["A", "B"]);
+  });
+
+  test("detects three-node cycle", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      C: ["A"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["A", "B", "C"]);
+  });
+
+  test("detects longer cycle", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      C: ["D"],
+      D: ["E"],
+      E: ["A"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["A", "B", "C", "D", "E"]);
+  });
+
+  test("detects cycle with branching paths", () => {
+    const graph = {
+      A: ["B", "C"],
+      B: ["D"],
+      C: ["D"],
+      D: ["A"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    // The cycle should be detected from one of the paths
+    expect(cycles[0]).toContain("A");
+    expect(cycles[0]).toContain("D");
+  });
+
+  test("detects multiple independent cycles", () => {
+    const graph = {
+      A: ["B"],
+      B: ["A"],
+      C: ["D"],
+      D: ["C"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(2);
+  });
+
+  test("detects cycle in complex graph with acyclic parts", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      C: ["D"],
+      D: ["B", "E"],
+      E: [],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["B", "C", "D"]);
+  });
+
+  test("handles graph with nodes that have no outgoing edges", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      C: ["A"],
+      D: [],
+      E: ["D"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["A", "B", "C"]);
+  });
+
+  test("handles disconnected components with one containing cycle", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      C: [],
+      D: ["E"],
+      E: ["D"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["D", "E"]);
+  });
+
+  test("detects nested cycles", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      C: ["A", "D"],
+      D: ["E"],
+      E: ["D"],
+    };
+    const cycles = detectCycles(graph);
+    // Should detect at least one cycle
+    expect(cycles.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("handles graph with multiple edges from same node", () => {
+    const graph = {
+      A: ["B", "C", "D"],
+      B: ["E"],
+      C: ["E"],
+      D: ["E"],
+      E: ["A"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0][0]).toBe("A");
+    expect(cycles[0][cycles[0].length - 1]).toBe("E");
+  });
+
+  test("handles nodes referenced as neighbors but not defined as keys", () => {
+    const graph = {
+      A: ["B"],
+      B: ["C"],
+      // C is referenced but not defined
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles).toEqual([]);
+  });
+
+  test("preserves node IDs correctly in cycle path", () => {
+    const graph = {
+      node1: ["node2"],
+      node2: ["node3"],
+      node3: ["node1"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["node1", "node2", "node3"]);
+  });
+
+  test("handles graph with numeric-like string node IDs", () => {
+    const graph = {
+      "1": ["2"],
+      "2": ["3"],
+      "3": ["1"],
+    };
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["1", "2", "3"]);
+  });
+
+  test("accepts Map<string, Set<string>> input", () => {
+    const graph = new Map<string, Set<string>>([
+      ["A", new Set(["B"])],
+      ["B", new Set(["C"])],
+      ["C", new Set(["A"])],
+    ]);
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+    expect(cycles[0]).toEqual(["A", "B", "C"]);
+  });
+
+  test("deduplicates equivalent cycles from different starting nodes", () => {
+    // Both A->B->C->A and B->C->A->B are the same cycle
+    const graph = new Map<string, Set<string>>([
+      ["A", new Set(["B"])],
+      ["B", new Set(["C"])],
+      ["C", new Set(["A"])],
+    ]);
+    const cycles = detectCycles(graph);
+    expect(cycles.length).toBe(1);
+  });
+});
+
+describe("normalizeCycleKey", () => {
+  test("rotates to lexicographically smallest node", () => {
+    expect(normalizeCycleKey(["C", "A", "B", "C"])).toBe("A,B,C");
+  });
+
+  test("handles single-node cycle", () => {
+    expect(normalizeCycleKey(["A", "A"])).toBe("A");
+  });
+});

package/src/discovery/cycles.ts

@@ -0,0 +1,107 @@
+/**
+ * Cycle detection using DFS with three-color marking (white/gray/black).
+ *
+ * Accepts either `Map<string, Set<string>>` or `Record<string, string[]>` as input.
+ * Returns deduplicated cycles, each represented as an array of node IDs.
+ */
+
+type GraphInput = Map<string, Set<string>> | Record<string, string[]>;
+
+/**
+ * Normalize graph input to Map<string, Set<string>>.
+ */
+function normalizeGraph(graph: GraphInput): Map<string, Set<string>> {
+  if (graph instanceof Map) return graph;
+  const result = new Map<string, Set<string>>();
+  for (const [node, neighbors] of Object.entries(graph)) {
+    result.set(node, new Set(neighbors));
+  }
+  return result;
+}
+
+/**
+ * Detects cycles in a directed graph using DFS with three-color marking.
+ *
+ * @param graph - Adjacency list: node → neighbors. Accepts Map<string, Set<string>>
+ *   or Record<string, string[]>.
+ * @returns Array of deduplicated cycles. Each cycle is a node ID array
+ *   (e.g. ["A", "B", "C"]). Self-loops return ["A"].
+ */
+export function detectCycles(graph: GraphInput): string[][] {
+  const g = normalizeGraph(graph);
+
+  const WHITE = 0; // Not visited
+  const GRAY = 1;  // In current DFS path
+  const BLACK = 2; // Fully explored
+
+  const color = new Map<string, number>();
+  const parent = new Map<string, string>();
+  const cycles: string[][] = [];
+  const reportedCycles = new Set<string>();
+
+  for (const node of g.keys()) {
+    color.set(node, WHITE);
+  }
+
+  function dfs(node: string): void {
+    color.set(node, GRAY);
+
+    const neighbors = g.get(node) ?? new Set();
+    for (const neighbor of neighbors) {
+      const c = color.get(neighbor);
+      if (c === undefined || c === WHITE) {
+        if (c === undefined) {
+          // Node referenced but not defined as a key — treat as fully explored
+          continue;
+        }
+        parent.set(neighbor, node);
+        dfs(neighbor);
+      } else if (c === GRAY) {
+        // Found a cycle — reconstruct it
+        const cycle: string[] = [neighbor];
+        let current = node;
+        while (current !== neighbor) {
+          cycle.push(current);
+          current = parent.get(current)!;
+        }
+        cycle.push(neighbor);
+        cycle.reverse();
+
+        // Normalize to avoid duplicate cycle reports
+        const key = normalizeCycleKey(cycle);
+        if (!reportedCycles.has(key)) {
+          reportedCycles.add(key);
+          // Strip the trailing repeated node for a clean cycle representation
+          cycles.push(cycle.slice(0, -1));
+        }
+      }
+    }
+
+    color.set(node, BLACK);
+  }
+
+  for (const node of g.keys()) {
+    if (color.get(node) === WHITE) {
+      dfs(node);
+    }
+  }
+
+  return cycles;
+}
+
+/**
+ * Normalize a cycle for deduplication.
+ * Rotate to start with the lexicographically smallest node.
+ */
+export function normalizeCycleKey(cycle: string[]): string {
+  // Remove the repeated last element for rotation
+  const nodes = cycle.slice(0, -1);
+  let minIdx = 0;
+  for (let i = 1; i < nodes.length; i++) {
+    if (nodes[i] < nodes[minIdx]) {
+      minIdx = i;
+    }
+  }
+  const rotated = [...nodes.slice(minIdx), ...nodes.slice(0, minIdx)];
+  return rotated.join(",");
+}

package/src/discovery/files.test.ts

@@ -0,0 +1,154 @@
+import { describe, test, expect } from "bun:test";
+import { findInfraFiles } from "./files";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("findInfraFiles", () => {
+  test("returns empty array for empty directory", async () => {
+    await withTestDir(async (testDir) => {
+      const files = await findInfraFiles(testDir);
+      expect(files).toEqual([]);
+    });
+  });
+
+  test("finds .ts files in root directory", async () => {
+    await withTestDir(async (testDir) => {
+      await writeFile(join(testDir, "app.ts"), "export const app = {};");
+      await writeFile(join(testDir, "config.ts"), "export const config = {};");
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(2);
+      expect(files.some((f) => f.endsWith("app.ts"))).toBe(true);
+      expect(files.some((f) => f.endsWith("config.ts"))).toBe(true);
+    });
+  });
+
+  test.each([
+    { extension: ".test.ts", pattern: /app\.test\.ts$/ },
+    { extension: ".spec.ts", pattern: /app\.spec\.ts$/ },
+  ])("excludes $extension files", async ({ extension, pattern }) => {
+    await withTestDir(async (testDir) => {
+      await writeFile(join(testDir, "app.ts"), "export const app = {};");
+      await writeFile(join(testDir, `app${extension}`), "test();");
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(1);
+      expect(files[0]).toMatch(/app\.ts$/);
+      expect(files[0]).not.toMatch(pattern);
+    });
+  });
+
+  test("finds .ts files recursively", async () => {
+    await withTestDir(async (testDir) => {
+      const subDir = join(testDir, "src", "lib");
+      await mkdir(subDir, { recursive: true });
+      await writeFile(join(testDir, "root.ts"), "export const root = {};");
+      await writeFile(join(testDir, "src", "app.ts"), "export const app = {};");
+      await writeFile(
+        join(subDir, "utils.ts"),
+        "export const utils = {};"
+      );
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(3);
+      expect(files.some((f) => f.endsWith("root.ts"))).toBe(true);
+      expect(files.some((f) => f.endsWith("app.ts"))).toBe(true);
+      expect(files.some((f) => f.endsWith("utils.ts"))).toBe(true);
+    });
+  });
+
+  test("excludes node_modules directory", async () => {
+    await withTestDir(async (testDir) => {
+      const nodeModulesDir = join(testDir, "node_modules", "some-package");
+      await mkdir(nodeModulesDir, { recursive: true });
+      await writeFile(join(testDir, "app.ts"), "export const app = {};");
+      await writeFile(
+        join(nodeModulesDir, "index.ts"),
+        "export const lib = {};"
+      );
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(1);
+      expect(files[0]).toMatch(/app\.ts$/);
+      expect(files.some((f) => f.includes("node_modules"))).toBe(false);
+    });
+  });
+
+  test("excludes nested node_modules directories", async () => {
+    await withTestDir(async (testDir) => {
+      const srcDir = join(testDir, "src");
+      const nodeModulesDir = join(srcDir, "node_modules");
+      await mkdir(nodeModulesDir, { recursive: true });
+      await writeFile(join(testDir, "app.ts"), "export const app = {};");
+      await writeFile(join(srcDir, "lib.ts"), "export const lib = {};");
+      await writeFile(
+        join(nodeModulesDir, "package.ts"),
+        "export const pkg = {};"
+      );
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(2);
+      expect(files.some((f) => f.endsWith("app.ts"))).toBe(true);
+      expect(files.some((f) => f.endsWith("lib.ts"))).toBe(true);
+      expect(files.some((f) => f.includes("node_modules"))).toBe(false);
+    });
+  });
+
+  test("ignores non-.ts files", async () => {
+    await withTestDir(async (testDir) => {
+      await writeFile(join(testDir, "app.ts"), "export const app = {};");
+      await writeFile(join(testDir, "readme.md"), "# README");
+      await writeFile(join(testDir, "config.json"), "{}");
+      await writeFile(join(testDir, "script.js"), "console.log();");
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(1);
+      expect(files[0]).toMatch(/app\.ts$/);
+    });
+  });
+
+  test("handles mixed file types and test files", async () => {
+    await withTestDir(async (testDir) => {
+      await writeFile(join(testDir, "app.ts"), "export const app = {};");
+      await writeFile(join(testDir, "app.test.ts"), "test();");
+      await writeFile(join(testDir, "app.spec.ts"), "test();");
+      await writeFile(join(testDir, "config.ts"), "export const config = {};");
+      await writeFile(join(testDir, "readme.md"), "# README");
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(2);
+      expect(files.some((f) => f.endsWith("app.ts"))).toBe(true);
+      expect(files.some((f) => f.endsWith("config.ts"))).toBe(true);
+    });
+  });
+
+  test("returns full paths to files", async () => {
+    await withTestDir(async (testDir) => {
+      await writeFile(join(testDir, "app.ts"), "export const app = {};");
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toHaveLength(1);
+      expect(files[0]).toBe(join(testDir, "app.ts"));
+    });
+  });
+
+  test("handles directories with no .ts files", async () => {
+    await withTestDir(async (testDir) => {
+      await mkdir(join(testDir, "docs"), { recursive: true });
+      await writeFile(join(testDir, "docs", "readme.md"), "# README");
+      await writeFile(join(testDir, "package.json"), "{}");
+
+      const files = await findInfraFiles(testDir);
+      expect(files).toEqual([]);
+    });
+  });
+
+  test("handles non-existent directory gracefully", async () => {
+    await withTestDir(async (testDir) => {
+      const nonExistentPath = join(testDir, "does-not-exist");
+      const files = await findInfraFiles(nonExistentPath);
+      expect(files).toEqual([]);
+    });
+  });
+});

package/src/discovery/files.ts

@@ -0,0 +1,61 @@
+import { readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+
+/**
+ * Recursively find all TypeScript infrastructure files in a directory
+ * @param path - The directory path to search
+ * @returns Array of file paths to .ts files (excluding test files)
+ */
+export async function findInfraFiles(path: string): Promise<string[]> {
+  const files: string[] = [];
+  let sourceRoot: string | null = null;
+
+  async function scanDirectory(dir: string): Promise<void> {
+    let entries;
+
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      // Skip directories we can't read
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+
+      // Skip node_modules
+      if (entry.isDirectory() && entry.name === "node_modules") {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        // Child project boundary — a directory with its own barrel file is a
+        // separate scope, but only if we've already found the project's own
+        // source root (the first barrel directory). The project's own src/
+        // with _.ts is the source root, not a child project.
+        const barrelPath = join(fullPath, "_.ts");
+        if (existsSync(barrelPath)) {
+          if (sourceRoot === null) {
+            sourceRoot = fullPath;
+          } else {
+            continue;
+          }
+        }
+        await scanDirectory(fullPath);
+      } else if (entry.isFile()) {
+        // Include only .ts files, exclude test files
+        if (
+          entry.name.endsWith(".ts") &&
+          !entry.name.endsWith(".test.ts") &&
+          !entry.name.endsWith(".spec.ts")
+        ) {
+          files.push(fullPath);
+        }
+      }
+    }
+  }
+
+  await scanDirectory(path);
+  return files;
+}