Promote intArrayLiteral to @wxyc/database and lint the bare-array-in-ANY() trap unwritable

[jakebromberg]

The rule found a live seventh instance on main

Running the finished rule across the tree (npm run lint) surfaced exactly one hit: jobs/va-apple-music-url-remediation/orchestrate.ts:378 — ANY(${albumIds}) with albumIds: number[] imported from drizzle-orm. That is a real, currently-shipped instance of this exact defect, in a job that has already run against production data (album_metadata: {"candidates":206,"invalidated":0,"batches":1} on the 2026-08-06 09:33 PDT run). It's already ticketed as #2007 — found by reviewing that production failure, not by anything preventive — and is being fixed by the open, not-yet-merged PR #2008. No human review caught it before #2007; this rule would have. That gap is the strongest argument for this ticket, so it belongs here rather than in a status update.

I did not touch that job's logic (out of scope, and PR #2008 fixes it differently — a VALUES-join UPDATE that removes the array bind entirely, not a call to intArrayLiteral). See "Suppressing the one known instance" below for how the rule still ships clean.

Summary

• Promote intArrayLiteral (already exported from jobs/artist-unicode-dedup/merge.ts) to shared/database/src/int-array-literal.ts, hardened to validate every element via Number + Number.isInteger and throw on a non-integer input instead of splicing raw text. Update all six call sites (jobs/artist-unicode-dedup/merge.ts, jobs/flowsheet-ghost-row-sweep/orchestrate.ts, jobs/flowsheet-metadata-backfill/orchestrate.ts, jobs/legacy-dj-name-remediation/job.ts, jobs/album-critic-reviews-etl/antijoin.ts, shared/database/src/library-tiebreak.ts) to import it — no behavior change at any call site.
• Add wxyc/no-bare-array-in-sql-template (eslint-rules/), wired into eslint.config.mjs for apps/**, shared/**, jobs/**, tests/**. It resolves a tagged template's sql identifier through scope analysis to a named import from 'drizzle-orm' — never postgres-js — then flags any interpolation whose statically-known type is an array.
• Document the trap + the fix in docs/bulk-update-playbook.md.

Why type-aware, not AST-only

The issue allowed a narrower AST-only fallback ("does ${} sit textually inside ANY(...)") if type information proved impractical. I built that version first and rejected it: it cannot distinguish the fixed shape (ANY(${idArrayLiteral}::int[]), idArrayLiteral: string) from the historical bug (ANY(${ids}), ids: number[]) — both are syntactically ${Identifier} immediately after ANY(. Shipping the position-only version would have flagged every one of the six call sites this PR just fixed, at the exact moment they became correct. Type information isn't an optional enhancement to fall back away from here, either — this repo's eslint.config.mjs already requires it project-wide (tseslint.configs.recommendedTypeChecked + parserOptions.projectService: true), so the rule uses ESLintUtils.getParserServices + @typescript-eslint/type-utils's isTypeArrayTypeOrUnionOfArrayTypes and fires on any array-typed interpolation in a confirmed Drizzle sql template — not just the ones inside ANY(...), the broader "ideally any ${}" form the issue asked for.

Proof the rule works

tests/unit/database/no-bare-array-in-sql-template.rule.test.ts — an eslint.RuleTester suite (following source-tagged-constraint.rule.test.ts's existing pattern) running through @typescript-eslint/parser with projectService.allowDefaultProject so a virtual, not-on-disk fixture still gets real type information. 5 valid + 7 invalid cases, including the load-bearing negative case: the identical ANY(${array}) syntax under a postgres-js-shaped tag (a local variable, not a drizzle-orm import) is asserted NOT to fire.

I also verified end-to-end against the real eslint.config.mjs, not just the RuleTester harness: a temporary fixture mirroring library-tiebreak.ts's pre-fix shape failed lint with the rule's message; the fixed shape passed clean. (Fixture was written, linted, then deleted — not part of this diff.)

Running the rule across the existing tree, comparing npm run lint on this branch against a clean origin/main checkout with the identical invocation: baseline is 835 problems / 0 errors / 835 warnings; this branch is also 835 problems / 0 errors / 835 warnings after the suppression below. Everything else in the tree is clean — the only place the rule ever fires outside its own test fixtures is the one already-ticketed line.

Suppressing the one known instance

A rule that fails on the tree it lands into isn't shippable, and this issue's own acceptance criterion says so directly: "Running the rule across the existing tree surfaces zero unfixed instances." I considered --no-verify and waiting for #2008 to merge first, and rejected both — --no-verify just relocates the same failure to CI (which will enforce this the moment GitHub Actions recovers from today's major_outage), and #2008 is blocked on that exact outage with no ETA, so waiting could stall this PR indefinitely. The failure has to be resolved inside this PR.

jobs/va-apple-music-url-remediation/orchestrate.ts now carries a targeted suppression around invalidateAlbumBatch's one sql statement:

/* eslint-disable wxyc/no-bare-array-in-sql-template */
const updateSql = sql`
  ...
  WHERE "album_id" = ANY(${albumIds})
  ...
`;
/* eslint-enable wxyc/no-bare-array-in-sql-template */

A single // eslint-disable-next-line wasn't usable here: the violation (${albumIds}) sits inside a multi-line sql template literal, so a comment on the preceding source line would land inside the template literal's string content — i.e. become part of the SQL text sent to Postgres — rather than function as a JS comment. (I tried this first and caught it immediately: it round-trips as a harmless SQL comment, but it isn't a working ESLint directive, and it isn't something you'd want in a query string.) The disable/re-enable pair brackets exactly this one statement, immediately outside the template literal on both sides — not a file-level /* eslint-disable */, and it exempts nothing else in the job.

This repo's flat config default-reports unused disable directives at warn (linterOptions.reportUnusedDisableDirectives isn't set, and ESLint 9+'s flat-config default for that option is "warn" — confirmed empirically, not from memory, by linting a throwaway fixture with a directive that suppressed nothing). So once PR #2008 lands and rewrites this statement to a VALUES-join UPDATE that removes the array bind entirely, this pair becomes a live "unused eslint-disable directive" warning — a built-in cleanup nudge for whoever rebases it, not a silent, permanent carve-out. I did not add a suppression for the // eslint-disable-next-line form's exact wording the issue's reviewer originally suggested, because it isn't syntactically usable at this call site; said so in-line at the suppression site too.

Two touched files outside the six call sites — why, and a live overlap with PR #2012

tests/mocks/database.mock.ts: one pure re-export line, export { intArrayLiteral } from '../../shared/database/src/int-array-literal.js';, added in the same style as the existing foldArtistName/requirePositiveInt re-exports right above it. @wxyc/database is fully mapped to this mock in unit tests, so without this line every one of the six call sites' unit tests would fail with intArrayLiteral is not a function. This is orthogonal to the mock's .where()/.limit() query-builder sharp edge (createMockQueryChain, db.execute) — I didn't touch that, and I didn't touch tests/__mocks__/drizzle-orm.ts at all, which is the file that actually owns how an interpolated value gets serialized and is the reason a mocked-DB unit test couldn't have caught #2007 in the first place. This PR doesn't change that serialization behavior in any way; the new rule is a static, authoring-time check specifically because the runtime/mock path can't see this class of bug.

tests/integration/artist-unicode-dedup-merge.spec.js: necessary, not incidental — merge.ts no longer exports intArrayLiteral (moved to @wxyc/database), and this spec had a direct unit-style assertion against merge.intArrayLiteral. I updated it to import from @wxyc/database instead and kept an equivalent assertion (full behavioral coverage, including the validation this promotion adds, now lives in the new tests/unit/database/int-array-literal.test.ts).

This file is also touched by PR #2012 (chore/issue-2011, open), which adds a beforeAll pre-clean block to the same describe. I confirmed the two changes don't collide: my edits are at the top-level requires (a new const { intArrayLiteral } = require('@wxyc/database');) and in a test(...) block ~60 lines below the describe's beforeAll; #2012's edit is entirely inside that beforeAll's body. I verified this isn't just "looks non-adjacent" — git merge-tree --write-tree HEAD <2012-branch> (read-only preview, no working-tree changes) produced a clean merge with both changes present in the result, no conflict markers, exit 0. Whichever of us merges second will still get a clean auto-merge; flagging the overlap here so it isn't a surprise.

Test plan

• tests/unit/database/int-array-literal.test.ts — 10 cases (TDD: written and confirmed failing before the helper existed, then implementation, then green)
• tests/unit/database/no-bare-array-in-sql-template.rule.test.ts — 5 valid + 7 invalid RuleTester cases
• npm run lint — 835 problems, 0 errors, 835 warnings (byte-identical to a clean origin/main checkout run the same way)
• npm run typecheck — clean
• npx tsc --noEmit -p jobs/<name> for all 5 touched jobs/** packages — clean (va-apple-music-url-remediation still carries its pre-existing, unrelated TS2554 pair — tracked separately as va-apple-music-url-remediation: the cooperative live-DJ pause never pauses, and a probe throw kills the run's summary #2009, untouched by this PR's comment-only edit there)
• npm run format:check — clean
• npm run test:unit — 412 suites / 6519 tests passing

GitHub Actions is in a confirmed major_outage as of 2026-08-06 — this PR will show zero checks; none were triggered, re-run, or polled.

Closes #2010

[jakebromberg]

Review follow-ups pushed as 3ca95fef: the blocking text-array pointer fix (all three sites), the IN-splat claim restated as policy rather than fact, the four known gaps documented (including relabelling the namespace-import case, previously encoded as valid), Number.isSafeInteger, the integration spec's assertion now matching its comment, and the real coverage boundary stated in both eslint.config.mjs and the playbook.

Local checks after the revisions: lint 835 problems / 0 errors (identical warning count to clean origin/main), npm run typecheck clean, prettier --check clean, full unit suite 412 suites / 6520 tests passing.

Overlap: this PR conflicts with #2008

The description's overlap section verified #2012 with git merge-tree --write-tree (exit 0, re-confirmed — the merged file carries both this PR's require('@wxyc/database') and #2012's pre-clean, no conflict markers). #2008 was not checked, and it does conflict.

git merge-tree --write-tree against #2008 exits 1 with CONFLICT (content): jobs/va-apple-music-url-remediation/orchestrate.ts. #2008 rewrites invalidateAlbumBatch — the exact function this PR wraps in the suppression pair — to a sql.join VALUES form, so both edit the same ~25 lines.

Resolution is mechanical: take #2008's body, delete this PR's comment block and directive pair. #2008 removes the array bind entirely, so the suppression has nothing left to suppress. If a resolver keeps the pair by accident it degrades to a warning, not a break — reportUnusedDisableDirectives resolves to 'warn' in this flat config, confirmed empirically on eslint 10.8.0 by simulating exactly that rebase.

Noted on #2008 as well so whoever merges second isn't surprised.

One coupling for the future: linting the tree with this rule removed from the config turns those two directive comments into hard errors (Definition for rule … was not found), so any later delete or rename of the rule must delete the comments in the same change.