feat(gate): explain why a file was flagged

[veksen]

Goal

Make the untested-data-access gate explain itself, so a false positive can be judged from the PR comment instead of by cloning the analyzer.

The gate has taken six precision fixes in four weeks (Query-Doctor/Site#3531, #3550, #3615, #3650, plus two cases nobody filed). Every one was diagnosed the same way: check out the analyzer, write a throwaway script, replay the PR's changed-file list, print which pattern matched what text. The module had that information and discarded it before anyone could see it.

An audit of all 15 PRs the gate has ever fired on, across Site, Nutcracker, this repo and veksen-enterprises/d2armory, found 2 correct flags. One false positive is still open: apps/api/src/db/test-db.ts on Query-Doctor/Site#3530 and #3573.

What

Before, the PR comment listed paths:

• apps/api/src/db/test-db.ts

After, it names the cause:

• apps/api/src/db/test-db.ts — matched drizzle-init on line 2: drizzle(

That line is enough to see the flag is the testcontainers harness being read as production data access. It is the open false positive above, diagnosed without leaving the PR.

How

Read src/gate/test-presence.ts first, then the two rendering sites.

The 20 anonymous regexes in the content matcher become named rules: raw-select-from, drizzle-sql-tag, ddl-create-index, and so on. findQueryCode returns the first that matches, with the line and an excerpt. patchAddsQueryCode stays as the boolean form, defined in terms of it. Rule order is precedence, so a line matching both .execute( and the raw select shape reports the first, which names the cause better.

Line numbers required a change to the three strippers. They removed comment, import and block-comment text, which shifted every later line, so an offset into the stripped text pointed at the wrong place. They now replace that text with spaces and keep the newlines. This is the one behavioural risk in the change: blanking leaves whitespace where deletion closed the gap, and the raw select shape has a 300-character budget between select and from, so blanking is marginally more conservative. I checked that against the corpus below.

dataAccessFiles becomes {path, evidence} rather than strings. Evidence is absent when GitHub supplied no patch, which happens for large and binary files: the filename prior decides those alone, and the line renders as a bare path.

The check annotation in main.ts renders separately from the template rather than sharing a formatter. That predates this change and I left it alone.

Tests

Six new cases in src/gate/test-presence.test.ts, each written before its implementation and observed failing:

• rule name and line number for a match
• precedence when several rules match
• correct line number when comment and import lines precede the match, which is what the blanking change buys
• null when nothing matches
• the verdict carries evidence through to what a reader sees
• evidence omitted when the path prior decided it

Full suite 429/429. npm run typecheck clean.

Beyond the unit tests, I replayed 42 real PRs from Site, Nutcracker, this repo and d2armory through classifyChangedFiles. The set of files classified as data access is identical before and after, so the stripper change altered no outcome. I also rendered the comment for Site#3530 and #3573 through the reporter's own nunjucks config, with a patchless file appended so both branches of the new loop render.

[github-actions]

Query Doctor — 6 successful checks

 Cost regression — No query went up more than 5%
 Untested data access — No changed data-access file without a test
 New query — No new queries
 New query with index recommendation — No new query ships an index recommendation
 Schema drift — No schema changes
 High-value nudge — No index or rewrite past the threshold

---

_{More details via MCP → get_ci_run({ runId: "019fd2a1-cab4-7c41-aefd-a6fae4da71ff" }) · view run · docs
3 queries read against main on assumed statistics of 10,000,000 rows per table. Sync production stats for costs measured against your real data.}