@aaroncql/pim-agent 0.0.1

package/src/shared/FileScanner.test.ts

@@ -0,0 +1,158 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "bun:test";
+import { FileScanner } from "./FileScanner";
+
+const tempRoots: string[] = [];
+
+const createTempDir = async (): Promise<string> => {
+  const root = await mkdtemp(join(tmpdir(), "pim-file-scanner-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterAll(async () => {
+  await Promise.all(
+    tempRoots.map((root) => rm(root, { force: true, recursive: true }))
+  );
+});
+
+const defaultOptions = {
+  includeDotfiles: false,
+  includeIgnored: false,
+} as const;
+
+describe("FileScanner.scan", () => {
+  test("scans a directory and returns absolute file paths", async () => {
+    const root = await createTempDir();
+    await writeFile(join(root, "a.ts"), "", "utf8");
+    await writeFile(join(root, "b.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", defaultOptions);
+
+    expect(files.toSorted()).toEqual(
+      [join(root, "a.ts"), join(root, "b.ts")].sort()
+    );
+  });
+
+  test("respects gitignore patterns", async () => {
+    const root = await createTempDir();
+    await writeFile(join(root, ".gitignore"), "ignored.ts\n", "utf8");
+    await writeFile(join(root, "kept.ts"), "", "utf8");
+    await writeFile(join(root, "ignored.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", defaultOptions);
+
+    expect(files).toEqual([join(root, "kept.ts")]);
+  });
+
+  test("respects always-ignored defaults like node_modules", async () => {
+    const root = await createTempDir();
+    await mkdir(join(root, "node_modules", "pkg"), { recursive: true });
+    await writeFile(join(root, "node_modules", "pkg", "x.ts"), "", "utf8");
+    await writeFile(join(root, "kept.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", defaultOptions);
+
+    expect(files).toEqual([join(root, "kept.ts")]);
+  });
+
+  test("skips dotfiles by default", async () => {
+    const root = await createTempDir();
+    await mkdir(join(root, ".hidden"), { recursive: true });
+    await writeFile(join(root, ".hidden", "secret.ts"), "", "utf8");
+    await writeFile(join(root, "visible.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", defaultOptions);
+
+    expect(files).toEqual([join(root, "visible.ts")]);
+  });
+
+  test("includes dotfiles when requested", async () => {
+    const root = await createTempDir();
+    await mkdir(join(root, ".hidden"), { recursive: true });
+    await writeFile(join(root, ".hidden", "secret.ts"), "", "utf8");
+    await writeFile(join(root, "visible.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", {
+      ...defaultOptions,
+      includeDotfiles: true,
+    });
+
+    expect(files.toSorted()).toEqual(
+      [join(root, ".hidden", "secret.ts"), join(root, "visible.ts")].sort()
+    );
+  });
+
+  test("includes ignored files when requested", async () => {
+    const root = await createTempDir();
+    await writeFile(join(root, ".gitignore"), "ignored.ts\n", "utf8");
+    await writeFile(join(root, "kept.ts"), "", "utf8");
+    await writeFile(join(root, "ignored.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", {
+      ...defaultOptions,
+      includeIgnored: true,
+    });
+
+    expect(files.toSorted()).toEqual(
+      [join(root, "ignored.ts"), join(root, "kept.ts")].sort()
+    );
+  });
+
+  test("excludes patterns via the exclude option", async () => {
+    const root = await createTempDir();
+    await mkdir(join(root, "src"), { recursive: true });
+    await writeFile(join(root, "src", "app.ts"), "", "utf8");
+    await writeFile(join(root, "src", "app.test.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", {
+      ...defaultOptions,
+      exclude: ["**/*.test.ts"],
+    });
+
+    expect(files).toEqual([join(root, "src", "app.ts")]);
+  });
+
+  test("excludes multiple patterns", async () => {
+    const root = await createTempDir();
+    await mkdir(join(root, "src", "generated"), { recursive: true });
+    await writeFile(join(root, "src", "app.ts"), "", "utf8");
+    await writeFile(join(root, "src", "app.test.ts"), "", "utf8");
+    await writeFile(join(root, "src", "generated", "types.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", {
+      ...defaultOptions,
+      exclude: ["**/*.test.ts", "src/generated/**"],
+    });
+
+    expect(files).toEqual([join(root, "src", "app.ts")]);
+  });
+
+  test("returns an empty array for an empty directory", async () => {
+    const root = await createTempDir();
+
+    const files = await FileScanner.scan(root, "**/*", defaultOptions);
+
+    expect(files).toEqual([]);
+  });
+
+  test("scans nested directories", async () => {
+    const root = await createTempDir();
+    await mkdir(join(root, "a", "b", "c"), { recursive: true });
+    await writeFile(join(root, "a", "top.ts"), "", "utf8");
+    await writeFile(join(root, "a", "b", "mid.ts"), "", "utf8");
+    await writeFile(join(root, "a", "b", "c", "deep.ts"), "", "utf8");
+
+    const files = await FileScanner.scan(root, "**/*.ts", defaultOptions);
+
+    expect(files.toSorted()).toEqual(
+      [
+        join(root, "a", "top.ts"),
+        join(root, "a", "b", "mid.ts"),
+        join(root, "a", "b", "c", "deep.ts"),
+      ].sort()
+    );
+  });
+});

package/src/shared/FileScanner.ts

@@ -0,0 +1,41 @@
+import { resolve } from "node:path";
+import { GitignoreFilter } from "./GitignoreFilter";
+import { GlobExclusions } from "./GlobExclusions";
+
+export type FileScanOptions = {
+  readonly exclude?: readonly string[];
+  readonly includeDotfiles: boolean;
+  readonly includeIgnored: boolean;
+};
+
+export class FileScanner {
+  static async scan(
+    root: string,
+    pattern: string,
+    options: FileScanOptions
+  ): Promise<readonly string[]> {
+    const absoluteRoot = resolve(root);
+    const filter = options.includeIgnored
+      ? undefined
+      : await GitignoreFilter.for(absoluteRoot);
+    const excludes = GlobExclusions.compile(options.exclude);
+    const glob = new Bun.Glob(pattern);
+    const files: string[] = [];
+
+    for await (const filePath of glob.scan({
+      cwd: absoluteRoot,
+      absolute: true,
+      onlyFiles: true,
+      dot: options.includeDotfiles,
+    })) {
+      if (
+        (filter === undefined || !filter.ignores(filePath)) &&
+        !GlobExclusions.ignores(excludes, absoluteRoot, filePath)
+      ) {
+        files.push(filePath);
+      }
+    }
+
+    return files;
+  }
+}

package/src/shared/Fs.ts

@@ -0,0 +1,46 @@
+import { chmod, mkdir, rename, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export class Fs {
+  public static async readJsonOrEmpty<T>(
+    filePath: string,
+    fallback: T
+  ): Promise<T> {
+    try {
+      return (await Bun.file(filePath).json()) as T;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return fallback;
+      }
+      throw new Error(`Failed to parse ${filePath}: ${(err as Error).message}`);
+    }
+  }
+
+  public static async writeAtomic(
+    filePath: string,
+    data: string,
+    mode?: number
+  ): Promise<void> {
+    await mkdir(dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    await Bun.write(tmp, data);
+    const resolvedMode = mode ?? (await Fs.existingMode(filePath));
+    if (resolvedMode !== undefined) {
+      await chmod(tmp, resolvedMode);
+    }
+    await rename(tmp, filePath);
+  }
+
+  private static async existingMode(
+    filePath: string
+  ): Promise<number | undefined> {
+    try {
+      return (await stat(filePath)).mode & 0o777;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return undefined;
+      }
+      throw err;
+    }
+  }
+}

package/src/shared/FsErrors.ts

@@ -0,0 +1,72 @@
+import type { Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+
+export class FsErrors {
+  public static code(error: unknown): string | undefined {
+    return typeof error === "object" && error !== null && "code" in error
+      ? String((error as { code: unknown }).code)
+      : undefined;
+  }
+
+  public static async statOrThrow(path: string): Promise<Stats> {
+    try {
+      return await stat(path);
+    } catch (error) {
+      const code = FsErrors.code(error);
+
+      if (code === "ENOENT") {
+        throw new Error(await FsErrors.renderMissing(path));
+      }
+
+      if (code === "EACCES" || code === "EPERM") {
+        throw new Error(`Permission denied accessing ${path}.`);
+      }
+
+      throw new Error(
+        `Cannot stat ${path}: ${code ?? (error instanceof Error ? error.message : "unknown error")}.`
+      );
+    }
+  }
+
+  public static async renderMissing(path: string): Promise<string> {
+    const suggestions = await FsErrors.suggestSiblings(path);
+    const headline = `Path not found: ${path}. Use glob to locate the file or directory, or verify the path.`;
+    if (suggestions.length === 0) {
+      return headline;
+    }
+    return [headline, "", "Did you mean one of these?", ...suggestions].join(
+      "\n"
+    );
+  }
+
+  private static async suggestSiblings(
+    path: string
+  ): Promise<readonly string[]> {
+    const dir = dirname(path);
+    const base = basename(path).toLowerCase();
+    const stem = base.slice(0, base.length - extname(base).length);
+
+    try {
+      const entries = await readdir(dir);
+      return entries
+        .filter((entry) => {
+          const lower = entry.toLowerCase();
+          const lowerStem = lower.slice(
+            0,
+            lower.length - extname(lower).length
+          );
+          return (
+            lower.includes(base) ||
+            base.includes(lower) ||
+            (stem.length > 0 &&
+              (lowerStem.includes(stem) || stem.includes(lowerStem)))
+          );
+        })
+        .slice(0, 3)
+        .map((entry) => join(dir, entry));
+    } catch {
+      return [];
+    }
+  }
+}

package/src/shared/FuzzyMatcher.test.ts

@@ -0,0 +1,114 @@
+import { expect, test } from "bun:test";
+import { FuzzyMatcher, type FuzzyCandidate } from "./FuzzyMatcher";
+
+type Command = {
+  readonly name: string;
+  readonly description: string;
+};
+
+const commandCandidates = (
+  commands: readonly Command[]
+): readonly FuzzyCandidate<Command>[] =>
+  commands.map((command) => ({
+    item: command,
+    haystacks: [command.name, command.description],
+  }));
+
+test("empty query returns candidates sorted alphabetically by first haystack", () => {
+  const candidates = commandCandidates([
+    { name: "rename", description: "rename" },
+    { name: "clear", description: "clear" },
+    { name: "help", description: "help" },
+  ]);
+
+  const hits = FuzzyMatcher.rank("", candidates);
+
+  expect(hits.map((hit) => hit.item.name)).toEqual(["clear", "help", "rename"]);
+  expect(hits[0]?.score).toBe(0);
+  expect(hits[0]?.positions.size).toBe(0);
+});
+
+test("whitespace-only query is treated as empty", () => {
+  const candidates = commandCandidates([
+    { name: "b", description: "b" },
+    { name: "a", description: "a" },
+  ]);
+
+  const hits = FuzzyMatcher.rank("   ", candidates);
+
+  expect(hits.map((hit) => hit.item.name)).toEqual(["a", "b"]);
+});
+
+test("non-empty query orders results by fzf score", () => {
+  const candidates = commandCandidates([
+    { name: "clear", description: "Clear the session." },
+    { name: "rename", description: "Rename the session." },
+    { name: "resume", description: "Resume a session." },
+    { name: "help", description: "Show help." },
+  ]);
+
+  const hits = FuzzyMatcher.rank("cl", candidates);
+
+  expect(hits.length).toBeGreaterThan(0);
+  expect(hits[0]?.item.name).toBe("clear");
+});
+
+test("limit truncates ranked results", () => {
+  const candidates = commandCandidates([
+    { name: "alpha", description: "" },
+    { name: "alphabet", description: "" },
+    { name: "alphanumeric", description: "" },
+  ]);
+
+  const hits = FuzzyMatcher.rank("a", candidates, { limit: 2 });
+
+  expect(hits.length).toBe(2);
+});
+
+test("limit also applies to the empty-query alphabetical case", () => {
+  const candidates = commandCandidates([
+    { name: "c", description: "" },
+    { name: "a", description: "" },
+    { name: "b", description: "" },
+  ]);
+
+  const hits = FuzzyMatcher.rank("", candidates, { limit: 2 });
+
+  expect(hits.map((hit) => hit.item.name)).toEqual(["a", "b"]);
+});
+
+test("ties on score break toward the earlier match start", () => {
+  const candidates = commandCandidates([
+    { name: "new", description: "Start a new session." },
+    { name: "status", description: "Show the current session status." },
+  ]);
+
+  const hits = FuzzyMatcher.rank("sta", candidates);
+
+  expect(hits[0]?.item.name).toBe("status");
+});
+
+test("ties on score and start break toward the shorter haystack", () => {
+  const candidates: readonly FuzzyCandidate<string>[] = [
+    {
+      item: "src/shared/DiffLines.test.ts",
+      haystacks: ["src/shared/DiffLines.test.ts"],
+    },
+    { item: "src/shared/DiffLines.ts", haystacks: ["src/shared/DiffLines.ts"] },
+  ];
+
+  const hits = FuzzyMatcher.rank("difflines", candidates);
+
+  expect(hits[0]?.item).toBe("src/shared/DiffLines.ts");
+});
+
+test("matches against the second haystack when the first does not contain the query", () => {
+  const candidates = commandCandidates([
+    { name: "noop", description: "fully unrelated" },
+    { name: "x", description: "rename the session" },
+  ]);
+
+  const hits = FuzzyMatcher.rank("rename", candidates);
+
+  expect(hits[0]?.item.name).toBe("x");
+});

package/src/shared/FuzzyMatcher.ts

@@ -0,0 +1,73 @@
+import { byLengthAsc, byStartAsc, Fzf } from "fzf";
+
+export type FuzzyCandidate<T> = {
+  readonly item: T;
+  readonly haystacks: readonly string[];
+};
+
+export type FuzzyHit<T> = {
+  readonly item: T;
+  readonly score: number;
+  readonly positions: ReadonlySet<number>;
+};
+
+export type FuzzyRankOptions = {
+  readonly limit?: number;
+};
+
+export type FuzzyIndex<T> = {
+  readonly find: (
+    query: string,
+    options?: FuzzyRankOptions
+  ) => readonly FuzzyHit<T>[];
+};
+
+const HAYSTACK_SEPARATOR = " ";
+
+export class FuzzyMatcher {
+  public static rank<T>(
+    query: string,
+    candidates: readonly FuzzyCandidate<T>[],
+    options: FuzzyRankOptions = {}
+  ): readonly FuzzyHit<T>[] {
+    return FuzzyMatcher.prepare(candidates).find(query, options);
+  }
+
+  public static prepare<T>(
+    candidates: readonly FuzzyCandidate<T>[]
+  ): FuzzyIndex<T> {
+    const fzf = new Fzf<readonly FuzzyCandidate<T>[]>(candidates, {
+      selector: (candidate) => candidate.haystacks.join(HAYSTACK_SEPARATOR),
+      tiebreakers: [byStartAsc, byLengthAsc],
+    });
+
+    let emptyHits: readonly FuzzyHit<T>[] | undefined;
+
+    return {
+      find: (query, options = {}) => {
+        const trimmed = query.trim();
+        const limit = options.limit ?? Infinity;
+        if (trimmed.length === 0) {
+          if (emptyHits === undefined) {
+            emptyHits = [...candidates]
+              .sort((a, b) =>
+                (a.haystacks[0] ?? "").localeCompare(b.haystacks[0] ?? "")
+              )
+              .map((candidate) => ({
+                item: candidate.item,
+                score: 0,
+                positions: new Set<number>(),
+              }));
+          }
+          return limit === Infinity ? emptyHits : emptyHits.slice(0, limit);
+        }
+        const hits = fzf.find(trimmed).map((result) => ({
+          item: result.item.item,
+          score: result.score,
+          positions: result.positions,
+        }));
+        return limit === Infinity ? hits : hits.slice(0, limit);
+      },
+    };
+  }
+}

package/src/shared/GitignoreFilter.test.ts

@@ -0,0 +1,64 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, expect, test } from "bun:test";
+import { GitignoreFilter } from "./GitignoreFilter";
+
+const tempRoots: string[] = [];
+
+const createTempDir = async (): Promise<string> => {
+  const root = await mkdtemp(join(tmpdir(), "pim-gitignore-filter-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterAll(async () => {
+  await Promise.all(
+    tempRoots.map((root) => rm(root, { force: true, recursive: true }))
+  );
+});
+
+test("applies hardcoded defaults", async () => {
+  const root = await createTempDir();
+  const filter = await GitignoreFilter.for(root);
+
+  expect(filter.ignores(join(root, "node_modules", "pkg", "index.js"))).toBe(
+    true
+  );
+  expect(filter.ignores(join(root, ".git", "config"))).toBe(true);
+  expect(filter.ignores(join(root, "src", "index.ts"))).toBe(false);
+});
+
+test("loads gitignore patterns from root up to the git boundary", async () => {
+  const root = await createTempDir();
+  const project = join(root, "project");
+  const nested = join(project, "packages", "app");
+
+  await mkdir(join(project, ".git"), { recursive: true });
+  await mkdir(nested, { recursive: true });
+  await writeFile(
+    join(project, ".gitignore"),
+    ["*.tmp", "*.log", "!important.log", "logs/", "/anchored.txt"].join("\n"),
+    "utf8"
+  );
+  await writeFile(join(nested, ".gitignore"), "local.txt\n", "utf8");
+
+  const filter = await GitignoreFilter.for(nested);
+
+  expect(filter.ignores(join(nested, "scratch.tmp"))).toBe(true);
+  expect(filter.ignores(join(nested, "logs", "app.log"))).toBe(true);
+  expect(filter.ignores(join(project, "anchored.txt"))).toBe(true);
+  expect(filter.ignores(join(nested, "anchored.txt"))).toBe(false);
+  expect(filter.ignores(join(nested, "drop.log"))).toBe(true);
+  expect(filter.ignores(join(nested, "important.log"))).toBe(false);
+  expect(filter.ignores(join(nested, "local.txt"))).toBe(true);
+});
+
+test("rejects relative paths", async () => {
+  const root = await createTempDir();
+  const filter = await GitignoreFilter.for(root);
+
+  expect(() => filter.ignores("src/index.ts")).toThrow(
+    "Expected absolute path"
+  );
+});