Skip to content

A full-featured CRM built with React, shadcn/ui, and Supabase.

feat(harness): add eslint step scoped to the ticket diff

Jerome17f52b32fd7b
diff --git a/.claude/hooks/bash-guard.mjs b/.claude/hooks/bash-guard.mjs
index f11b9f5b..b93de10a 100755
--- a/.claude/hooks/bash-guard.mjs
+++ b/.claude/hooks/bash-guard.mjs
@@ -131,7 +131,7 @@ const CATEGORY_RULES = {
],
lint: [
runsLint,
- "lint: prettier is auto-applied by the validation hooks; eslint runs via the project's editor config. Skip it.",
+ "lint: validate-on-stop.mjs runs eslint on your changed files automatically after you stop; read its stderr output instead.",
],
build: [
runsBuild,
@@ -141,13 +141,14 @@ const CATEGORY_RULES = {
// Which categories to guard comes from the SAME config the validation chain runs
// (kills the triple-encoding: runner, guard, and doc no longer drift). Each
-// validation step's kind maps to a category, plus validation.extraForbidden
-// (lint/build — never run during tickets, not part of the chain). Fail-open to
-// ALL categories if the config can't be read, so a malformed config never
-// weakens the guard.
+// validation step's kind maps to a category (lint included — it is now a chain
+// step), plus validation.extraForbidden (build — never run during tickets, not
+// part of the chain). Fail-open to ALL categories if the config can't be read,
+// so a malformed config never weakens the guard.
const KIND_TO_CATEGORY = {
format: "prettier",
typecheck: "typecheck",
+ lint: "lint",
unit: "unit",
e2e: "e2e",
};
diff --git a/.claude/hooks/lib/config.mjs b/.claude/hooks/lib/config.mjs
index 2a10c336..9fec0980 100644
--- a/.claude/hooks/lib/config.mjs
+++ b/.claude/hooks/lib/config.mjs
@@ -141,5 +141,10 @@ export const launcher = (cfg) => cfg.launcher ?? {};
export const formatStep = (cfg) =>
validationSteps(cfg).find((s) => s.kind === "format") ?? null;
// Steps a pre-PR / pre-push gate runs on the human path (fast checks only).
+// `changedScoped` steps are EXCLUDED: they need a per-worktree diff base (the
+// session branch) that the human push path lacks, and running their bare command
+// whole-repo would lint/test far more than the change at hand.
export const prePrSteps = (cfg) =>
- validationSteps(cfg).filter((s) => s.kind === "typecheck" || s.kind === "lint");
+ validationSteps(cfg).filter(
+ (s) => (s.kind === "typecheck" || s.kind === "lint") && !s.changedScoped,
+ );
diff --git a/.claude/hooks/lib/validation.mjs b/.claude/hooks/lib/validation.mjs
index 33e84bf3..f200b6cc 100644
--- a/.claude/hooks/lib/validation.mjs
+++ b/.claude/hooks/lib/validation.mjs
@@ -87,8 +87,37 @@ function runVitest(wt, configFile, projects = [], changedSince = "") {
return { status: r.status, output, timedOut: r.status === 124 };
}
+// Files this worktree changed that lint should check: the config `extensions`,
+// restricted to paths that still exist on disk. A deleted / renamed-away file
+// must not be handed to eslint (it would error "No files matching"). Pure —
+// unit-tested independently of the shell-out.
+export function scopedLintFiles(changedFiles, cwd, extensions) {
+ return changedFiles.filter(
+ (f) => extensions.some((e) => f.endsWith(e)) && existsSync(join(cwd, f)),
+ );
+}
+
+// Run eslint on ONLY this worktree's diff since `base` (the session branch it
+// forked from), mirroring the vitest `--changed` scoping: a ticket is judged on
+// its own changed files, never the whole repo — which also sidesteps pre-existing
+// lint noise in unrelated / generated files. Zero matching files -> nothing to
+// lint (ok). `base` empty -> repo base branch, matching getWorktreesToValidate.
+// `command` is the eslint invocation prefix (e.g. `npx eslint`); files are
+// appended here, so the config command must NOT carry its own file glob.
+function runEslintScoped(cwd, base, command, extensions, tail) {
+ const { changedFiles } = getWorktreeChangeSummary(cwd, base || getBaseBranch());
+ const files = scopedLintFiles(changedFiles, cwd, extensions);
+ if (files.length === 0) return { ok: true };
+ const out = join(tmpdir(), `eslint-${process.pid}.out`);
+ const args = files.map((f) => `'${f.replace(/'/g, `'\\''`)}'`).join(" ");
+ const r = bash(`${command} ${args} > "${out}" 2>&1`, { cwd });
+ const output = tailFile(out, tail);
+ tryUnlink(out);
+ return r.status === 0 ? { ok: true } : { ok: false, output };
+}
+
// Per-kind tail length for failure output (mechanical, not a project fact).
-const TAIL_LINES = { format: 15, typecheck: 20, unit: 40, e2e: 50 };
+const TAIL_LINES = { format: 15, typecheck: 20, lint: 30, unit: 40, e2e: 50 };
// A step is skipped when its `condition` is not met. `pathExists` gates on a
// path under the repo (e.g. the supabase/functions unit-fn gate); `modeNot`
@@ -119,6 +148,11 @@ function runStep(ctx, step, { cwd, base }) {
return r.status === 0 ? { ok: true } : { ok: false, output: r.output };
}
+ if (step.kind === "lint" && step.changedScoped) {
+ const exts = step.extensions ?? [".ts", ".tsx", ".mjs"];
+ return runEslintScoped(cwd, base, step.command, exts, tail);
+ }
+
const r = bash(`${step.command} 2>&1`, { cwd });
if (r.status === 0) {
if (step.kind === "format" && step.autoCommit) {
diff --git a/.claude/hooks/test/bash-guard.test.mjs b/.claude/hooks/test/bash-guard.test.mjs
index 6f87399b..c0c0b074 100644
--- a/.claude/hooks/test/bash-guard.test.mjs
+++ b/.claude/hooks/test/bash-guard.test.mjs
@@ -157,6 +157,25 @@ describe("bash-guard hook", () => {
expect(isBlocked(r)).toBe(false);
});
+ test("a lint step in the chain blocks manual lint (no extraForbidden)", () => {
+ const withLintStep = {
+ validation: {
+ steps: [
+ {
+ id: "lint",
+ kind: "lint",
+ command: "npx eslint",
+ changedScoped: true,
+ },
+ ],
+ extraForbidden: [],
+ },
+ roles: { developer: { model: "sonnet" } },
+ };
+ const r = runHookWithConfig("developer", "npm run lint", withLintStep);
+ expect(isBlocked(r)).toBe(true);
+ });
+
test("extraForbidden build is blocked when listed", () => {
const withBuild = {
validation: { steps: [], extraForbidden: ["build"] },
diff --git a/.claude/hooks/test/config.test.mjs b/.claude/hooks/test/config.test.mjs
index 87e2ef36..a7a07a46 100644
--- a/.claude/hooks/test/config.test.mjs
+++ b/.claude/hooks/test/config.test.mjs
@@ -17,6 +17,7 @@ import {
debounceRoles,
roleModel,
worktreeProvision,
+ prePrSteps,
} from "../lib/config.mjs";
const REPO_ROOT = join(
@@ -119,6 +120,32 @@ describe("config loader", () => {
).toThrow(/deploy\.relevantGlobs/);
});
+ test("prePrSteps takes typecheck/lint but excludes changedScoped steps", () => {
+ const cfg = loadConfig(
+ makeRepo({
+ validation: {
+ steps: [
+ {
+ id: "typecheck",
+ kind: "typecheck",
+ command: "npm run typecheck",
+ },
+ {
+ id: "lint",
+ kind: "lint",
+ command: "npx eslint",
+ changedScoped: true,
+ },
+ ],
+ },
+ roles: {},
+ }),
+ );
+ // typecheck (whole-repo-safe) is on the human push path; the diff-scoped lint
+ // step is not — it needs a per-worktree base the human path lacks.
+ expect(prePrSteps(cfg).map((s) => s.id)).toEqual(["typecheck"]);
+ });
+
test("the committed harness.config.json is valid", () => {
clearConfigCache();
const cfg = loadConfig(REPO_ROOT);
diff --git a/.claude/hooks/test/validation.test.mjs b/.claude/hooks/test/validation.test.mjs
new file mode 100644
index 00000000..8d7e309f
--- /dev/null
+++ b/.claude/hooks/test/validation.test.mjs
@@ -0,0 +1,53 @@
+// Tests for lib/validation.mjs: scopedLintFiles — the pure file-selection the
+// lint step feeds to eslint (extension filter + must-still-exist-on-disk).
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, test, expect } from "vitest";
+import { scopedLintFiles } from "../lib/validation.mjs";
+
+const EXT = [".ts", ".tsx", ".mjs"];
+
+const tmpDirs = [];
+const makeCwd = (files) => {
+ const dir = mkdtempSync(join(tmpdir(), "scoped-lint-"));
+ tmpDirs.push(dir);
+ for (const f of files) writeFileSync(join(dir, f), "");
+ return dir;
+};
+
+afterEach(() => {
+ while (tmpDirs.length)
+ rmSync(tmpDirs.pop(), { recursive: true, force: true });
+});
+
+describe("scopedLintFiles", () => {
+ test("keeps only lintable extensions", () => {
+ const cwd = makeCwd(["a.ts", "b.tsx", "c.mjs", "d.css", "e.sql", "f.md"]);
+ expect(
+ scopedLintFiles(
+ ["a.ts", "b.tsx", "c.mjs", "d.css", "e.sql", "f.md"],
+ cwd,
+ EXT,
+ ),
+ ).toEqual(["a.ts", "b.tsx", "c.mjs"]);
+ });
+
+ test("drops paths that no longer exist (deleted / renamed away)", () => {
+ const cwd = makeCwd(["kept.ts"]);
+ expect(scopedLintFiles(["kept.ts", "gone.ts"], cwd, EXT)).toEqual([
+ "kept.ts",
+ ]);
+ });
+
+ test("empty change set → empty list (nothing to lint)", () => {
+ const cwd = makeCwd([]);
+ expect(scopedLintFiles([], cwd, EXT)).toEqual([]);
+ });
+
+ test("a diff of only non-code files → empty list", () => {
+ const cwd = makeCwd(["schema.sql", "notes.md"]);
+ expect(scopedLintFiles(["schema.sql", "notes.md"], cwd, EXT)).toEqual([]);
+ });
+});
diff --git a/.claude/rules/validation-commands.md b/.claude/rules/validation-commands.md
index 8f122417..dd67e38e 100644
--- a/.claude/rules/validation-commands.md
+++ b/.claude/rules/validation-commands.md
@@ -10,12 +10,13 @@ guard, so they can never drift:
- `validate-on-stop.mjs` (SubagentStop) runs the whole chain after every
developer / test-writer stop: the format step (prettier auto-fix + commit),
- typecheck, the unit steps, then e2e once in the repo (full mode only). A failed
- step rejects the stop; the agent's internal loop fixes it and only a green stop
- returns control to the orchestrator.
+ typecheck, lint (eslint, scoped to the stop's changed files), the unit steps,
+ then e2e once in the repo (full mode only). A failed step rejects the stop; the
+ agent's internal loop fixes it and only a green stop returns control to the
+ orchestrator.
- `bash-guard.mjs` (PreToolUse Bash) blocks `developer` / `quality-reviewer` from
- running those same commands manually, plus `validation.extraForbidden` (lint,
- build). The forbidden set is DERIVED from `validation.steps`, not hardcoded here.
+ running those same commands manually, plus `validation.extraForbidden` (build).
+ The forbidden set is DERIVED from `validation.steps`, not hardcoded here.
## Why blocked (developer / quality-reviewer)
diff --git a/.claude/settings.json b/.claude/settings.json
index c02b3819..4923ba4a 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -222,7 +222,7 @@
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-on-stop.mjs",
"timeout": 900,
- "statusMessage": "Running validation (prettier, typecheck, unit, e2e)..."
+ "statusMessage": "Running validation (prettier, typecheck, lint, unit, e2e)..."
}
]
},
diff --git a/harness.config.json b/harness.config.json
index a5626467..95692790 100644
--- a/harness.config.json
+++ b/harness.config.json
@@ -20,6 +20,13 @@
"kind": "typecheck",
"command": "npm run typecheck"
},
+ {
+ "id": "lint",
+ "kind": "lint",
+ "command": "npx eslint",
+ "changedScoped": true,
+ "extensions": [".ts", ".tsx", ".mjs"]
+ },
{
"id": "unit-app",
"kind": "unit",
@@ -45,7 +52,7 @@
"condition": { "modeNot": "demo" }
}
],
- "extraForbidden": ["lint", "build"]
+ "extraForbidden": ["build"]
},
"worktree": {
"provision": "npm-link"