@os-eco/overstory-cli 0.10.3 → 0.11.0

package/src/agents/scope-detect.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import {
+	detectScopeViolation,
+	findScopeViolations,
+	hasExpansionReason,
+	IMPLEMENTATION_CAPABILITIES,
+	parseExpansionReasonsFromGitLog,
+} from "./scope-detect.ts";
+
+describe("findScopeViolations", () => {
+	test("literal match: in-scope file is not a violation", () => {
+		const result = findScopeViolations(["src/foo.ts"], ["src/foo.ts"]);
+		expect(result).toEqual([]);
+	});
+
+	test("glob match: src/foo/**/*.ts allows nested file", () => {
+		const result = findScopeViolations(
+			["src/foo/bar/baz.ts", "src/foo/qux.ts"],
+			["src/foo/**/*.ts"],
+		);
+		expect(result).toEqual([]);
+	});
+
+	test("out-of-scope file is reported", () => {
+		const result = findScopeViolations(["src/other.ts"], ["src/foo.ts"]);
+		expect(result).toEqual(["src/other.ts"]);
+	});
+
+	test("empty fileScope is treated as unrestricted", () => {
+		const result = findScopeViolations(["any/file.ts", "another.ts"], []);
+		expect(result).toEqual([]);
+	});
+
+	test("partial violations: returns only the out-of-scope subset", () => {
+		const result = findScopeViolations(
+			["src/foo.ts", "src/other.ts", "src/bar.ts"],
+			["src/foo.ts", "src/bar.ts"],
+		);
+		expect(result).toEqual(["src/other.ts"]);
+	});
+
+	test("glob match: literal path equals scope entry without a glob char", () => {
+		const result = findScopeViolations(["a.ts"], ["a.ts"]);
+		expect(result).toEqual([]);
+	});
+});
+
+describe("hasExpansionReason", () => {
+	test("expansion_reason: with value → true", () => {
+		expect(hasExpansionReason("expansion_reason: foo")).toBe(true);
+	});
+
+	test("Expansion_Reason: case-insensitive → true", () => {
+		expect(hasExpansionReason("Expansion_Reason: bar")).toBe(true);
+	});
+
+	test("EXPANSION_REASON: multi-word value → true", () => {
+		expect(hasExpansionReason("EXPANSION_REASON: baz quux")).toBe(true);
+	});
+
+	test("expansion_reason: empty value → false", () => {
+		expect(hasExpansionReason("expansion_reason:")).toBe(false);
+	});
+
+	test("expansion_reason: only whitespace → false", () => {
+		expect(hasExpansionReason("expansion_reason:   ")).toBe(false);
+	});
+
+	test("expansion-reason: hyphen separator → false", () => {
+		expect(hasExpansionReason("expansion-reason: foo")).toBe(false);
+	});
+
+	test("no marker → false", () => {
+		expect(hasExpansionReason("no reason here")).toBe(false);
+	});
+
+	test("marker embedded in commit body with prefix → true", () => {
+		const body = "Refactor the thing\n\nexpansion_reason: had to update shared types\n";
+		expect(hasExpansionReason(body)).toBe(true);
+	});
+});
+
+describe("parseExpansionReasonsFromGitLog", () => {
+	test("returns each value across multiple commit bodies", () => {
+		const log = [
+			"feat: a thing",
+			"",
+			"expansion_reason: needed shared type",
+			"",
+			"fix: another thing",
+			"",
+			"expansion_reason: had to update barrel export",
+		].join("\n");
+		const result = parseExpansionReasonsFromGitLog(log);
+		expect(result).toEqual(["needed shared type", "had to update barrel export"]);
+	});
+
+	test("trims whitespace around values", () => {
+		const log = "expansion_reason:    surrounded by spaces   \n";
+		const result = parseExpansionReasonsFromGitLog(log);
+		expect(result).toEqual(["surrounded by spaces"]);
+	});
+
+	test("ignores commits without the marker", () => {
+		const log = "feat: regular commit\n\nfix: another\n";
+		expect(parseExpansionReasonsFromGitLog(log)).toEqual([]);
+	});
+
+	test("empty log returns empty array", () => {
+		expect(parseExpansionReasonsFromGitLog("")).toEqual([]);
+	});
+
+	test("case-insensitive match", () => {
+		const log = "Expansion_Reason: capitalized variant\n";
+		expect(parseExpansionReasonsFromGitLog(log)).toEqual(["capitalized variant"]);
+	});
+});
+
+describe("detectScopeViolation", () => {
+	test("returns expected violations and expansion reasons via stub", () => {
+		const stub = (args: string[]): string => {
+			if (args[0] === "diff") return "src/foo.ts\nsrc/other.ts\n";
+			if (args[0] === "log") return "feat: change\n\nexpansion_reason: cross-cutting\n";
+			return "";
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: ["src/foo.ts"],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual(["src/other.ts"]);
+		expect(result.expansionReasons).toEqual(["cross-cutting"]);
+	});
+
+	test("returns empty when stub throws", () => {
+		const stub = (): string => {
+			throw new Error("boom");
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: ["src/foo.ts"],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual([]);
+		expect(result.expansionReasons).toEqual([]);
+	});
+
+	test("empty fileScope yields no violations regardless of diff", () => {
+		const stub = (args: string[]): string => {
+			if (args[0] === "diff") return "src/anything.ts\n";
+			return "";
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: [],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual([]);
+	});
+
+	test("blank diff lines are filtered", () => {
+		const stub = (args: string[]): string => {
+			if (args[0] === "diff") return "\nsrc/foo.ts\n\n\nsrc/bar.ts\n";
+			return "";
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: ["src/foo.ts"],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual(["src/bar.ts"]);
+	});
+});
+
+describe("IMPLEMENTATION_CAPABILITIES", () => {
+	test("includes builder and merger", () => {
+		expect(IMPLEMENTATION_CAPABILITIES.has("builder")).toBe(true);
+		expect(IMPLEMENTATION_CAPABILITIES.has("merger")).toBe(true);
+	});
+
+	test("excludes read-only roles", () => {
+		expect(IMPLEMENTATION_CAPABILITIES.has("scout")).toBe(false);
+		expect(IMPLEMENTATION_CAPABILITIES.has("reviewer")).toBe(false);
+		expect(IMPLEMENTATION_CAPABILITIES.has("lead")).toBe(false);
+	});
+});

package/src/agents/scope-detect.ts

@@ -0,0 +1,146 @@
+/**
+ * Scope-violation detection for builder/merger turns (overstory-9f4d).
+ *
+ * Surfaces a soft, advisory signal when an agent's modified files exceed its
+ * declared FILE_SCOPE without an `expansion_reason:` justification. The
+ * turn-runner consumes this on terminal-mail observation; the lead reads the
+ * `events.db` record during merge verification.
+ *
+ * This is observability only — never a hard block. All errors are swallowed.
+ */
+
+/**
+ * Capabilities allowed to modify files. Mirrors the set in
+ * `src/agents/hooks-deployer.ts`. Read-only roles (scout, reviewer) do not
+ * commit work, so scope detection is a no-op for them. Lead is excluded for
+ * the same reason — leads delegate, they don't touch files directly.
+ */
+export const IMPLEMENTATION_CAPABILITIES: ReadonlySet<string> = new Set(["builder", "merger"]);
+
+/**
+ * Synchronous git runner contract. Accepts argv (without the `git` prefix) and
+ * a working directory; returns combined stdout. Tests inject a stub; production
+ * calls `Bun.spawnSync(["git", ...args], { cwd })`.
+ */
+export type GitRunner = (args: string[], cwd: string) => string;
+
+const defaultGitRunner: GitRunner = (args, cwd) => {
+	const proc = Bun.spawnSync(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+	if (proc.exitCode !== 0) {
+		return "";
+	}
+	return proc.stdout.toString();
+};
+
+/**
+ * Return the subset of `modifiedFiles` not covered by any FILE_SCOPE entry.
+ *
+ * - Empty `fileScope` is treated as unrestricted: returns `[]`.
+ * - A file is in scope when any scope entry matches it literally OR when
+ *   `new Bun.Glob(entry).match(file)` returns true.
+ */
+export function findScopeViolations(modifiedFiles: string[], fileScope: string[]): string[] {
+	if (fileScope.length === 0) return [];
+
+	const globs: Array<{ entry: string; glob: Bun.Glob }> = [];
+	for (const entry of fileScope) {
+		try {
+			globs.push({ entry, glob: new Bun.Glob(entry) });
+		} catch {
+			// malformed glob — fall back to literal-only match for this entry
+			globs.push({ entry, glob: new Bun.Glob(entry.replace(/[*?[\]{}]/g, "\\$&")) });
+		}
+	}
+
+	const violations: string[] = [];
+	for (const file of modifiedFiles) {
+		let matched = false;
+		for (const { entry, glob } of globs) {
+			if (entry === file) {
+				matched = true;
+				break;
+			}
+			try {
+				if (glob.match(file)) {
+					matched = true;
+					break;
+				}
+			} catch {
+				// ignore malformed pattern; continue
+			}
+		}
+		if (!matched) violations.push(file);
+	}
+	return violations;
+}
+
+/**
+ * Case-insensitive check for `expansion_reason:` followed by at least one
+ * non-whitespace character before the next newline.
+ *
+ * - Matches `expansion_reason: foo`, `Expansion_Reason: bar`, `EXPANSION_REASON: baz quux`.
+ * - Rejects `expansion_reason:` (empty value) and `expansion-reason: foo` (different separator).
+ */
+export function hasExpansionReason(message: string): boolean {
+	return /expansion_reason:[^\S\n]*\S+/i.test(message);
+}
+
+/**
+ * Parse `expansion_reason:` values from the output of `git log --format=%B <range>`.
+ * Returns each value (trimmed) in encounter order. Commits without the marker
+ * are ignored.
+ */
+export function parseExpansionReasonsFromGitLog(log: string): string[] {
+	const reasons: string[] = [];
+	const re = /expansion_reason:[^\S\n]*([^\n]*\S)/gi;
+	let m: RegExpExecArray | null = re.exec(log);
+	while (m !== null) {
+		const value = m[1]?.trim();
+		if (value && value.length > 0) reasons.push(value);
+		m = re.exec(log);
+	}
+	return reasons;
+}
+
+export interface DetectScopeViolationOpts {
+	worktreePath: string;
+	baseRef: string;
+	fileScope: string[];
+	/** Test injection — replaces `Bun.spawnSync` for git calls. */
+	gitRunner?: GitRunner;
+}
+
+export interface ScopeViolationResult {
+	violations: string[];
+	expansionReasons: string[];
+}
+
+/**
+ * Detect scope violations for a worktree at HEAD relative to `baseRef`.
+ *
+ * - Runs `git diff --name-only baseRef...HEAD` to enumerate modified files.
+ * - Runs `git log --format=%B baseRef..HEAD` and parses `expansion_reason:`
+ *   markers from commit bodies.
+ *
+ * Always returns. Any failure (git error, parse failure) yields
+ * `{ violations: [], expansionReasons: [] }` — this is an advisory signal and
+ * must never break the runner.
+ */
+export function detectScopeViolation(opts: DetectScopeViolationOpts): ScopeViolationResult {
+	const runner = opts.gitRunner ?? defaultGitRunner;
+	try {
+		const diffOut = runner(["diff", "--name-only", `${opts.baseRef}...HEAD`], opts.worktreePath);
+		const modifiedFiles = diffOut
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line.length > 0);
+
+		const logOut = runner(["log", "--format=%B", `${opts.baseRef}..HEAD`], opts.worktreePath);
+		const expansionReasons = parseExpansionReasonsFromGitLog(logOut);
+
+		const violations = findScopeViolations(modifiedFiles, opts.fileScope);
+		return { violations, expansionReasons };
+	} catch {
+		return { violations: [], expansionReasons: [] };
+	}
+}