@aaroncql/pim-agent 0.0.1

package/src/extensions/glob/render.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import type { GlobMatch } from "./glob";
+import { formatTitle, renderFiles } from "./render";
+
+const fixture: readonly GlobMatch[] = [
+  { path: "/repo/newer.ts", mtime: 2_000 },
+  { path: "/repo/older.ts", mtime: 1_000 },
+];
+
+const relativeOptions = {
+  cwd: "/repo",
+  pathFormat: "relative",
+} as const;
+
+const absoluteOptions = {
+  cwd: "/repo",
+  pathFormat: "absolute",
+} as const;
+
+describe("renderFiles", () => {
+  test("joins paths with newlines, newest first, relative by default", () => {
+    const outcome = renderFiles(fixture, 1000, relativeOptions);
+    expect(outcome.body).toBe("newer.ts\nolder.ts");
+    expect(outcome.totalItems).toBe(2);
+    expect(outcome.visibleItems).toBe(2);
+    expect(outcome.truncated).toBe(false);
+  });
+
+  test("can render absolute paths", () => {
+    const outcome = renderFiles(fixture, 1000, absoluteOptions);
+    expect(outcome.body).toBe("/repo/newer.ts\n/repo/older.ts");
+  });
+
+  test("flips truncated when results exceed headLimit", () => {
+    const outcome = renderFiles(fixture, 1, relativeOptions);
+    expect(outcome.body).toBe("newer.ts");
+    expect(outcome.truncated).toBe(true);
+    expect(outcome.visibleItems).toBe(1);
+    expect(outcome.totalItems).toBe(2);
+  });
+
+  test("returns a no-match outcome when there are no results", () => {
+    const outcome = renderFiles([], 1000, relativeOptions);
+    expect(outcome.body).toBe("No matches.");
+    expect(outcome.truncated).toBe(false);
+    expect(outcome.totalItems).toBe(0);
+    expect(outcome.visibleItems).toBe(0);
+  });
+});
+
+describe("formatTitle", () => {
+  test("uses relative path under cwd", () => {
+    const title = formatTitle({
+      pattern: "**/*.ts",
+      path: "/repo/src",
+      cwd: "/repo",
+    });
+    expect(title).toBe("**/*.ts in src");
+  });
+
+  test("omits location when path is undefined", () => {
+    const title = formatTitle({
+      pattern: "**/*.ts",
+      path: undefined,
+      cwd: "/repo",
+    });
+    expect(title).toBe("**/*.ts");
+  });
+
+  test("omits location when path resolves to cwd", () => {
+    const title = formatTitle({
+      pattern: "**/*.ts",
+      path: ".",
+      cwd: "/repo",
+    });
+    expect(title).toBe("**/*.ts");
+  });
+
+  test("omits location when path is the absolute cwd", () => {
+    const title = formatTitle({
+      pattern: "**/*.ts",
+      path: "/repo",
+      cwd: "/repo",
+    });
+    expect(title).toBe("**/*.ts");
+  });
+
+  test("uses '...' placeholder when pattern is undefined", () => {
+    const title = formatTitle({
+      pattern: undefined,
+      path: undefined,
+      cwd: "/repo",
+    });
+    expect(title).toBe("...");
+  });
+
+  test("appends pluralized file count when provided", () => {
+    const title = formatTitle({
+      pattern: "**/*.ts",
+      path: "/repo/src",
+      cwd: "/repo",
+      fileCount: 3,
+    });
+    expect(title).toBe("**/*.ts in src (3 files)");
+  });
+
+  test("uses singular noun for a single file", () => {
+    const title = formatTitle({
+      pattern: "**/*.ts",
+      path: undefined,
+      cwd: "/repo",
+      fileCount: 1,
+    });
+    expect(title).toBe("**/*.ts (1 file)");
+  });
+
+  test("shows zero count without omitting the suffix", () => {
+    const title = formatTitle({
+      pattern: "**/*.ts",
+      path: undefined,
+      cwd: "/repo",
+      fileCount: 0,
+    });
+    expect(title).toBe("**/*.ts (0 files)");
+  });
+});

package/src/extensions/glob/render.ts

@@ -0,0 +1,74 @@
+import { OutputBudget } from "../../shared/OutputBudget";
+import { Paths } from "../../shared/Paths";
+import type { GlobMatch } from "./glob";
+import type { GlobPathFormat } from "./schema";
+
+export type RenderOutcome = {
+  readonly body: string;
+  readonly totalItems: number;
+  readonly visibleItems: number;
+  readonly truncated: boolean;
+};
+
+export type RenderOptions = {
+  readonly cwd: string;
+  readonly pathFormat: GlobPathFormat;
+};
+
+export function renderFiles(
+  matches: readonly GlobMatch[],
+  headLimit: number,
+  options: RenderOptions
+): RenderOutcome {
+  if (matches.length === 0) {
+    return {
+      body: "No matches.",
+      totalItems: 0,
+      visibleItems: 0,
+      truncated: false,
+    };
+  }
+
+  const lines = matches.map((match) => formatPath(match.path, options));
+  const headCapped = lines.slice(0, headLimit);
+  const { visible } = OutputBudget.applyByteCap(headCapped);
+  const truncated = visible.length < lines.length;
+
+  return {
+    body: visible.join("\n"),
+    totalItems: lines.length,
+    visibleItems: visible.length,
+    truncated,
+  };
+}
+
+export type TitleOptions = {
+  readonly pattern: string | undefined;
+  readonly path: string | undefined;
+  readonly cwd: string;
+  readonly fileCount?: number;
+};
+
+export function formatTitle(options: TitleOptions): string {
+  const pattern = options.pattern ?? "...";
+  const resolved =
+    options.path === undefined
+      ? undefined
+      : Paths.resolve(options.path, options.cwd);
+  const target =
+    resolved === undefined || resolved === options.cwd
+      ? undefined
+      : Paths.displayRelative(resolved, options.cwd);
+  const location = target ? ` in ${target}` : "";
+  const suffix =
+    options.fileCount === undefined
+      ? ""
+      : ` (${options.fileCount} ${options.fileCount === 1 ? "file" : "files"})`;
+  return `${pattern}${location}${suffix}`;
+}
+
+function formatPath(path: string, options: RenderOptions): string {
+  return options.pathFormat === "absolute"
+    ? path
+    : Paths.displayRelative(path, options.cwd);
+}

package/src/extensions/glob/schema.ts

@@ -0,0 +1,52 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+export const GLOB_HEAD_LIMIT_MAX = 1000;
+
+export const GLOB_PATH_FORMATS = ["relative", "absolute"] as const;
+
+export const globSchema = Type.Object({
+  pattern: Type.String({
+    description: "Glob pattern relative to path (eg. **/*.ts).",
+  }),
+  path: Type.Optional(
+    Type.String({
+      description:
+        "Absolute or relative path to directory (resolved against cwd). Defaults to cwd.",
+    })
+  ),
+  exclude: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Glob patterns to exclude, relative to path (eg. **/*.test.ts or dist/**).",
+    })
+  ),
+  includeDotfiles: Type.Optional(
+    Type.Boolean({
+      description:
+        "Include dot-prefixed files and directories such as .env or .github. Defaults to false.",
+    })
+  ),
+  includeIgnored: Type.Optional(
+    Type.Boolean({
+      description:
+        "Include gitignored and normally ignored paths such as node_modules. Defaults to false.",
+    })
+  ),
+  pathFormat: Type.Optional(
+    StringEnum(GLOB_PATH_FORMATS, {
+      description:
+        "`relative` (default): output paths relative to cwd when possible. `absolute`: output absolute paths.",
+    })
+  ),
+  headLimit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: GLOB_HEAD_LIMIT_MAX,
+      description: `Maximum returned entries. Defaults to ${GLOB_HEAD_LIMIT_MAX}.`,
+    })
+  ),
+});
+
+export type GlobInput = Static<typeof globSchema>;
+export type GlobPathFormat = (typeof GLOB_PATH_FORMATS)[number];

package/src/extensions/grep/grep.test.ts

@@ -0,0 +1,387 @@
+import { mkdir, mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "bun:test";
+import { buildMatcher, findMatches } from "./grep";
+
+const tempRoots: string[] = [];
+
+const tempRoot = async (): Promise<string> => {
+  const root = await mkdtemp(join(tmpdir(), "pim-grep-tool-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterAll(async () => {
+  await Promise.all(
+    tempRoots.map((root) => rm(root, { force: true, recursive: true }))
+  );
+});
+
+const makeMatcher = (
+  pattern: string,
+  options?: {
+    readonly caseInsensitive?: boolean;
+    readonly matchAcrossLines?: boolean;
+  }
+) =>
+  buildMatcher({
+    pattern,
+    caseInsensitive: options?.caseInsensitive ?? false,
+    matchAcrossLines: options?.matchAcrossLines ?? false,
+  });
+
+const defaultScanOptions = {
+  includeDotfiles: false,
+  includeIgnored: false,
+} as const;
+
+describe("buildMatcher", () => {
+  test("compiles regexes with no flags by default", () => {
+    const matcher = makeMatcher("alpha");
+    expect(matcher.regex.flags).toBe("");
+    expect(matcher.regex.test("alpha")).toBe(true);
+    expect(matcher.regex.test("Alpha")).toBe(false);
+  });
+
+  test("applies the i flag for caseInsensitive regexes", () => {
+    const matcher = makeMatcher("alpha", { caseInsensitive: true });
+    expect(matcher.regex.flags).toBe("i");
+    expect(matcher.regex.test("Alpha")).toBe(true);
+  });
+
+  test("applies the s flag for matchAcrossLines regexes", () => {
+    const matcher = makeMatcher(".", { matchAcrossLines: true });
+    expect(matcher.regex.flags).toBe("s");
+    expect(matcher.regex.test("\n")).toBe(true);
+  });
+
+  test("throws an actionable error on invalid regex syntax", () => {
+    expect(() => makeMatcher("(")).toThrow(/Invalid regular expression/);
+  });
+});
+
+describe("findMatches", () => {
+  test("returns content matches with line numbers", async () => {
+    const root = await tempRoot();
+    const nested = join(root, "nested");
+    const older = join(root, "older.txt");
+    const newer = join(nested, "newer.txt");
+
+    await mkdir(nested);
+    await writeFile(older, "alpha\nbeta", "utf8");
+    await writeFile(newer, "gamma\nalphabet\nalpha", "utf8");
+    await utimes(
+      older,
+      new Date("2024-01-01T00:00:00Z"),
+      new Date("2024-01-01T00:00:00Z")
+    );
+    await utimes(
+      newer,
+      new Date("2024-01-02T00:00:00Z"),
+      new Date("2024-01-02T00:00:00Z")
+    );
+
+    const matches = await findMatches(
+      root,
+      undefined,
+      makeMatcher("alpha"),
+      defaultScanOptions
+    );
+
+    expect(matches.map((match) => match.filePath)).toEqual([newer, older]);
+    expect(matches[0]?.lines).toEqual([
+      { lineNumber: 2, text: "alphabet" },
+      { lineNumber: 3, text: "alpha" },
+    ]);
+    expect(matches[1]?.lines).toEqual([{ lineNumber: 1, text: "alpha" }]);
+  });
+
+  test("escapes regex metacharacters when searching literal text", async () => {
+    const root = await tempRoot();
+    const path = join(root, "code.ts");
+    await writeFile(path, "useFoo(\nfoo.bar[0]\n", "utf8");
+
+    const matches = await findMatches(
+      root,
+      undefined,
+      makeMatcher("foo\\.bar\\[0\\]"),
+      defaultScanOptions
+    );
+
+    expect(matches.map((match) => match.filePath)).toEqual([path]);
+    expect(matches[0]?.lines).toEqual([{ lineNumber: 2, text: "foo.bar[0]" }]);
+  });
+
+  test("supports regular expressions", async () => {
+    const root = await tempRoot();
+    const path = join(root, "code.ts");
+    await writeFile(path, "alpha\nbeta\n", "utf8");
+
+    const matches = await findMatches(
+      root,
+      undefined,
+      makeMatcher("^a.*a$"),
+      defaultScanOptions
+    );
+
+    expect(matches.map((match) => match.filePath)).toEqual([path]);
+    expect(matches[0]?.lines).toEqual([{ lineNumber: 1, text: "alpha" }]);
+  });
+
+  test("matches escaped dots and alternation as regex syntax", async () => {
+    const root = await tempRoot();
+    const schema = join(root, "src", "extensions", "todo", "schema.ts");
+    const helper = join(root, "src", "shared", "arrays.ts");
+
+    await mkdir(join(root, "src", "extensions", "todo"), { recursive: true });
+    await mkdir(join(root, "src", "shared"), { recursive: true });
+    await writeFile(schema, "const x = Type.Union([Type.String()]);\n", "utf8");
+    await writeFile(
+      helper,
+      "export const oneOrMany = normalizeArray;\n",
+      "utf8"
+    );
+
+    const typeUnionMatches = await findMatches(
+      root,
+      "src/extensions/**/schema.ts",
+      makeMatcher("Type\\.Union"),
+      defaultScanOptions
+    );
+    const alternationMatches = await findMatches(
+      root,
+      "src/**/*.ts",
+      makeMatcher("StringOrArray|OneOrMany|oneOrMany|normalizeArray"),
+      defaultScanOptions
+    );
+
+    expect(typeUnionMatches.map((match) => match.filePath)).toEqual([schema]);
+    expect(alternationMatches.map((match) => match.filePath)).toEqual([helper]);
+  });
+
+  test("matchAcrossLines enables regex matches spanning line breaks", async () => {
+    const root = await tempRoot();
+    const path = join(root, "block.txt");
+    await writeFile(path, "before\nBEGIN\nmiddle\nEND\nafter\n", "utf8");
+
+    const withoutAcrossLines = await findMatches(
+      root,
+      undefined,
+      makeMatcher("BEGIN.*END"),
+      defaultScanOptions
+    );
+    const withAcrossLines = await findMatches(
+      root,
+      undefined,
+      makeMatcher("BEGIN.*END", { matchAcrossLines: true }),
+      defaultScanOptions
+    );
+
+    expect(withoutAcrossLines).toEqual([]);
+    expect(withAcrossLines.map((match) => match.filePath)).toEqual([path]);
+    expect(withAcrossLines[0]?.ranges).toEqual([
+      { startLineNumber: 2, endLineNumber: 4 },
+    ]);
+    expect(withAcrossLines[0]?.lines).toEqual([
+      { lineNumber: 2, text: "BEGIN" },
+      { lineNumber: 3, text: "middle" },
+      { lineNumber: 4, text: "END" },
+    ]);
+  });
+
+  test("matchAcrossLines enables exact regex matches spanning line breaks", async () => {
+    const root = await tempRoot();
+    const path = join(root, "block.txt");
+    await writeFile(path, "BEGIN\nmiddle\nEND\n", "utf8");
+
+    const matches = await findMatches(
+      root,
+      undefined,
+      makeMatcher("BEGIN\nmiddle", { matchAcrossLines: true }),
+      defaultScanOptions
+    );
+
+    expect(matches.map((match) => match.filePath)).toEqual([path]);
+    expect(matches[0]?.ranges).toEqual([
+      { startLineNumber: 1, endLineNumber: 2 },
+    ]);
+  });
+
+  test("respects gitignore, dotfiles, and the always-ignored defaults", async () => {
+    const root = await tempRoot();
+    const src = join(root, "src");
+    const ignored = join(src, "ignored.ts");
+    const kept = join(src, "kept.ts");
+    const nodeModules = join(root, "node_modules", "pkg", "x.ts");
+    const dot = join(root, ".secret", "x.ts");
+
+    await mkdir(src, { recursive: true });
+    await mkdir(join(root, "node_modules", "pkg"), { recursive: true });
+    await mkdir(join(root, ".secret"), { recursive: true });
+    await writeFile(join(root, ".gitignore"), "ignored.ts\n", "utf8");
+    await writeFile(ignored, "needle\n", "utf8");
+    await writeFile(kept, "needle\n", "utf8");
+    await writeFile(nodeModules, "needle\n", "utf8");
+    await writeFile(dot, "needle\n", "utf8");
+
+    const matches = await findMatches(
+      root,
+      undefined,
+      makeMatcher("needle"),
+      defaultScanOptions
+    );
+
+    expect(matches.map((match) => match.filePath)).toEqual([kept]);
+  });
+
+  test("can include dotfiles and ignored paths", async () => {
+    const root = await tempRoot();
+    const kept = join(root, "kept.ts");
+    const ignored = join(root, "ignored.ts");
+    const dot = join(root, ".secret", "x.ts");
+
+    await mkdir(join(root, ".secret"), { recursive: true });
+    await writeFile(join(root, ".gitignore"), "ignored.ts\n", "utf8");
+    await writeFile(kept, "needle\n", "utf8");
+    await writeFile(ignored, "needle\n", "utf8");
+    await writeFile(dot, "needle\n", "utf8");
+
+    const matches = await findMatches(root, undefined, makeMatcher("needle"), {
+      includeDotfiles: true,
+      includeIgnored: true,
+    });
+
+    expect(matches.map((match) => match.filePath).sort()).toEqual(
+      [dot, ignored, kept].sort()
+    );
+  });
+
+  test("searches direct file paths even when they are dotfiles or ignored", async () => {
+    const root = await tempRoot();
+    const ignored = join(root, "ignored.ts");
+    const dotfile = join(root, ".env");
+
+    await writeFile(join(root, ".gitignore"), "ignored.ts\n", "utf8");
+    await writeFile(ignored, "needle\n", "utf8");
+    await writeFile(dotfile, "needle\n", "utf8");
+
+    const ignoredMatches = await findMatches(
+      ignored,
+      undefined,
+      makeMatcher("needle"),
+      defaultScanOptions
+    );
+    const dotfileMatches = await findMatches(
+      dotfile,
+      undefined,
+      makeMatcher("needle"),
+      defaultScanOptions
+    );
+
+    expect(ignoredMatches.map((match) => match.filePath)).toEqual([ignored]);
+    expect(dotfileMatches.map((match) => match.filePath)).toEqual([dotfile]);
+  });
+
+  test("filters by glob", async () => {
+    const root = await tempRoot();
+    const ts = join(root, "a.ts");
+    const md = join(root, "a.md");
+
+    await writeFile(ts, "needle", "utf8");
+    await writeFile(md, "needle", "utf8");
+
+    const matches = await findMatches(
+      root,
+      "**/*.ts",
+      makeMatcher("needle"),
+      defaultScanOptions
+    );
+
+    expect(matches.map((match) => match.filePath)).toEqual([ts]);
+  });
+
+  test("excludes a single glob pattern", async () => {
+    const root = await tempRoot();
+    const source = join(root, "src", "app.ts");
+    const test = join(root, "src", "app.test.ts");
+
+    await mkdir(join(root, "src"), { recursive: true });
+    await writeFile(source, "needle", "utf8");
+    await writeFile(test, "needle", "utf8");
+
+    const matches = await findMatches(root, "**/*.ts", makeMatcher("needle"), {
+      ...defaultScanOptions,
+      exclude: ["**/*.test.ts"],
+    });
+
+    expect(matches.map((match) => match.filePath)).toEqual([source]);
+  });
+
+  test("excludes multiple glob patterns", async () => {
+    const root = await tempRoot();
+    const source = join(root, "src", "app.ts");
+    const test = join(root, "src", "app.test.ts");
+    const generated = join(root, "src", "generated", "types.ts");
+
+    await mkdir(join(root, "src", "generated"), { recursive: true });
+    await writeFile(source, "needle", "utf8");
+    await writeFile(test, "needle", "utf8");
+    await writeFile(generated, "needle", "utf8");
+
+    const matches = await findMatches(root, "**/*.ts", makeMatcher("needle"), {
+      ...defaultScanOptions,
+      exclude: ["**/*.test.ts", "src/generated/**"],
+    });
+
+    expect(matches.map((match) => match.filePath)).toEqual([source]);
+  });
+
+  test("skips binary files", async () => {
+    const root = await tempRoot();
+    const text = join(root, "text.txt");
+    const binary = join(root, "data.bin");
+
+    await writeFile(text, "needle\n", "utf8");
+    await Bun.write(binary, new Uint8Array([0x6e, 0x00, 0x65, 0x65]));
+
+    const matches = await findMatches(
+      root,
+      undefined,
+      makeMatcher("n"),
+      defaultScanOptions
+    );
+
+    expect(matches.map((match) => match.filePath)).toEqual([text]);
+  });
+
+  test("matches a single file path directly", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta\nalphabet", "utf8");
+
+    const matches = await findMatches(
+      path,
+      undefined,
+      makeMatcher("alpha"),
+      defaultScanOptions
+    );
+
+    expect(matches.length).toBe(1);
+    expect(matches[0]?.lines).toEqual([
+      { lineNumber: 1, text: "alpha" },
+      { lineNumber: 3, text: "alphabet" },
+    ]);
+  });
+
+  test("throws an actionable error when the path does not exist", async () => {
+    const root = await tempRoot();
+    const missing = join(root, "nope");
+
+    await expect(
+      findMatches(missing, undefined, makeMatcher("x"), defaultScanOptions)
+    ).rejects.toThrow(
+      `Path not found: ${missing}. Use glob to locate the file or directory, or verify the path.`
+    );
+  });
+});