canary-test-cli 7.1.0 → 8.0.0

package/agents/skills/claude-code/canary-blackhawk/scripts/cli.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// canary-blackhawk -- temporal-dependency linter for test files.
+//
+// Statically flags tests that depend on wall-clock time, a real delay, or the
+// local timezone: the ones that pass all day and fail at midnight, across a DST
+// boundary, or on Feb 29.
+//
+//   <paths>    files or directories to scan (default: the current directory).
+//   --json     emit machine-readable findings instead of human text.
+//   --strict   exit 1 when there are findings (default is advisory: exit 0).
+//
+// Tier-0 deterministic analysis -- no LLM, no network, no secrets, no
+// dependency on any other skill.
+//
+// Invoked via `canary skills run canary-blackhawk -- [paths] [--json] [--strict]`.
+
+import fs from 'node:fs';
+import { scanPaths, toJson } from './scanner.mjs';
+import { RULES } from './rules.mjs';
+import {
+  createParser,
+  formatUsageError,
+  EXIT_USAGE,
+} from '../../../lib/parse-args.mjs';
+
+export const SCHEMA_VERSION = 1;
+
+const PREFIX = 'canary-blackhawk:';
+
+// --- no-silent-abstention (#508 D2, skill-CLI convention half) ---------------
+//
+// Skill CLIs are deliberately self-contained -- no engine import, no shared
+// module -- so they cannot call `gateOutcome`. They honour the doctrine by
+// CONVENTION instead, emitting the same greppable line the engine helper does.
+// The skill-layer conformance registry (agents/skills/test/gate-conformance.
+// test.ts) is what holds them to it: a row whose fixture collapses the
+// denominator and asserts the loud outcome.
+//
+// U+26A0 / U+2014 are written as escapes so this source stays ASCII, matching
+// ts/src/core/gate-result.ts.
+const ABSTAINED_LINE =
+  '\u{26A0} Abstained \u{2014} verified zero items; this is not a pass.';
+
+// The rules block is GENERATED from RULES, never hand-typed: a new rule shows
+// up in --help the moment it is registered, so the help text cannot drift
+// behind the linter as rules are added.
+const USAGE =
+  'usage: canary-blackhawk [-h] [--json] [--strict] [--] [path ...]\n' +
+  '\n' +
+  'Temporal-dependency linter for test files: flags tests that depend on the\n' +
+  'wall clock, a real delay, or the local timezone.\n' +
+  '\n' +
+  'positional arguments:\n' +
+  '  path        files or directories to scan (default: the current directory)\n' +
+  '\n' +
+  'options:\n' +
+  '  -h, --help  show this help message and exit\n' +
+  '  --json      emit machine-readable findings instead of human text\n' +
+  '  --strict    exit 1 when there are findings (default is advisory: exit 0)\n' +
+  '\n' +
+  'rules:\n' +
+  RULES.map((r) => `  ${r.ruleId} (${r.severity})`).join('\n');
+
+function summary(result) {
+  const bySeverity = {};
+  for (const f of result.findings) {
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+  }
+  return {
+    files_scanned: result.filesScanned,
+    findings: result.findings.length,
+    by_severity: bySeverity,
+    suppressed: result.suppressed ?? 0,
+  };
+}
+
+// A trailing "N suppressed" note keeps inline-ignored lines visible but out of
+// the actionable total - the pattern the PR-guardian sticky comment uses.
+function suppressedNote(result) {
+  const n = result.suppressed ?? 0;
+  return n ? `\n${n} suppressed (inline blackhawk-ignore).` : '';
+}
+
+function renderText(result) {
+  const count = result.findings.length;
+  const files = result.filesScanned;
+  const fp = files === 1 ? '' : 's';
+  // #508: zero findings over zero scanned files is an ABSENT result, not a
+  // clean one. Findings outrank abstention (a finding proves a file was read),
+  // so this is checked only on the no-findings path.
+  if (!count && !files) {
+    return (
+      `${ABSTAINED_LINE} No file matched the given paths, so there is ` +
+      'nothing to report. Point at a directory that holds test files, or ' +
+      'pass a file directly.'
+    );
+  }
+  if (!count) {
+    return (
+      `No temporal-dependency findings (${files} file${fp} scanned).` +
+      suppressedNote(result)
+    );
+  }
+  const sp = count === 1 ? '' : 's';
+  const lines = [
+    `${count} temporal-dependency finding${sp} in ${files} file${fp}:`,
+    '',
+  ];
+  for (const f of result.findings) {
+    lines.push(`  ${f.file}:${f.line}  [${f.severity}] ${f.ruleId}`);
+    lines.push(`      ${f.snippet}`);
+    lines.push(`      why: ${f.why}`);
+  }
+  lines.push('');
+  lines.push(
+    'Advisory by default. Re-run with --strict to fail the step on findings.',
+  );
+  return lines.join('\n') + suppressedNote(result);
+}
+
+/**
+ * blackhawk takes paths, so it gets the `--` end-of-options terminator (a file
+ * literally named `--json` stays reachable) and treats a lone `-` as a
+ * positional, as argparse does. The four shared invariants live in the shared
+ * parser (#479).
+ */
+export const CLI_SPEC = {
+  prog: 'canary-blackhawk',
+  booleans: { '--json': 'json', '--strict': 'strict' },
+  positionals: { key: 'paths', defaults: ['.'] },
+};
+
+const parseArgs = createParser(CLI_SPEC);
+
+export function main(argv = []) {
+  const { positionals: paths, opts, help, error } = parseArgs(argv);
+
+  // Usage and parse errors resolve before any filesystem work, so `--help`
+  // never reports a missing path and a typo never half-runs a scan.
+  if (help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (error) {
+    console.error(formatUsageError(CLI_SPEC.prog, error));
+    return EXIT_USAGE;
+  }
+
+  for (const entry of paths) {
+    if (!fs.existsSync(entry)) {
+      console.error(`${PREFIX} path not found: ${entry}`);
+      return 1;
+    }
+  }
+
+  const result = scanPaths(paths);
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          schema_version: SCHEMA_VERSION,
+          findings: result.findings.map(toJson),
+          summary: summary(result),
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log(renderText(result));
+  }
+
+  // Advisory by default (D3). Under --strict the CLI carries an exit-code
+  // contract, so a collapsed denominator inherits EXIT_ABSTAINED (3) -- distinct
+  // from 1 ("found something real"), so CI can tell them apart.
+  if (opts.strict && !result.filesScanned) return 3;
+  return opts.strict && result.findings.length ? 1 : 0;
+}
+
+// Direct execution (the skill runner execs this file via its shebang).
+//
+// `process.exitCode`, not `process.exit()`: a large `--json` payload exceeds
+// the pipe buffer, and `process.exit` tears the process down mid-write, leaving
+// truncated JSON that still exits 0 (#791).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/agents/skills/claude-code/canary-blackhawk/scripts/rules.mjs

@@ -0,0 +1,120 @@
+// Temporal-dependency rule catalog (pure data + compiled patterns).
+//
+// Each rule is a line-level pattern plus the reason it matters. The catalog is
+// deliberately small and language-agnostic: the same scan runs over Python and
+// JS/TS because the idioms do not collide (`new Date()` never appears in Python,
+// `time.time()` never in TypeScript).
+//
+// Rules whose `clockDependent` flag is set are suppressed when the file already
+// installs a frozen clock (see scanner.frozenClockMarkers). Timezone rules are
+// not, because freezing the clock pins *when* a test runs, never *where*.
+//
+// JS has no verbose-regex flag, so patterns are compact literals documented by
+// the comment above them.
+
+export const SEVERITIES = ['high', 'medium', 'low'];
+
+// Frozen-clock idioms. Their presence anywhere in a file suppresses every
+// clock-dependent rule in that file -- the single most important behaviour in
+// this skill, because a naive universal wall-clock rule false-positives on
+// exactly the tests that already handle time correctly.
+export const FROZEN_CLOCK_MARKERS = [
+  'vi.useFakeTimers',
+  'vi.setSystemTime',
+  'jest.useFakeTimers',
+  'jest.setSystemTime',
+  'sinon.useFakeTimers',
+  'MockDate',
+  'freeze_time',
+  'freezegun',
+  'time_machine',
+];
+
+// Tokens that make a datetime expression explicitly timezone-aware.
+const TZ_TOKENS = [
+  'tzinfo',
+  'timezone.utc',
+  'pytz',
+  'tz=',
+  'ZoneInfo',
+  'astimezone',
+];
+
+// JS Date.now() | bare new Date() | moment() | PY datetime.now/today/utcnow() |
+// date.today() | time.time() | pd.Timestamp.now()
+const WALL_CLOCK =
+  /\bDate\.now\s*\(|\bnew\s+Date\s*\(\s*\)|\bmoment\s*\(\s*\)|\bdatetime\.(?:now|today|utcnow)\s*\(|\bdate\.today\s*\(|\btime\.time\s*\(|\bTimestamp\.now\s*\(/;
+
+// PY time.sleep(n) | JS setTimeout(fn, n) with a literal numeric delay.
+const REAL_DELAY =
+  /\btime\.sleep\s*\(\s*(?<delay>[0-9][0-9_]*(?:\.[0-9]+)?)\s*\)|\bsetTimeout\s*\([^,]*,\s*(?<delay2>[0-9][0-9_]*(?:\.[0-9]+)?)\s*[,)]/;
+
+// JS locale formatting | PY strftime with %z / %Z.
+const LOCAL_TZ =
+  /\.toLocale(?:String|DateString|TimeString)\s*\(|strftime\s*\(\s*[frbu]*['"][^'"]*%[zZ]/;
+
+// A comparison against datetime(YYYY, ...) or strptime(...) on either side.
+const NAIVE_COMPARE =
+  /(?:==|!=|<=|>=|<|>)\s*(?:\w+\.)*datetime\s*\(\s*\d{4}|(?:\w+\.)*datetime\s*\(\s*\d{4}[^)]*\)\s*(?:==|!=|<=|>=|<|>)|(?:==|!=|<=|>=|<|>)\s*(?:\w+\.)*strptime\s*\(|(?:\w+\.)*strptime\s*\([^)]*\)\s*(?:==|!=|<=|>=|<|>)/;
+
+/** BH002 guard: keep only when the literal delay is > 0. */
+function delayIsPositive(match) {
+  const raw = match.groups?.delay ?? match.groups?.delay2;
+  const n = Number.parseFloat(String(raw).replace(/_/g, ''));
+  return Number.isFinite(n) && n > 0;
+}
+
+/** BH004 guard: keep only when the compared datetime carries no timezone token. */
+function naiveDatetime(match) {
+  const line = match.input ?? '';
+  return !TZ_TOKENS.some((token) => line.includes(token));
+}
+
+/**
+ * @typedef {{ruleId: string, severity: string, why: string, pattern: RegExp,
+ *            clockDependent: boolean, keep: ((m: RegExpExecArray) => boolean)|null}} Rule
+ */
+
+/** @type {Rule[]} */
+export const RULES = [
+  {
+    ruleId: 'BH001-wall-clock',
+    severity: 'high',
+    why:
+      'reads the wall clock, so the assertion depends on when the suite runs ' +
+      '(midnight, a DST shift, or Feb 29 changes the answer)',
+    pattern: WALL_CLOCK,
+    clockDependent: true,
+    keep: null,
+  },
+  {
+    ruleId: 'BH002-real-delay',
+    severity: 'medium',
+    why:
+      'burns a real delay, so the test is slow by construction and races the ' +
+      'scheduler on a loaded CI runner',
+    pattern: REAL_DELAY,
+    clockDependent: true,
+    keep: delayIsPositive,
+  },
+  {
+    ruleId: 'BH003-local-timezone',
+    severity: 'medium',
+    why:
+      "formats against the machine's local timezone, so the expected string " +
+      'differs between a developer laptop and a UTC CI runner',
+    pattern: LOCAL_TZ,
+    clockDependent: false,
+    keep: null,
+  },
+  {
+    ruleId: 'BH004-naive-datetime-compare',
+    severity: 'low',
+    why:
+      'compares a timezone-naive datetime, so the result shifts with the host ' +
+      'offset and breaks across a DST boundary',
+    pattern: NAIVE_COMPARE,
+    clockDependent: true,
+    keep: naiveDatetime,
+  },
+];

package/agents/skills/claude-code/canary-blackhawk/scripts/scanner.mjs

@@ -0,0 +1,244 @@
+// Line scanner: turns test sources into temporal-dependency findings (pure).
+//
+// Regex/AST-lite by design -- no parser dependency, standard library only -- so
+// it ships wherever node does. See SKILL.md for the fidelity limits that buys.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { FROZEN_CLOCK_MARKERS, RULES } from './rules.mjs';
+import { stringLiteralRanges, execOutsideStrings } from './string-literals.mjs';
+
+export const SNIPPET_LIMIT = 120;
+
+const SUPPORTED_SUFFIXES = [
+  '.py',
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.cjs',
+];
+
+const SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  '__pycache__',
+  '.venv',
+  'venv',
+  'dist',
+  'build',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.tox',
+  // Fixture directories are test DATA: files here never RUN as tests, so a
+  // temporal/order smell in one is a property of the data, not a defect (#493
+  // one level up). Also keeps pragmas out of golden-pinned fixture files.
+  'fixtures',
+  '__fixtures__',
+  '__mocks__',
+  'testdata',
+]);
+
+const TEST_DIRS = new Set(['tests', 'test', '__tests__', 'e2e', 'spec']);
+
+const COMMENT_PREFIXES = ['#', '//', '*', '/*', '"""', "'''"];
+
+const splitLines = (text) => text.split(/\r\n|\r|\n/);
+const isComment = (stripped) =>
+  COMMENT_PREFIXES.some((p) => stripped.startsWith(p));
+const partsOf = (p) => p.split(/[\\/]/).filter(Boolean);
+
+/**
+ * Return the frozen-clock idioms present in `text`, in catalog order. A
+ * non-empty result suppresses every clock-dependent rule for the whole file --
+ * file-wide (not block-scoped) on purpose: a scope-accurate answer needs a real
+ * parser, and blackhawk errs toward silence.
+ */
+export function frozenClockMarkers(text) {
+  return FROZEN_CLOCK_MARKERS.filter((marker) => text.includes(marker));
+}
+
+/** True when a path looks like a test file by name or containing directory. */
+function isTestFile(filePath) {
+  const suffix = path.extname(filePath);
+  if (!SUPPORTED_SUFFIXES.includes(suffix)) return false;
+  const name = path.basename(filePath);
+  const stem = name.slice(0, name.length - suffix.length);
+  if (name.includes('.test.') || name.includes('.spec.')) return true;
+  if (stem.startsWith('test_') || stem.endsWith('_test')) return true;
+  return partsOf(filePath)
+    .slice(0, -1)
+    .some((part) => TEST_DIRS.has(part));
+}
+
+/** Convert an internal finding to its JSON-contract shape (snake_case id). */
+export function toJson(f) {
+  return {
+    file: f.file,
+    line: f.line,
+    rule_id: f.ruleId,
+    severity: f.severity,
+    snippet: f.snippet,
+    why: f.why,
+  };
+}
+
+// Inline suppression pragma (#393): `blackhawk-ignore <RULE>[,<RULE>] -- reason`
+// in a comment. Rule-scoped (so it never blanket-silences a line) and the reason
+// is required (keeps suppressions honest and greppable). A pragma covers the
+// finding on its own line (trailing comment) and the next line (comment above
+// the code) - the two idioms teams reach for.
+const PRAGMA = /\bblackhawk-ignore\s+([A-Za-z0-9,\s-]*?)\s*--\s*(\S.*)$/;
+
+function parsePragmas(lines) {
+  const map = new Map();
+  const add = (ln, tokens) => {
+    if (!map.has(ln)) map.set(ln, new Set());
+    for (const t of tokens) map.get(ln).add(t);
+  };
+  lines.forEach((raw, i) => {
+    // #499: a pragma is a DIRECTIVE, so it only counts as code. Matching the
+    // raw line let a `blackhawk-ignore` inside a string literal register as
+    // live -- data acting as directive, with a fabricated "reason" entering the
+    // suppressed count. This suite necessarily carries pragma text inside
+    // fixture strings, so the self-scan was the thing at risk. Savant shipped
+    // this guard in #498; blackhawk never got it ported back.
+    const m = execOutsideStrings(PRAGMA, raw, stringLiteralRanges(raw));
+    if (!m || !m[2].trim()) return; // reason required
+    const tokens = m[1].split(/[,\s]+/).filter(Boolean);
+    if (!tokens.length) return; // rule-scoped: must name a rule
+    add(i + 1, tokens); // same-line (trailing pragma)
+    add(i + 2, tokens); // next line (pragma above the code)
+  });
+  return map;
+}
+
+// A `BH002` token matches `BH002-real-delay`; the full id also matches.
+const tokenMatches = (ruleId, token) =>
+  ruleId === token || ruleId.split('-')[0] === token;
+
+/**
+ * @typedef {{file: string, line: number, ruleId: string, severity: string,
+ *            snippet: string, why: string}} Finding
+ */
+
+/**
+ * Scan source text. Returns kept `findings` plus `suppressed` findings silenced
+ * by an inline pragma, both ordered by line then rule id.
+ * @returns {{findings: Finding[], suppressed: Finding[]}}
+ */
+export function scanTextFull(text, file = '<text>') {
+  const lines = splitLines(text);
+  const frozen = frozenClockMarkers(text).length > 0;
+  const pragmas = parsePragmas(lines);
+  const findings = [];
+  const suppressed = [];
+  lines.forEach((raw, i) => {
+    const stripped = raw.trim();
+    if (!stripped || isComment(stripped)) return;
+    // #493: a match starting inside a string literal is fixture data, not
+    // code. Computed once per line; every rule's anchor token is code, even
+    // when the pattern's tail reaches into quotes (BH003's strftime('..%Z')).
+    const ranges = stringLiteralRanges(stripped);
+    for (const rule of RULES) {
+      if (frozen && rule.clockDependent) continue;
+      const match = execOutsideStrings(rule.pattern, stripped, ranges);
+      if (!match) continue;
+      if (rule.keep && !rule.keep(match)) continue;
+      const finding = {
+        file,
+        line: i + 1,
+        ruleId: rule.ruleId,
+        severity: rule.severity,
+        snippet: stripped.slice(0, SNIPPET_LIMIT),
+        why: rule.why,
+      };
+      const tokens = pragmas.get(i + 1);
+      if (tokens && [...tokens].some((t) => tokenMatches(rule.ruleId, t))) {
+        suppressed.push(finding);
+      } else {
+        findings.push(finding);
+      }
+    }
+  });
+  return { findings, suppressed };
+}
+
+/** Scan source text, returning kept findings (back-compat wrapper). */
+export function scanText(text, file = '<text>') {
+  return scanTextFull(text, file).findings;
+}
+
+/** Scan one file. Unreadable files yield nothing. */
+function scanFileFull(filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { findings: [], suppressed: [] };
+  }
+  return scanTextFull(text, filePath);
+}
+
+/** Yield the files a path contributes: explicit files win, dirs are filtered. */
+function* iterFiles(root) {
+  let stat;
+  try {
+    stat = fs.statSync(root);
+  } catch {
+    return;
+  }
+  if (stat.isFile()) {
+    if (SUPPORTED_SUFFIXES.includes(path.extname(root))) yield root;
+    return;
+  }
+  const collected = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) collected.push(full);
+    }
+  };
+  walk(root);
+  collected.sort();
+  for (const f of collected) {
+    if (partsOf(f).some((part) => SKIP_DIRS.has(part))) continue;
+    if (isTestFile(f)) yield f;
+  }
+}
+
+/** Scan every given file/directory, de-duplicating overlapping paths. */
+export function scanPaths(paths) {
+  const seen = new Set();
+  const findings = [];
+  let scanned = 0;
+  let suppressed = 0;
+  for (const entry of paths) {
+    for (const filePath of iterFiles(entry)) {
+      const resolved = path.resolve(filePath);
+      if (seen.has(resolved)) continue;
+      seen.add(resolved);
+      scanned += 1;
+      const r = scanFileFull(filePath);
+      findings.push(...r.findings);
+      suppressed += r.suppressed.length;
+    }
+  }
+  findings.sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) ||
+      a.line - b.line ||
+      a.ruleId.localeCompare(b.ruleId),
+  );
+  return { findings, filesScanned: scanned, suppressed };
+}

package/agents/skills/claude-code/canary-blackhawk/scripts/string-literals.mjs

@@ -0,0 +1,116 @@
+// String-literal ranges for a single source line (pure, stdlib-only). #493.
+//
+// Both canary-blackhawk and canary-savant regex over raw lines, so without
+// this they flag their own test fixtures: `pyFile('time.sleep(1)')` is data,
+// not a call. The correction is deliberately narrow -- a match is rejected
+// only when its START index falls inside a string literal. Stripping string
+// contents before matching would be wrong: blackhawk's BH003 pattern matches
+// `strftime('..%Z')` with the `%Z` inside the quotes ON PURPOSE; the anchor
+// token (`strftime`, `time.sleep`, `Date.now`, ...) is what separates code
+// from data.
+//
+// This file is intentionally duplicated verbatim in canary-blackhawk and
+// canary-savant: skills are self-contained by contract (their packaging
+// suites forbid cross-imports), and #479 tracks extracting shared skill
+// infrastructure. A parity test pins the two copies byte-identical.
+//
+// Fidelity limits (line-based scanner, no parser):
+// - Handles '...', "...", and `...` template literals. `${...}` interpolation
+//   regions are CODE (a nested-frame scan, so `${`x`}` and `${fn({a:1})}`
+//   work); backslash escapes are respected; a quote of the other kind inside
+//   a string is content.
+// - An unterminated quote marks the REST OF THE LINE as string. That is the
+//   safe default for multi-line Python strings whose opener ends mid-line,
+//   and for apostrophes in trailing comments: this helper only ever REJECTS
+//   matches, so the worst case is a suppressed match inside what was really
+//   string-ish text -- never a new false positive.
+// - Strings spanning lines (template literals, triple quotes) are only seen
+//   on their opening line; continuation lines look like code. Accepted: the
+//   scanners are line-based by design.
+// - Regex literals containing quotes (/['"]/) can open a phantom string for
+//   the rest of the line. Same rejection-only safety argument applies.
+
+/**
+ * Compute the [start, end) index ranges of string-literal CONTENT in `line`
+ * (quote characters excluded; empty literals contribute no range).
+ * @param {string} line
+ * @returns {Array<[number, number]>}
+ */
+export function stringLiteralRanges(line) {
+  /** @type {Array<[number, number]>} */
+  const ranges = [];
+  // Frames: {quote, start} while inside a string; {interp: true, depth}
+  // while inside a template's ${...} (which is code and may nest strings).
+  const stack = [];
+  const top = () => stack[stack.length - 1];
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    const frame = top();
+    if (frame && frame.quote) {
+      if (ch === '\\') {
+        i += 1; // escaped char is content, never a closer
+      } else if (ch === frame.quote) {
+        ranges.push([frame.start, i]);
+        stack.pop();
+      } else if (frame.quote === '`' && ch === '$' && line[i + 1] === '{') {
+        // Interpolation is code: close the string segment before `${`.
+        ranges.push([frame.start, i]);
+        stack.push({ interp: true, depth: 0 });
+        i += 1;
+      }
+      continue;
+    }
+    // Code context: top-level, or inside `${ ... }`.
+    if (ch === "'" || ch === '"' || ch === '`') {
+      stack.push({ quote: ch, start: i + 1 });
+    } else if (frame && frame.interp) {
+      if (ch === '{') {
+        frame.depth += 1;
+      } else if (ch === '}') {
+        if (frame.depth === 0) {
+          stack.pop();
+          top().start = i + 1; // the enclosing template resumes here
+        } else {
+          frame.depth -= 1;
+        }
+      }
+    }
+  }
+  // Unterminated string: treat the rest of the line as string (see header).
+  // An open interpolation frame is code and stays unmarked.
+  const frame = top();
+  if (frame && frame.quote) ranges.push([frame.start, line.length]);
+  return ranges.filter(([start, end]) => end > start);
+}
+
+/**
+ * True when `index` falls inside any of the given content ranges.
+ * @param {Array<[number, number]>} ranges
+ * @param {number} index
+ * @returns {boolean}
+ */
+export function inStringLiteral(ranges, index) {
+  return ranges.some(([start, end]) => index >= start && index < end);
+}
+
+/**
+ * Like `pattern.exec(line)`, but skips matches whose start index falls
+ * inside a string literal, returning the first CODE match (or null).
+ * @param {RegExp} pattern
+ * @param {string} line
+ * @param {Array<[number, number]>} ranges precomputed for `line`
+ * @returns {RegExpExecArray | null}
+ */
+export function execOutsideStrings(pattern, line, ranges) {
+  if (ranges.length === 0) return pattern.exec(line);
+  const flags = pattern.flags.includes('g')
+    ? pattern.flags
+    : `${pattern.flags}g`;
+  const re = new RegExp(pattern.source, flags);
+  let match;
+  while ((match = re.exec(line)) !== null) {
+    if (!inStringLiteral(ranges, match.index)) return match;
+    if (re.lastIndex === match.index) re.lastIndex += 1; // zero-width guard
+  }
+  return null;
+}