Compare commits

...

2 Commits

Author SHA1 Message Date
diegosouzapw
d7fb19ffa8 docs(changelog): add fragment for #20938 2026-11-21 10:46:17 -03:00
diegosouzapw
354f4b9461 fix(db): run the migration-numbering gate in the pre-commit hook when a migration is staged
The gate only ran in CI, so a hand-numbered or badly named migration was caught
minutes after the push. The hook now lists the staged paths under
src/lib/db/migrations/ and, only when there is one, runs
scripts/check/check-migration-numbering.mjs (names, duplicates and the frozen
001-241 series; the comparison with the base stays in CI). It runs before
lint-staged, aborts the commit if git cannot list the staged files, and blanks
GITHUB_EVENT_NAME / MIGRATION_BASE_REF so a CI-like environment never turns the
local run into a base comparison.

Tests: the hook test now mocks git, pins the step's placement and gating, and
runs the real hook text with real git and the real gate in a throwaway
repository (bad name fails with the gate's message, good name passes, no
migration staged never runs the gate).

Closes #20578
2026-11-21 10:40:27 -03:00
5 changed files with 191 additions and 8 deletions

View File

@@ -9,6 +9,12 @@ fi
# Cheap, deterministic local gates (re-enabled). Slower checks (i18n drift,
# openapi coverage/security-tiers, env-doc sync) run in CI to keep commits fast.
sh scripts/check/check-git-identity.sh
# Migration names (#20578): only when the commit touches src/lib/db/migrations/. The
# assignment aborts the hook if git fails. Names only; the comparison with the base stays in CI.
staged_migrations=$(git diff --cached --name-only --diff-filter=ACMRD -- src/lib/db/migrations/)
if [ -n "$staged_migrations" ]; then
GITHUB_EVENT_NAME= MIGRATION_BASE_REF= node scripts/check/check-migration-numbering.mjs
fi
# The stash is shared by every worktree. Never let a local hook stash another
# session's changes, and never download a missing tool during a commit.
npx --no-install lint-staged --no-stash

View File

@@ -0,0 +1 @@
- **fix(db):** the pre-commit hook now runs `check:migration-numbering` when the commit stages a file under `src/lib/db/migrations/`, so a hand-numbered or badly named migration fails locally with the same message CI prints (names only; the comparison with the base stays in CI); commits without migrations skip it ([#20938](https://github.com/cheaper-inference/OmniRoute/pull/20938))

View File

@@ -165,7 +165,7 @@ Runs on every PR to `main`. Blocks merge on failure.
| `check:vitest-exclusions` | Every Vitest exclusion names a tracking issue and appears in `config/quality/vitest-exclusions.json` (#13204) | Yes |
| `check:file-size` | Source files (`.ts`/`.tsx` in `src/`, `open-sse/`, `electron/`, `bin/`) stay within `cap` and test files (`*.test.ts(x)`) within `testCap`; files frozen in `file-size-baseline.json` (`frozen` / `testFrozen`) must not grow past their recorded size | Yes |
| `check:error-helper` | Error responses in executors/handlers use `buildErrorBody()` / `sanitizeErrorMessage()` (Hard Rule #12) | Yes |
| `check:migration-numbering` | Migration file names: the old `001`–`241` series is frozen and new files are `YYYYMMDDHHMMSS_<description>.sql`. Against the PR base it rejects a removed migration, a renamed one without a compatibility entry, and an out-of-order or edited one whose final schema does not commute |
| `check:migration-numbering` | Migration file names: the old `001`–`241` series is frozen and new files are `YYYYMMDDHHMMSS_<description>.sql`. Against the PR base it rejects a removed migration, a renamed one without a compatibility entry, and an out-of-order or edited one whose final schema does not commute. Also runs in the husky pre-commit hook when the commit stages a file under `src/lib/db/migrations/` (names, duplicates and the frozen series only; the comparison with the base stays in CI — #20578) |
| `check:public-creds` | No literal OAuth `client_id`/`client_secret` or Firebase Web keys outside `publicCreds.ts` (Hard Rule #11) | Yes |
| `check:db-rules` | No raw SQL outside `src/lib/db/` modules; no barrel-imports from `localDb.ts` (Hard Rules #2/#5) | Yes |
| `check:known-symbols` | Provider executors, routing strategies, and translators registered in their dispatch tables match the files on disk — no orphaned or undeclared symbols | Yes |

View File

@@ -309,7 +309,7 @@ Use `IF NOT EXISTS`, `IF EXISTS`, and `OR IGNORE` / `OR REPLACE` clauses liberal
1. **Create the file with the generator**: `npm run db:new-migration -- <description>` (for example `npm run db:new-migration -- add combo priority`). It writes `src/lib/db/migrations/<YYYYMMDDHHMMSS>_<description>.sql` with the current UTC time and a comment header, moves forward one second if that timestamp is taken, and never overwrites a file. Do not pick a number by hand.
2. **Use safe DDL**: `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, `ALTER TABLE ... ADD COLUMN`
3. **Backfill data carefully**: use `UPDATE ... WHERE ...` to handle existing rows
4. **Check order and naming**: `npm run test:migrations:fresh` (all migrations on an empty database) and `npm run check:migration-numbering`
4. **Check order and naming**: `npm run test:migrations:fresh` (all migrations on an empty database) and `npm run check:migration-numbering`. The husky pre-commit hook runs `check:migration-numbering` on its own when the commit stages a file under `src/lib/db/migrations/`, so a hand-picked or badly formed name (for example `242_x.sql`) fails the commit locally with the same message CI prints. The hook checks names, duplicates and the frozen `001`–`241` series only; the comparison with the PR base (removed, renamed or out-of-order migrations) still runs in CI
5. **Test on a copy**: never run untested migrations on production
6. **A table created from code needs a migration too**: if a module also creates the table lazily (`CREATE TABLE IF NOT EXISTS`, kept as a self-heal path), a migration must create it with the same DDL. Otherwise a clean install and an upgraded install end up with different schemas, depending on whether that code path ran. `tests/unit/db/lazy-table-migration-guard.test.ts` scans `src/` and `open-sse/` and fails on a lazy `CREATE` without a migration (#20557). Example: `src/lib/db/migrations/20261118120853_compression_run_telemetry.sql`.

View File

@@ -1,23 +1,56 @@
import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { spawnSync } from "node:child_process";
const hook = readFileSync(new URL("../../../.husky/pre-commit", import.meta.url), "utf8");
const repoRoot = fileURLToPath(new URL("../../../", import.meta.url));
const hook = readFileSync(join(repoRoot, ".husky/pre-commit"), "utf8");
function runHook(extra: Record<string, string> = {}) {
const MIGRATION_GATE = "scripts/check/check-migration-numbering.mjs";
const STAGED_MIGRATIONS_CMD =
"git diff --cached --name-only --diff-filter=ACMRD -- src/lib/db/migrations/";
function runHook(extra: Record<string, string> = {}, cwd = repoRoot) {
// Execute the checked-in hook. Only the external tools are fixtures; no real
// stash, index mutation or dependency installation is permitted by the probe.
// MOCK_REAL_GIT=1 / MOCK_REAL_MIGRATION_GATE=1 let the end-to-end cases run the
// real git and the real migration gate inside a throwaway repository.
const tools = `
command() { if [ "$1 $2" = "-v npx" ] && [ "$MOCK_NPX_MISSING" = "1" ]; then return 1; fi; builtin command "$@"; }
npx() { printf 'NPX:%s\\n' "$*"; return "$MOCK_LINT_EXIT"; }
node() { printf 'NODE:%s\\n' "$*"; }
git() {
if [ "$MOCK_REAL_GIT" = "1" ]; then builtin command git "$@"; return; fi
printf 'GIT:%s\\n' "$*" >&2; printf '%s' "$MOCK_STAGED_MIGRATIONS"; return "$MOCK_GIT_EXIT"
}
node() {
if [ "$1" = "${MIGRATION_GATE}" ]; then
printf 'GATE:%s event=[%s] base=[%s]\\n' "$*" "\${GITHUB_EVENT_NAME-unset}" "\${MIGRATION_BASE_REF-unset}"
if [ "$MOCK_REAL_MIGRATION_GATE" = "1" ]; then "$REAL_NODE" "$@"; return; fi
return "$MOCK_MIGRATION_GATE_EXIT"
fi
printf 'NODE:%s\\n' "$*"
}
npm() { printf 'NPM:%s\\n' "$*"; }
sh() { printf 'SH:%s\\n' "$*"; }
`;
return spawnSync("bash", ["-c", `${tools}\n${hook}`], {
cwd,
encoding: "utf8",
env: { ...process.env, MOCK_NPX_MISSING: "0", MOCK_LINT_EXIT: "0", ...extra },
env: {
...process.env,
MOCK_NPX_MISSING: "0",
MOCK_LINT_EXIT: "0",
MOCK_REAL_GIT: "0",
MOCK_STAGED_MIGRATIONS: "",
MOCK_GIT_EXIT: "0",
MOCK_REAL_MIGRATION_GATE: "0",
MOCK_MIGRATION_GATE_EXIT: "0",
REAL_NODE: process.execPath,
...extra,
},
});
}
@@ -31,7 +64,7 @@ test("hook never stashes and never downloads a missing lint-staged", () => {
test("missing npx blocks the commit instead of silently skipping all checks", () => {
const result = runHook({ MOCK_NPX_MISSING: "1" });
assert.notEqual(result.status, 0);
assert.doesNotMatch(result.stdout, /NODE:|NPM:/);
assert.doesNotMatch(result.stdout, /NODE:|NPM:|GATE:/);
});
test("failed lint-staged preserves its exit even when the hook is executed directly", () => {
@@ -39,3 +72,146 @@ test("failed lint-staged preserves its exit even when the hook is executed direc
assert.equal(result.status, 42);
assert.doesNotMatch(result.stdout, /NODE:|NPM:/);
});
// #20578 — the migration-numbering gate runs locally, but only when the commit touches
// src/lib/db/migrations/, and before the slow steps.
test("hook wires the migration gate on staged migrations, before lint-staged", () => {
const listAt = hook.indexOf(STAGED_MIGRATIONS_CMD);
const gateAt = hook.indexOf(`node ${MIGRATION_GATE}`);
const lintStagedAt = hook.indexOf("npx --no-install lint-staged");
assert.ok(listAt > 0, "the hook lists the staged migrations");
assert.ok(gateAt > listAt, "the hook runs the migration gate after listing them");
assert.ok(gateAt < lintStagedAt, "the migration gate runs before lint-staged");
// lint-staged appends file names, which parseGateArgs rejects: never route it there.
const { "lint-staged": lintStaged } = JSON.parse(
readFileSync(join(repoRoot, "package.json"), "utf8")
);
assert.doesNotMatch(JSON.stringify(lintStaged), /check-migration-numbering/);
});
test("a commit without staged migrations never runs the migration gate", () => {
const result = runHook();
assert.equal(result.status, 0, result.stderr);
assert.match(result.stderr, new RegExp(`GIT:${STAGED_MIGRATIONS_CMD.slice(4)}`));
assert.doesNotMatch(result.stdout, /GATE:/);
});
test("a staged migration runs the gate (names only) before lint-staged", () => {
const result = runHook({ MOCK_STAGED_MIGRATIONS: "src/lib/db/migrations/242_x.sql\n" });
assert.equal(result.status, 0, result.stderr);
const gateLine = result.stdout.indexOf(`GATE:${MIGRATION_GATE} event=[] base=[]`);
assert.ok(gateLine >= 0, result.stdout);
assert.ok(gateLine < result.stdout.indexOf("NPX:--no-install lint-staged"), result.stdout);
});
test("a failing migration gate blocks the commit before lint-staged", () => {
const result = runHook({
MOCK_STAGED_MIGRATIONS: "src/lib/db/migrations/242_x.sql\n",
MOCK_MIGRATION_GATE_EXIT: "1",
});
assert.equal(result.status, 1);
assert.match(result.stdout, /GATE:/);
assert.doesNotMatch(result.stdout, /NPX:|NODE:|NPM:/);
});
test("a failing staged-file listing blocks the commit instead of skipping the gate", () => {
const result = runHook({ MOCK_GIT_EXIT: "128" });
assert.notEqual(result.status, 0);
assert.doesNotMatch(result.stdout, /NPX:|NODE:|NPM:|GATE:/);
});
// End to end: the real hook text, real git and the real gate, in a throwaway repository in
// the OS temp dir with a copy of the gate and of the migrations directory.
function makeScratchRepo() {
const root = mkdtempSync(join(tmpdir(), "pre-commit-migration-gate-"));
for (const rel of [
MIGRATION_GATE,
"scripts/check/lib/allowlist.mjs",
"scripts/check/lib/migrationBaseDiff.mjs",
"scripts/check/lib/migrationNaming.mjs",
]) {
mkdirSync(dirname(join(root, rel)), { recursive: true });
cpSync(join(repoRoot, rel), join(root, rel));
}
cpSync(join(repoRoot, "src/lib/db/migrations"), join(root, "src/lib/db/migrations"), {
recursive: true,
});
writeFileSync(join(root, "README.md"), "scratch\n");
const git = (...args: string[]) => {
const r = spawnSync("git", args, { cwd: root, encoding: "utf8" });
assert.equal(r.status, 0, `git ${args.join(" ")}: ${r.stderr}`);
};
git("init", "-q");
git("add", "-A");
git(
"-c",
"user.name=scratch",
"-c",
"user.email=scratch@example.invalid",
"-c",
"commit.gpgsign=false",
"commit",
"-q",
"-m",
"base"
);
const stage = (rel: string, content: string) => {
writeFileSync(join(root, rel), content);
git("add", "--", rel);
};
return { root, stage };
}
function runHookEndToEnd(root: string) {
// A CI-like environment must not turn the local run into a base comparison.
return runHook(
{
MOCK_REAL_GIT: "1",
MOCK_REAL_MIGRATION_GATE: "1",
GITHUB_EVENT_NAME: "pull_request",
MIGRATION_BASE_REF: "refs/heads/does-not-exist",
},
root
);
}
test("end to end: a hand-numbered migration fails the commit with the gate's message", () => {
const { root, stage } = makeScratchRepo();
try {
stage("src/lib/db/migrations/242_x.sql", "SELECT 1;\n");
const result = runHookEndToEnd(root);
assert.equal(result.status, 1, result.stdout + result.stderr);
assert.match(result.stderr, /nome inválido: 242_x\.sql/);
assert.match(result.stderr, /npm run db:new-migration -- <descricao>/);
assert.doesNotMatch(result.stdout, /NPX:/);
} finally {
rmSync(root, { recursive: true, force: true });
}
});
test("end to end: a correctly named migration passes the gate", () => {
const { root, stage } = makeScratchRepo();
try {
stage("src/lib/db/migrations/20261120000000_scratch_probe.sql", "SELECT 1;\n");
const result = runHookEndToEnd(root);
assert.equal(result.status, 0, result.stdout + result.stderr);
assert.match(result.stdout, /\[check-migration-numbering\] comparação com a base: pulada/);
assert.match(result.stdout, /\[check-migration-numbering\] OK/);
assert.match(result.stdout, /NPX:--no-install lint-staged --no-stash/);
} finally {
rmSync(root, { recursive: true, force: true });
}
});
test("end to end: a commit without migrations does not run the gate", () => {
const { root, stage } = makeScratchRepo();
try {
stage("README.md", "changed\n");
const result = runHookEndToEnd(root);
assert.equal(result.status, 0, result.stdout + result.stderr);
assert.doesNotMatch(result.stdout + result.stderr, /GATE:|check-migration-numbering/);
assert.match(result.stdout, /NPX:--no-install lint-staged --no-stash/);
} finally {
rmSync(root, { recursive: true, force: true });
}
});