refactor: use ignore package instead of picomatch for .stageignore

Per review feedback: the ignore package implements gitignore semantics
natively (comments, blank lines, negation, anchoring), so the hand-rolled
compile/match layer is no longer needed.

- Replace picomatch + @types/picomatch with ignore@^7.0.5
- Rename loadStageIgnorePatterns -> loadStageIgnore (returns Ignore | null)
- Drop CompiledPattern, compileIgnorePatterns, isIgnoredByPatterns
- Update prep.ts and show.ts callers
- Update tests to construct Ignore instances directly; add empty-file test
- README: clarify ".gitignore-style patterns" instead of "glob patterns"

Minor behavior change: leading whitespace on a pattern is no longer
stripped (the previous code did line.trim()). This aligns with the
gitignore spec, which strips only trailing whitespace.

Author: onequbitaway

README.md

@@ -79,7 +79,7 @@ Examples:
 
 ### `.stageignore`
 
-Add a `.stageignore` file to your repo root to exclude files from the diff analysis. Uses glob patterns, one per line:
+Add a `.stageignore` file to your repo root to exclude files from the diff analysis. Uses `.gitignore`-style patterns, one per line:
 
 ```
 # Build artifacts

packages/cli/package.json

@@ -49,16 +49,15 @@
     "better-sqlite3": "^12.9.0",
     "commander": "^14.0.3",
     "drizzle-orm": "^0.45.2",
+    "ignore": "^7.0.5",
     "open": "^11.0.0",
     "parse-diff": "^0.11.1",
-    "picomatch": "^4.0.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@stagereview/types": "workspace:*",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.6.0",
-    "@types/picomatch": "^4.0.3",
     "drizzle-kit": "^0.31.10",
     "tsdown": "^0.21.10",
     "typescript": "^5.6.3",

packages/cli/src/__tests__/filter-files.test.ts

@@ -3,8 +3,9 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import type { Hunk, PullRequestFile } from "@stagereview/types/parsed-diff";
 import { LINE_TYPE } from "@stagereview/types/parsed-diff";
+import ignore from "ignore";
 import { describe, expect, it } from "vitest";
-import { filterFilesForLlm, loadStageIgnorePatterns, shouldIncludeFile } from "../filter-files.js";
+import { filterFilesForLlm, loadStageIgnore, shouldIncludeFile } from "../filter-files.js";
 
 function makeHunk(lineCount: number, overrides?: Partial<Hunk>): Hunk {
 	return {
@@ -35,6 +36,10 @@ function makeFile(overrides?: Partial<PullRequestFile>): PullRequestFile {
 	};
 }
 
+function ig(patterns: string[]) {
+	return ignore().add(patterns);
+}
+
 describe("shouldIncludeFile", () => {
 	const denylistedFilenames = [
 		"package-lock.json",
@@ -144,7 +149,7 @@ describe("filterFilesForLlm", () => {
 			makeFile({ path: "build/config.gypi" }),
 			makeFile({ path: "dist/bundle.js" }),
 		];
-		const result = filterFilesForLlm(files, ["build/**", "dist/**"]);
+		const result = filterFilesForLlm(files, ig(["build/**", "dist/**"]));
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("src/app.ts");
 		expect(result.excludedByPath).toEqual(["build/config.gypi", "dist/bundle.js"]);
@@ -156,32 +161,32 @@ describe("filterFilesForLlm", () => {
 			makeFile({ path: "pnpm-lock.yaml" }),
 			makeFile({ path: "generated/schema.ts" }),
 		];
-		const result = filterFilesForLlm(files, ["generated/**"]);
+		const result = filterFilesForLlm(files, ig(["generated/**"]));
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("src/app.ts");
 		expect(result.excludedByPath).toEqual(["pnpm-lock.yaml", "generated/schema.ts"]);
 	});
 
-	it("works normally when stageIgnorePatterns is undefined", () => {
+	it("works normally when stageIgnore is undefined", () => {
 		const files = [makeFile({ path: "src/app.ts" }), makeFile({ path: "pnpm-lock.yaml" })];
 		const result = filterFilesForLlm(files, undefined);
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("src/app.ts");
 	});
 
-	it("works normally when stageIgnorePatterns is empty", () => {
+	it("works normally when stageIgnore is null", () => {
 		const files = [makeFile({ path: "src/app.ts" }), makeFile({ path: "src/utils.ts" })];
-		const result = filterFilesForLlm(files, []);
+		const result = filterFilesForLlm(files, null);
 		expect(result.files).toHaveLength(2);
 	});
 
-	it("matches slashless globs against nested paths via matchBase", () => {
+	it("slashless globs match nested paths", () => {
 		const files = [
 			makeFile({ path: "src/app.ts" }),
 			makeFile({ path: "src/schema.generated.ts" }),
 			makeFile({ path: "lib/deep/nested/types.generated.ts" }),
 		];
-		const result = filterFilesForLlm(files, ["*.generated.ts"]);
+		const result = filterFilesForLlm(files, ig(["*.generated.ts"]));
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("src/app.ts");
 	});
@@ -192,35 +197,34 @@ describe("filterFilesForLlm", () => {
 			makeFile({ path: "build/important.js" }),
 			makeFile({ path: "src/app.ts" }),
 		];
-		const result = filterFilesForLlm(files, ["build/**", "!build/important.js"]);
+		const result = filterFilesForLlm(files, ig(["build/**", "!build/important.js"]));
 		expect(result.files).toHaveLength(2);
 		expect(result.files.map((f) => f.path)).toEqual(["build/important.js", "src/app.ts"]);
 	});
 
 	it("last matching pattern wins with negation", () => {
 		const files = [makeFile({ path: "dist/bundle.js" })];
-		// exclude, re-include, exclude again
-		const result = filterFilesForLlm(files, ["dist/**", "!dist/bundle.js", "*.js"]);
+		const result = filterFilesForLlm(files, ig(["dist/**", "!dist/bundle.js", "*.js"]));
 		expect(result.files).toHaveLength(0);
 	});
 
-	it("strips leading slash from root-anchored patterns", () => {
+	it("leading slash anchors a pattern to the repo root", () => {
 		const files = [makeFile({ path: "dist/bundle.js" }), makeFile({ path: "src/app.ts" })];
-		const result = filterFilesForLlm(files, ["/dist/**"]);
+		const result = filterFilesForLlm(files, ig(["/dist/**"]));
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("src/app.ts");
 	});
 
 	it("root-anchored pattern does not match nested paths", () => {
 		const files = [makeFile({ path: "foo/bar.js" }), makeFile({ path: "src/foo/bar.js" })];
-		const result = filterFilesForLlm(files, ["/foo/**"]);
+		const result = filterFilesForLlm(files, ig(["/foo/**"]));
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("src/foo/bar.js");
 	});
 
 	it("trailing slash matches directory contents", () => {
 		const files = [makeFile({ path: "build/output.js" }), makeFile({ path: "src/app.ts" })];
-		const result = filterFilesForLlm(files, ["build/"]);
+		const result = filterFilesForLlm(files, ig(["build/"]));
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("src/app.ts");
 	});
@@ -230,26 +234,30 @@ describe("filterFilesForLlm", () => {
 			makeFile({ path: "generated/schema.ts" }),
 			makeFile({ path: "generated/keep-this.ts" }),
 		];
-		const result = filterFilesForLlm(files, ["generated/**", "!keep-this.ts"]);
+		const result = filterFilesForLlm(files, ig(["generated/**", "!keep-this.ts"]));
 		expect(result.files).toHaveLength(1);
 		expect(result.files[0]?.path).toBe("generated/keep-this.ts");
 	});
 });
 
-describe("loadStageIgnorePatterns", () => {
+describe("loadStageIgnore", () => {
 	function makeTempDir(): string {
 		return mkdtempSync(path.join(tmpdir(), "stage-test-"));
 	}
 
-	it("returns empty array when .stageignore does not exist", () => {
+	it("returns null when .stageignore does not exist", () => {
 		const dir = makeTempDir();
-		expect(loadStageIgnorePatterns(dir)).toEqual([]);
+		expect(loadStageIgnore(dir)).toBeNull();
 	});
 
 	it("parses patterns from .stageignore", () => {
 		const dir = makeTempDir();
 		writeFileSync(path.join(dir, ".stageignore"), "build/**\ndist/**\n");
-		expect(loadStageIgnorePatterns(dir)).toEqual(["build/**", "dist/**"]);
+		const matcher = loadStageIgnore(dir);
+		expect(matcher).not.toBeNull();
+		expect(matcher?.ignores("build/config.gypi")).toBe(true);
+		expect(matcher?.ignores("dist/bundle.js")).toBe(true);
+		expect(matcher?.ignores("src/app.ts")).toBe(false);
 	});
 
 	it("ignores comments and blank lines", () => {
@@ -258,12 +266,18 @@ describe("loadStageIgnorePatterns", () => {
 			path.join(dir, ".stageignore"),
 			"# Build artifacts\nbuild/**\n\n# Output\ndist/**\n\n",
 		);
-		expect(loadStageIgnorePatterns(dir)).toEqual(["build/**", "dist/**"]);
+		const matcher = loadStageIgnore(dir);
+		expect(matcher?.ignores("build/config.gypi")).toBe(true);
+		expect(matcher?.ignores("dist/bundle.js")).toBe(true);
+		expect(matcher?.ignores("src/app.ts")).toBe(false);
 	});
 
-	it("trims whitespace from patterns", () => {
+	it("empty .stageignore matches nothing", () => {
 		const dir = makeTempDir();
-		writeFileSync(path.join(dir, ".stageignore"), "  build/**  \n  dist/**  \n");
-		expect(loadStageIgnorePatterns(dir)).toEqual(["build/**", "dist/**"]);
+		writeFileSync(path.join(dir, ".stageignore"), "");
+		const matcher = loadStageIgnore(dir);
+		expect(matcher).not.toBeNull();
+		expect(matcher?.ignores("src/app.ts")).toBe(false);
+		expect(matcher?.ignores("build/anything.js")).toBe(false);
 	});
 });

packages/cli/src/filter-files.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import type { PullRequestFile } from "@stagereview/types/parsed-diff";
-import picomatch from "picomatch";
+import ignore, { type Ignore } from "ignore";
 
 const IGNORED_FILENAMES = new Set([
 	"package-lock.json",
@@ -48,59 +48,15 @@ export function shouldIncludeFile(filePath: string): boolean {
 }
 
 /**
- * Load exclusion patterns from a `.stageignore` file in the repo root.
- * Format follows `.gitignore` conventions: one glob pattern per line,
- * blank lines and `#` comments are ignored. Prefix a pattern with `!`
- * to negate (re-include) a previously excluded match.
+ * Load a `.stageignore` file from the repo root into an `Ignore` matcher.
+ * Returns `null` when the file is absent. Parsing, comments, blank lines,
+ * negation, and anchoring semantics all follow `.gitignore` via the
+ * `ignore` package.
  */
-export function loadStageIgnorePatterns(repoRoot: string): string[] {
+export function loadStageIgnore(repoRoot: string): Ignore | null {
 	const ignorePath = path.join(repoRoot, ".stageignore");
-	if (!existsSync(ignorePath)) return [];
-	const content = readFileSync(ignorePath, "utf8");
-	return content
-		.split("\n")
-		.map((line) => line.trim())
-		.filter((line) => line !== "" && !line.startsWith("#"));
-}
-
-interface CompiledPattern {
-	negated: boolean;
-	matcher: picomatch.Matcher;
-}
-
-/**
- * Pre-compile `.stageignore` patterns into matchers. Patterns without a
- * slash use `matchBase` so bare globs like `*.generated.ts` match in
- * subdirectories. Patterns with a slash match the full path. Patterns
- * prefixed with `!` negate a previous match (`.gitignore` semantics:
- * last matching pattern wins).
- */
-export function compileIgnorePatterns(patterns: string[]): CompiledPattern[] {
-	const compiled: CompiledPattern[] = [];
-	for (const raw of patterns) {
-		const negated = raw.startsWith("!");
-		const stripped = negated ? raw.slice(1) : raw;
-		const rooted = stripped.startsWith("/");
-		const unrooted = rooted ? stripped.slice(1) : stripped;
-		const glob = unrooted.endsWith("/") ? `${unrooted}**` : unrooted;
-		if (!glob) continue;
-		const useMatchBase = !rooted && !glob.includes("/");
-		compiled.push({
-			negated,
-			matcher: picomatch(glob, { dot: true, matchBase: useMatchBase }),
-		});
-	}
-	return compiled;
-}
-
-function isIgnoredByPatterns(filePath: string, compiled: CompiledPattern[]): boolean {
-	let ignored = false;
-	for (const { negated, matcher } of compiled) {
-		if (matcher(filePath)) {
-			ignored = !negated;
-		}
-	}
-	return ignored;
+	if (!existsSync(ignorePath)) return null;
+	return ignore().add(readFileSync(ignorePath, "utf8"));
 }
 
 export interface FilterFilesResult {
@@ -110,18 +66,13 @@ export interface FilterFilesResult {
 
 export function filterFilesForLlm(
 	files: PullRequestFile[],
-	stageIgnorePatterns?: string[],
+	stageIgnore?: Ignore | null,
 ): FilterFilesResult {
-	const compiled =
-		stageIgnorePatterns && stageIgnorePatterns.length > 0
-			? compileIgnorePatterns(stageIgnorePatterns)
-			: null;
-
 	const excludedByPath: string[] = [];
 	const reviewable: PullRequestFile[] = [];
 
 	for (const file of files) {
-		if (!shouldIncludeFile(file.path) || (compiled && isIgnoredByPatterns(file.path, compiled))) {
+		if (!shouldIncludeFile(file.path) || stageIgnore?.ignores(file.path)) {
 			excludedByPath.push(file.path);
 			continue;
 		}

packages/cli/src/prep.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import type { Hunk, PullRequestFile } from "@stagereview/types/parsed-diff";
 import { parseGitDiff } from "./diff-parser.js";
-import { filterFilesForLlm, loadStageIgnorePatterns } from "./filter-files.js";
+import { filterFilesForLlm, loadStageIgnore } from "./filter-files.js";
 import { formatHunkDiffWithLineNumbers } from "./format-diff.js";
 import { getCommitMessages, type ResolveScopeOptions, readRepoRoot, resolveScope } from "./git.js";
 import type { WorkingTreeRef } from "./schema.js";
@@ -29,8 +29,8 @@ export function runPrep(
 	const { scope, rawDiff, mergeBaseSha } = resolveScope(options);
 
 	const allFiles = parseGitDiff(rawDiff);
-	const stageIgnorePatterns = loadStageIgnorePatterns(readRepoRoot());
-	const { files } = filterFilesForLlm(allFiles, stageIgnorePatterns);
+	const stageIgnore = loadStageIgnore(readRepoRoot());
+	const { files } = filterFilesForLlm(allFiles, stageIgnore);
 
 	const formattedHunks = files
 		.flatMap((file) => file.hunks.map((hunk) => formatHunkForPrompt(file, hunk)))

packages/cli/src/show.ts

@@ -4,7 +4,7 @@ import open from "open";
 import { buildOtherChangesChapter } from "./build-other-changes.js";
 import { closeDb, getDb } from "./db/client.js";
 import { parseGitDiff } from "./diff-parser.js";
-import { filterFilesForLlm, loadStageIgnorePatterns } from "./filter-files.js";
+import { filterFilesForLlm, loadStageIgnore } from "./filter-files.js";
 import { type ResolveScopeOptions, readRepoContext, readRepoRoot, resolveScope } from "./git.js";
 import { diffRoutes } from "./routes/diff.js";
 import { runRoutes } from "./routes/runs.js";
@@ -90,8 +90,8 @@ function assembleChaptersFile(
 	};
 	const { scope, rawDiff } = resolveScope(options);
 	const allFiles = parseGitDiff(rawDiff);
-	const stageIgnorePatterns = loadStageIgnorePatterns(readRepoRoot());
-	const { files: filteredFiles, excludedByPath } = filterFilesForLlm(allFiles, stageIgnorePatterns);
+	const stageIgnore = loadStageIgnore(readRepoRoot());
+	const { files: filteredFiles, excludedByPath } = filterFilesForLlm(allFiles, stageIgnore);
 
 	validateHunkCoverage(filteredFiles, agentOutput.chapters);
 	const sanitized = sanitizeLineRefs(agentOutput.chapters, filteredFiles);