canary-test-cli 7.0.0 → 7.2.0

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

@@ -0,0 +1,374 @@
+// Tier-1 static scanner: test sources -> shared-state suspect findings (pure).
+//
+// AST-lite by design -- no test execution, no parser dependency, standard
+// library only -- so it ships wherever node does and runs cheaply on every PR.
+// Two rules (SV001, SV002) need whole-file context, so the scan is two-pass: a
+// file-level pass for those, plus a line pass for the local rules (SV003,
+// SV004). See SKILL.md for the fidelity limits this buys.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  SEVERITY,
+  WHY,
+  SV004_CODE_PATTERN,
+  SV004_TEXT_PATTERN,
+  PYTHON_SETUP_TEARDOWN,
+  JS_SETUP_TEARDOWN,
+  PY_MODULE_MUTABLE,
+  JS_MODULE_MUTABLE,
+  mutationPattern,
+} from './rules.mjs';
+import {
+  analyzeRestoration,
+  classifyMutation,
+  isSnapshotWriteBack,
+} from './restoration.mjs';
+import {
+  stringLiteralRanges,
+  inStringLiteral,
+  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));
+
+/** @returns {string[]} the path's components, separator-agnostic. */
+const partsOf = (p) => p.split(/[\\/]/).filter(Boolean);
+
+/** 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;
+  const dirs = partsOf(filePath).slice(0, -1);
+  return dirs.some((part) => TEST_DIRS.has(part));
+}
+
+function makeFinding(file, line, ruleId, snippet) {
+  return {
+    file,
+    line,
+    ruleId,
+    severity: SEVERITY[ruleId],
+    snippet: snippet.slice(0, SNIPPET_LIMIT),
+    why: WHY[ruleId],
+  };
+}
+
+/** 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,
+  };
+}
+
+/** Module-level mutable declarations that some line later mutates in place. */
+function sv001ModuleMutables(lines, file, isPy, text) {
+  const declRe = isPy ? PY_MODULE_MUTABLE : JS_MODULE_MUTABLE;
+  const findings = [];
+  lines.forEach((raw, i) => {
+    // Module scope == column 0 (unindented). A mutable declared inside a
+    // function is local and cannot leak between tests.
+    if (/^\s/.test(raw)) return;
+    const match = declRe.exec(raw.trim());
+    if (!match) return;
+    const name = match[1];
+    if (mutationPattern(name).test(text)) {
+      findings.push(
+        makeFinding(file, i + 1, 'SV001-module-mutable-global', raw.trim()),
+      );
+    }
+  });
+  return findings;
+}
+
+// Line comment openers, for the code-only projection below. A whole-line
+// comment is caught earlier by isComment (which also covers block-comment
+// continuations and Python docstring fences).
+const COMMENT_OPENERS = ['//', '/*', '#'];
+
+/**
+ * The line with comments dropped and string-literal CONTENT blanked, so a
+ * token found in the result is code rather than prose or data.
+ *
+ * #732: SV002 asked `text.includes(teardown)` of the RAW file while its setup
+ * half already skipped comments, so any file that merely MENTIONED the
+ * teardown token exempted itself -- invisibly, because a finding that is never
+ * generated never appears in the `N suppressed` line either. Blanking rather
+ * than deleting preserves column positions for callers that keep ranges.
+ *
+ * Erring here means erring toward FIRING (a token wrongly read as prose costs
+ * a false flag, which restoration.mjs's header calls the safe direction),
+ * never toward the silent exemption this replaces.
+ */
+function codeOnly(line) {
+  if (isComment(line.trim())) return '';
+  const ranges = stringLiteralRanges(line);
+  let out = '';
+  for (let i = 0; i < line.length; i += 1) {
+    if (inStringLiteral(ranges, i)) {
+      out += ' ';
+      continue;
+    }
+    // Rest of the line is a trailing comment.
+    if (COMMENT_OPENERS.some((c) => line.startsWith(c, i))) break;
+    out += line[i];
+  }
+  return out;
+}
+
+/** Setup markers whose matching teardown is absent from the file. */
+function sv002MissingTeardown(lines, file, isPy) {
+  const pairs = isPy ? PYTHON_SETUP_TEARDOWN : JS_SETUP_TEARDOWN;
+  // #732: pair against code only. Both halves read the same projection, so
+  // the rule can no longer be switched off by a comment or a fixture string.
+  const codeLines = lines.map(codeOnly);
+  const codeText = codeLines.join('\n');
+  const findings = [];
+  for (const [setup, teardown] of pairs) {
+    if (codeText.includes(teardown)) continue;
+    for (let i = 0; i < lines.length; i += 1) {
+      const code = codeLines[i].trim();
+      if (!code) continue;
+      const hit = isPy
+        ? code.includes(`def ${setup}`)
+        : code.startsWith(`${setup}(`) || code.includes(` ${setup}(`);
+      if (hit) {
+        const stripped = lines[i].trim();
+        findings.push(
+          makeFinding(file, i + 1, 'SV002-missing-teardown', stripped),
+        );
+        break; // one finding per unmatched setup marker
+      }
+    }
+  }
+  return findings;
+}
+
+// Inline suppression pragma (#496): `savant-ignore <RULE>[,<RULE>] -- reason`
+// in a comment, matching canary-blackhawk's `blackhawk-ignore` (#393) so a
+// user moving between the two skills learns one dialect. 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. One deliberate divergence from blackhawk: the
+// anchor is string-literal guarded (#493 style), because savant's own suite
+// carries pragma text inside fixture strings and data must never act as a
+// directive.
+const PRAGMA = /\bsavant-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) => {
+    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;
+}
+
+// An `SV003` token matches `SV003-shared-singleton-mutation`; 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 isPy = file.endsWith('.py');
+  const lines = splitLines(text);
+  const findings = [];
+  // #493 root cause 2: SV003's why asserts persistence, so a file that
+  // restores the global (teardown restore or snapshot write-back) must not
+  // be flagged. Computed once per file.
+  const restoration = analyzeRestoration(text);
+
+  findings.push(...sv001ModuleMutables(lines, file, isPy, text));
+  findings.push(...sv002MissingTeardown(lines, file, isPy));
+
+  lines.forEach((raw, i) => {
+    const stripped = raw.trim();
+    if (!stripped) return;
+    // #493: a match starting inside a string literal is fixture data, not
+    // code. SV003 and SV004's code-anchored alternatives reject those; the
+    // SV004 text alternatives stay unfiltered because their signal (titles,
+    // docstrings, comments) legitimately lives inside strings.
+    const ranges = stringLiteralRanges(stripped);
+    // SV004 is self-reported ordering: it fires on comments and code alike.
+    if (
+      execOutsideStrings(SV004_CODE_PATTERN, stripped, ranges) ||
+      SV004_TEXT_PATTERN.test(stripped)
+    ) {
+      findings.push(
+        makeFinding(file, i + 1, 'SV004-order-coupled-name', stripped),
+      );
+    }
+    if (isComment(stripped)) return;
+    const mutation = classifyMutation(stripped, ranges);
+    if (mutation) {
+      const restored =
+        isSnapshotWriteBack(mutation, lines) ||
+        restoration.restores(mutation.family, mutation.key);
+      if (!restored) {
+        findings.push(
+          makeFinding(file, i + 1, 'SV003-shared-singleton-mutation', stripped),
+        );
+      }
+    }
+  });
+
+  findings.sort((a, b) => a.line - b.line || a.ruleId.localeCompare(b.ruleId));
+
+  // Partition after the sort (stable), so both arrays stay line-ordered.
+  const pragmas = parsePragmas(lines);
+  const kept = [];
+  const suppressed = [];
+  for (const f of findings) {
+    const tokens = pragmas.get(f.line);
+    if (tokens && [...tokens].some((t) => tokenMatches(f.ruleId, t))) {
+      suppressed.push(f);
+    } else {
+      kept.push(f);
+    }
+  }
+  return { findings: kept, 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) {
+      const full = path.join(dir, entry.name);
+      if (SKIP_DIRS.has(entry.name)) continue;
+      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-savant/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;
+}