canary-test-cli 7.0.0 → 7.1.0

package/dist/engine/core/vacuity-scanner.js

@@ -0,0 +1,556 @@
+/**
+ * canary-cassandra -- vacuous-test detection (#612).
+ *
+ * A vacuous test PASSES WITHOUT PROVING ANYTHING. It has assertions, it goes
+ * green, and it goes green identically against the bug it was written to catch,
+ * so every gate this repo owns reads it as healthy. Three shipped examples are
+ * recorded in #486 and all three cleared coverage, `review-test`, and CI:
+ *
+ * - an assertion whose expectation could not have been false (`toBe(true)`),
+ * - a test whose target was never actually invoked, and
+ * - a test whose only assertion was an ABSENCE, which the buggy code satisfied
+ *   by crashing before it could do anything.
+ *
+ * This module is one implementation, consumed by both the `canary vacuity-check`
+ * CLI and the promotion gate (`promotion-verdict.ts`, #477). It is deliberately
+ * NOT a self-contained `.mjs` skill: #605's accepted risk was that
+ * `static_linter` and `quality_scorer` already overlap and a third
+ * half-enforcer would be the real defect. `agents/skills/claude-code/
+ * canary-cassandra/SKILL.md` drives this CLI rather than carrying a second copy
+ * of the detection.
+ *
+ * ## The fidelity ladder, and why VAC-002 needs one
+ *
+ * A test's "declared target" is declared nowhere. Inferring it from imports is
+ * exactly the heuristic tier STRATEGY.md distrusts, and the issue predicts the
+ * failure precisely: a correct integration test gets flagged when the call sits
+ * several frames deeper. So:
+ *
+ * - `annotated` -- the author wrote `@covers <symbol>`. The rule checks THAT
+ *   symbol and says so.
+ * - `import-inferred` -- no annotation, so the target set is the symbols
+ *   imported from relative paths, closed over local declarations to a fixpoint
+ *   (one helper, or a chain of them, still counts as reaching the target).
+ * - neither -- the target cannot be resolved. That is "cannot verify", which is
+ *   a finding about the SCAN, so it lands in `skipped` with its reason.
+ *
+ * A skip is PER RULE, not per test: `VAC-001` needs no target and always runs,
+ * so a test whose target is unresolvable is still genuinely `checked` and stays
+ * in the denominator. Saying otherwise would understate what was verified. What
+ * must not happen is a reader mistaking that for a full pass, which is why
+ * `promotion-verdict.ts` puts the skip count in its remedy rather than letting
+ * `promote` read as unqualified.
+ *
+ * ## The denominator
+ *
+ * `scanVacuity` returns a {@link GateResult}, so a file it could not read
+ * reports `checked: 0` and `gateOutcome` structurally refuses to print a pass.
+ * A vacuity detector that could itself go quiet and look clean would be the
+ * joke telling itself.
+ */
+import { readFileSync } from 'node:fs';
+import { ASSERT_JS, ASSERT_PY, enumerateTests, frameworkForPath, } from './static-linter.js';
+import { blankStringContent } from './string-literals.js';
+/**
+ * `@covers <symbol>` -- the explicit rung of the ladder.
+ *
+ * Global, because {@link annotationFor} needs the LAST match in its window, not
+ * the first: `exec` returns the match nearest the start, which is the FARTHEST
+ * annotation above the declaration.
+ */
+const COVERS_PRAGMA = /@covers\s+([A-Za-z_$][\w$]*)/g;
+/** An import whose specifier is relative: the local code a test can target. */
+const JS_RELATIVE_IMPORT = /import\s+(?:type\s+)?(?:\{([^}]*)\}|(\w+))[^'"]*from\s*['"](\.[^'"]*)['"]/g;
+const JS_RELATIVE_REQUIRE = /(?:const|let|var)\s+(?:\{([^}]*)\}|(\w+))\s*=\s*require\s*\(\s*['"](\.[^'"]*)['"]/g;
+/**
+ * Python has no `.`-prefix requirement for a first-party import, so `from x
+ * import y` counts. `import os` and the stdlib are excluded by name below --
+ * a heuristic, but the alternative is treating every pytest file as
+ * unresolvable.
+ */
+const PY_FROM_IMPORT = /^[ \t]*from\s+([\w.]+)\s+import\s+(\([^)]*\)|[^\n#]+)/gm;
+const PY_STDLIB = new Set([
+    'os',
+    'sys',
+    'json',
+    're',
+    'time',
+    'math',
+    'pathlib',
+    'typing',
+    'datetime',
+    'unittest',
+    'pytest',
+    'collections',
+    'subprocess',
+    'tempfile',
+    'itertools',
+    'functools',
+    'socket',
+    'uuid',
+    'random',
+]);
+/**
+ * A local declaration whose body may reach the target set.
+ *
+ * Three shapes, and the third is not optional. Measured on canary's own suite,
+ * the largest single source of false positives was the testkit idiom
+ * `const { findings, write } = kitFor(dir)`: the imported target is `kitFor`,
+ * `findings()` reaches it, and a pattern that only understood `const x = ` saw
+ * none of it -- so every test in `doc-links.test.ts` read as touching nothing at
+ * all. An object pattern binds every name in it to the same reaching RHS.
+ */
+const JS_LOCAL_DECL = /(?:^|\n)\s*(?:export\s+)?(?:async\s+)?(?:function\s+(\w+)|(?:const|let|var)\s+(?:\{([^}]*)\}|\[([^\]]*)\]|(\w+))\s*=)/g;
+const PY_LOCAL_DECL = /(?:^|\n)\s*def\s+(\w+)\s*\(/g;
+/**
+ * A destructuring ASSIGNMENT with no declarator: `({ write, findings } =
+ * kitFor(root))`.
+ *
+ * The declare-then-assign-in-a-hook idiom -- `let findings: Kit['findings']` at
+ * module scope, bound inside `beforeEach`. `doc-links.test.ts` is written this
+ * way throughout, and because the binding line carries no `const`/`let`/`var`,
+ * a declaration-only pattern misses it and every test in the file reads as
+ * touching nothing at all.
+ */
+const JS_DESTRUCTURED_ASSIGN = /\(\s*\{([^}]*)\}\s*=\s*([^;\n]*)\)/g;
+/** Every identifier bound by one declaration match (a pattern binds several). */
+function boundNames(m, python) {
+    if (python)
+        return m[1] ? [m[1]] : [];
+    if (m[1])
+        return [m[1]];
+    if (m[4])
+        return [m[4]];
+    const pattern = m[2] ?? m[3] ?? '';
+    return pattern
+        .split(',')
+        .map((raw) => raw
+        .split(':')
+        .pop()
+        .trim()
+        .replace(/^\.\.\./, ''))
+        .filter((n) => /^[A-Za-z_$][\w$]*$/.test(n));
+}
+/**
+ * Assertions whose expectation is an ABSENCE. A test built only from these
+ * passes identically when the code under test never ran at all -- the
+ * `canary-katana` case from #486, where a bare tmpdir exited before the write
+ * and `expect(existsSync(...)).toBe(false)` was free.
+ */
+const ABSENCE_ASSERTION = /\.toBe\s*\(\s*(?:false|null|undefined)\s*\)|\.toBeNull\s*\(|\.toBeUndefined\s*\(|\.toBeFalsy\s*\(|\.toHaveLength\s*\(\s*0\s*\)|\.toEqual\s*\(\s*(?:\[\s*\]|\{\s*\})\s*\)|\.not\s*\.\s*to\w+/;
+const PY_ABSENCE_ASSERTION = /\bassert\s+not\b|\bis\s+None\b|==\s*(?:False|None)\b|==\s*(?:\[\s*\]|\{\s*\})|\bassert\s+len\s*\([^)]*\)\s*==\s*0\b/;
+/**
+ * Any assertion at all -- imported from the linter rather than restated.
+ *
+ * A local `/\bexpect\s*\(|\bassert\s*[.(]/` was NOT the linter's vocabulary, and
+ * the comment claiming it was is how the gap survived: `ASSERT_JS` also knows
+ * `should`-style, `.should`, the `toThrow` family, and the
+ * `expectX()`/`assertX()` helper convention that the linter's own notes say
+ * accounted for 9 of 16 residual findings here. For a suite written in any of
+ * those styles the assertion list came out EMPTY, VAC-003's `length > 0` guard
+ * short-circuited, and the rule reported nothing while nothing said it could not
+ * look -- the silent zero this module exists to prevent, one layer inside it.
+ */
+const JS_ASSERTION = ASSERT_JS;
+const PY_ASSERTION = new RegExp(`${ASSERT_PY.source}|\\bself\\.assert\\w+`);
+function mk(file, line, rule, severity, test, message, suggestion, fidelity) {
+    const f = {
+        file,
+        line,
+        rule,
+        severity,
+        test,
+        message,
+        suggestion,
+    };
+    if (fidelity)
+        f.fidelity = fidelity;
+    return f;
+}
+function lineOf(code, offset) {
+    let n = 1;
+    for (let i = 0; i < offset && i < code.length; i += 1) {
+        if (code[i] === '\n')
+            n += 1;
+    }
+    return n;
+}
+/**
+ * The identifiers a comma-separated import clause binds.
+ *
+ * `{ save as store }` binds `store`; `{ save }` binds `save`. Anything that is
+ * not a bare identifier after that (`type Kit`, a stray comment) is dropped --
+ * the filter is also what guarantees no name reaching {@link mentionsAny} can
+ * carry regex metacharacters.
+ */
+function clauseNames(list) {
+    // Parentheses and newlines stripped first, so the multi-line
+    // `from m import (\n  a,\n  b,\n)` form yields names rather than `(a` -- which
+    // the identifier filter below silently dropped, taking the whole file's target
+    // set with it.
+    return (list ?? '')
+        .replace(/[()\n]/g, ' ')
+        .split(',')
+        .map((raw) => raw
+        .trim()
+        .split(/\s+as\s+/)
+        .pop()
+        ?.trim() ?? '')
+        .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+}
+/** Python first-party imports: `from x import y`, minus the stdlib by name. */
+function pythonImportedTargets(code) {
+    const names = new Set();
+    for (const m of code.matchAll(PY_FROM_IMPORT)) {
+        const root = m[1].split('.')[0];
+        if (PY_STDLIB.has(root))
+            continue;
+        for (const n of clauseNames(m[2]))
+            names.add(n);
+    }
+    return names;
+}
+/** JS/TS first-party imports: any `import`/`require` with a relative specifier. */
+function jsImportedTargets(code) {
+    const names = new Set();
+    for (const re of [JS_RELATIVE_IMPORT, JS_RELATIVE_REQUIRE]) {
+        // Reset explicitly: these are module-level `/g` patterns, so a leftover
+        // `lastIndex` from an earlier file would silently skip the head of this one.
+        re.lastIndex = 0;
+        for (const m of code.matchAll(re)) {
+            for (const n of clauseNames(m[1]))
+                names.add(n);
+            if (m[2])
+                names.add(m[2]);
+        }
+    }
+    return names;
+}
+/** Names imported from first-party (relative) modules. */
+function importedTargets(code, python) {
+    return python ? pythonImportedTargets(code) : jsImportedTargets(code);
+}
+/**
+ * Grow `targets` with local declarations that themselves reach a target, to a
+ * fixpoint.
+ *
+ * This is the concession the issue asked for. Without it, a test that goes
+ * through a helper defined in the same file -- `roundTrip()` calling
+ * `load(save(v))` -- reads as never touching its target, and the rule
+ * confidently reports a correct test as vacuous. One hop covers the common
+ * case; the fixpoint covers a chain of them.
+ */
+function closeOverLocals(code, targets, python) {
+    const decls = [];
+    const re = python ? PY_LOCAL_DECL : JS_LOCAL_DECL;
+    re.lastIndex = 0;
+    const matches = [...code.matchAll(re)];
+    for (let i = 0; i < matches.length; i += 1) {
+        const m = matches[i];
+        const names = boundNames(m, python);
+        if (names.length === 0)
+            continue;
+        const start = m.index + m[0].length;
+        const end = matches[i + 1]?.index ?? code.length;
+        decls.push({ names, body: code.slice(start, end) });
+    }
+    if (!python) {
+        JS_DESTRUCTURED_ASSIGN.lastIndex = 0;
+        for (const m of code.matchAll(JS_DESTRUCTURED_ASSIGN)) {
+            const names = (m[1] ?? '')
+                .split(',')
+                .map((raw) => raw.split(':').pop().trim())
+                .filter((n) => /^[A-Za-z_$][\w$]*$/.test(n));
+            // The RHS alone is the body here: unlike a declaration, an assignment
+            // does not own the text that follows it.
+            if (names.length > 0)
+                decls.push({ names, body: m[2] ?? '' });
+        }
+    }
+    const reaching = new Set(targets);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const d of decls) {
+            if (d.names.every((n) => reaching.has(n)))
+                continue;
+            const reaches = [...reaching].some((t) => identifierPattern(t).test(d.body));
+            if (!reaches)
+                continue;
+            for (const n of d.names)
+                reaching.add(n);
+            grew = true;
+        }
+    }
+    return reaching;
+}
+/** Body lines of a test, paired with their 1-based line numbers. */
+function bodyLines(code, block) {
+    const first = lineOf(code, block.bodyStart);
+    return block.body.split('\n').map((text, i) => ({ text, line: first + i }));
+}
+function isComment(line) {
+    const s = line.trim();
+    return s.startsWith('#') || s.startsWith('//') || s.startsWith('*');
+}
+/** The text inside a balanced `expect(...)`, or null. */
+function expectArgument(line) {
+    const open = line.indexOf('expect(');
+    if (open < 0)
+        return null;
+    let depth = 0;
+    for (let i = open + 'expect'.length; i < line.length; i += 1) {
+        if (line[i] === '(')
+            depth += 1;
+        else if (line[i] === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return line.slice(open + 'expect('.length, i);
+        }
+    }
+    return null;
+}
+/**
+ * The matcher following `expect(...)`: its argument, and whether it is negated.
+ *
+ * The negation is returned rather than swallowed. `expect(v).not.toBe(v)` has
+ * identical texts on both sides, so a comparison that ignored `.not` reported it
+ * as `VAC-001` -- "no implementation can fail it" -- about an assertion that can
+ * only ever FAIL. Inverting the rule's own claim is worse than missing the case,
+ * and it was a `critical` finding that BLOCKS promotion. `pyTautology` already
+ * guarded the analogous `assert False`; the JS path had no equivalent.
+ */
+function matcherOf(line) {
+    const m = /\.\s*(not\s*\.\s*)?to\w+\s*\(([^()]*)\)/.exec(line);
+    return m ? { argument: m[2], negated: m[1] !== undefined } : null;
+}
+function normalize(expr) {
+    return expr.replace(/\s+/g, '');
+}
+/** VAC-001 for one JS/TS line. */
+function jsTautology(line) {
+    const actual = expectArgument(line);
+    const matcher = matcherOf(line);
+    if (actual === null || matcher === null || matcher.negated)
+        return false;
+    const a = normalize(actual);
+    const e = normalize(matcher.argument);
+    if (a === '' || e === '')
+        return false;
+    return a === e;
+}
+/** VAC-001 for one pytest line. */
+function pyTautology(line) {
+    const t = line.trim();
+    // `assert False` is a deliberate unreachable marker -- it can only ever fail,
+    // so it is the opposite of vacuous and must never be flagged.
+    if (/^assert\s+True\s*(?:,|$)/.test(t))
+        return true;
+    // Same reason `.not` is excluded above: `assert x != x` can only ever fail.
+    const cmp = /^assert\s+(.+?)\s*==\s*(.+?)\s*(?:,|$)/.exec(t);
+    if (!cmp)
+        return false;
+    return normalize(cmp[1]) === normalize(cmp[2]);
+}
+function scanBlock(code, block, file, python, reaching, annotated, skipped) {
+    const lines = bodyLines(code, block).filter((l) => !isComment(l.text));
+    const targets = annotated !== null ? new Set([annotated]) : reaching;
+    return [
+        ...tautologies(lines, block, file, python),
+        ...targetNeverInvoked(block, file, reaching, annotated),
+        ...absenceOnly(lines, block, file, python, targets, skipped),
+    ];
+}
+/**
+ * A pattern matching `name` as a whole identifier.
+ *
+ * NOT `\b${name}\b`, which is wrong for the `$` that JS identifiers allow and
+ * `\w` does not. `\b` sits between a `\w` and a non-`\w`, so `\b$fetch\b` can
+ * only match after a word character -- a `$`-prefixed import never matched at
+ * all, and `\bfoo$bar\b` can never match. That silently shrank the target set,
+ * producing a `VAC-002` false positive on a test invoking its target on the only
+ * line it had. Lookarounds over `[\w$]` give the boundary JS actually has.
+ *
+ * `name` is escaped as well: every call site filters to `[A-Za-z_$][\w$]*`
+ * today, so nothing can currently smuggle a metacharacter through, but the
+ * escape means a widened filter cannot turn into a silent semantic change.
+ */
+function identifierPattern(name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`);
+}
+/** Does `text` name any symbol in `targets`? */
+function mentionsAny(text, targets) {
+    return (targets !== null &&
+        [...targets].some((t) => identifierPattern(t).test(text)));
+}
+/**
+ * VAC-001 -- deterministic, hence `critical`: an expectation identical to the
+ * value it checks cannot fail for any implementation.
+ */
+function tautologies(lines, block, file, python) {
+    return lines
+        .filter((l) => (python ? pyTautology(l.text) : jsTautology(l.text)))
+        .map((l) => mk(file, l.line, 'VAC-001', 'critical', block.name, 'Assertion compares a value with itself; no implementation can fail it.', 'Assert the value the code under test should have produced, not the input.'));
+}
+/** VAC-002 -- the target is never referenced anywhere in the body. */
+function targetNeverInvoked(block, file, reaching, annotated) {
+    if (annotated !== null) {
+        if (mentionsAny(block.body, new Set([annotated])))
+            return [];
+        return [
+            mk(file, block.line, 'VAC-002', 'warning', block.name, `Declared target \`${annotated}\` is never referenced in this test.`, 'Invoke the target, or correct the @covers annotation to name what the test actually exercises.', 'annotated'),
+        ];
+    }
+    if (reaching === null || mentionsAny(block.body, reaching))
+        return [];
+    return [
+        mk(file, block.line, 'VAC-002', 'warning', block.name, 'This test references none of the symbols the file imports from first-party modules.', 'If the target is reached indirectly, add `// @covers <symbol>` so the check verifies the real target instead of inferring one.', 'import-inferred'),
+    ];
+}
+/**
+ * VAC-003 -- every assertion is an absence, AND none of them observes the
+ * target.
+ *
+ * That second clause is not a refinement, it is the rule. The first cut omitted
+ * it and reported 254 findings across canary's 2154 tests, nearly all of the
+ * form `expect(isCI()).toBe(false)` -- a perfectly good negative test, because
+ * the assertion invokes the target, so the target provably ran and the `false`
+ * is load-bearing. The #486 katana defect is the other shape:
+ * `expect(existsSync(ledger)).toBe(false)` after a bare call, where the absence
+ * is observed on a BYSTANDER and the buggy code satisfied it by exiting before
+ * the write. Reported at the first absence assertion, the line an author adds a
+ * precondition next to.
+ */
+function absenceOnly(lines, block, file, python, targets, skipped) {
+    if (targets === null)
+        return [];
+    const anyAssertion = python ? PY_ASSERTION : JS_ASSERTION;
+    const absence = python ? PY_ABSENCE_ASSERTION : ABSENCE_ASSERTION;
+    const assertions = lines.filter((l) => anyAssertion.test(l.text));
+    if (assertions.length === 0) {
+        // Zero recognised assertions is unanswerable, not clean: either the test
+        // asserts nothing (which is `LINT-006`'s finding, not this rule's) or its
+        // assertion style is one the vocabulary does not know. Both are "cannot
+        // verify", so both are recorded rather than passed over in silence.
+        skipped.push({
+            name: `VAC-003 (${block.name})`,
+            reason: 'no recognised assertion, so absence-only could not be judged -- the test may assert nothing (LINT-006) or use an unrecognised assertion style',
+        });
+        return [];
+    }
+    if (!assertions.every((l) => absence.test(l.text)))
+        return [];
+    if (assertions.some((l) => mentionsAny(l.text, targets)))
+        return [];
+    return [
+        mk(file, assertions[0].line, 'VAC-003', 'warning', block.name, 'Every assertion in this test asserts an absence, and none of them observes the target.', 'Add one assertion proving the operation actually ran (exit code, returned value, a positive existence) -- otherwise the test passes identically when the code crashed before doing anything.'),
+    ];
+}
+/** A zero-denominator result that names why it could not measure. */
+function unreadable(path, reason) {
+    return { checked: 0, findings: [], skipped: [{ name: path, reason }] };
+}
+function readSource(path) {
+    try {
+        return { ok: true, source: readFileSync(path, 'utf-8') };
+    }
+    catch (e) {
+        const code = e.code ?? 'unknown error';
+        return { ok: false, reason: `could not be read (${code})` };
+    }
+}
+/**
+ * The target set for the `import-inferred` rung, or `null` when there is none.
+ *
+ * Imports are read from the ORIGINAL source, not the blanked copy: blanking
+ * replaces literal CONTENT with spaces, so `from './store.js'` becomes
+ * `from '           '` and the leading `.` that marks a first-party module is
+ * gone -- which silently collapsed every JS/TS file to "target unresolvable".
+ *
+ * The cost is that an import written inside a fixture string is read as real.
+ * That only ever ADDS names to the target set, which makes VAC-002 quieter,
+ * never noisier -- the safe direction for a heuristic-tier rule.
+ */
+function resolveTargets(source, code, python) {
+    const imported = importedTargets(source, python);
+    return imported.size > 0 ? closeOverLocals(code, imported, python) : null;
+}
+/**
+ * The `@covers` symbol declared above `block`, or `null`.
+ *
+ * Two bugs lived in the naive version, and both produced a FALSE BLOCK, which is
+ * the worst outcome available here: `annotated` is the one vacuity fidelity
+ * allowed to block a promotion, so a stray annotation failed a correct test.
+ *
+ * - The window was a blind 400-character look-back, so it reached over the
+ *   PREVIOUS test and its annotation. It is now floored at `floor` -- the end of
+ *   the previous test's body -- so only text genuinely between the two
+ *   declarations can be read.
+ * - `exec` returns the match nearest the START of the window, i.e. the FARTHEST
+ *   annotation above the declaration. It now takes the last, which is the
+ *   nearest.
+ */
+function annotationFor(code, block, floor) {
+    const from = Math.max(floor, block.bodyStart - 400);
+    const window = code.slice(from, block.bodyStart);
+    const matches = [...window.matchAll(COVERS_PRAGMA)];
+    return matches.at(-1)?.[1] ?? null;
+}
+/**
+ * Scan one test file for vacuous tests.
+ *
+ * `checked` counts the tests actually analysed. A file no ruleset can parse
+ * yields `checked: 0` plus a skip entry, never an empty finding list that reads
+ * as clean.
+ */
+export function scanVacuity(path) {
+    const framework = frameworkForPath(path);
+    if (framework === null) {
+        return unreadable(path, 'no ruleset parses this extension, so a clean result would be meaningless');
+    }
+    const python = framework === 'pytest';
+    const read = readSource(path);
+    if (!read.ok)
+        return unreadable(path, read.reason);
+    const source = read.source;
+    // Whole-source blanking, offset-preserving: a `expect(true).toBe(true)`
+    // carried as fixture DATA is not a vacuous test, and a `it(...)` inside a
+    // string must not be able to truncate a real test's body (#590).
+    const code = blankStringContent(source, { python });
+    const blocks = enumerateTests(code, source, python);
+    const reaching = resolveTargets(source, code, python);
+    const skipped = [];
+    const findings = scanAllBlocks({ code, path, python, reaching }, blocks, skipped);
+    const result = {
+        checked: blocks.length,
+        findings,
+    };
+    if (skipped.length > 0)
+        result.skipped = skipped;
+    return result;
+}
+function scanAllBlocks(ctx, blocks, skipped) {
+    const findings = [];
+    for (let i = 0; i < blocks.length; i += 1) {
+        const block = blocks[i];
+        // An annotation may only be read from the gap between the previous test's
+        // end and this declaration -- see `annotationFor`.
+        const prev = blocks[i - 1];
+        const floor = prev ? prev.bodyStart + prev.body.length : 0;
+        const annotated = annotationFor(ctx.code, block, floor);
+        if (annotated === null && ctx.reaching === null) {
+            // Both target-dependent rules go dark together, and both say so. VAC-003
+            // asks "does any assertion observe the target", which is unanswerable
+            // without a target -- so it abstains rather than falling back to the
+            // 254-false-positive version of itself.
+            skipped.push({
+                name: `VAC-002/VAC-003 (${block.name})`,
+                reason: 'target unresolvable: no @covers annotation and no first-party relative import to infer from',
+            });
+        }
+        findings.push(...scanBlock(ctx.code, block, ctx.path, ctx.python, ctx.reaching, annotated, skipped));
+    }
+    return findings;
+}
+//# sourceMappingURL=vacuity-scanner.js.map

package/dist/engine/core/workflow-discovery.js

@@ -36,6 +36,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { ensureAscii } from '../util/ensure-ascii.js';
 // ---------------------------------------------------------------------------
 // Python-compatibility helpers (copied locally per-module, matching reporter.ts)
 // ---------------------------------------------------------------------------
@@ -58,13 +59,6 @@ function pyTruthy(value) {
 function pyGet(obj, key, fallback) {
     return Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : fallback;
 }
-/**
- * Reproduce Python's `json.dumps(..., ensure_ascii=True)` (the library default)
- * on `JSON.stringify` output: escape every code point >= 0x80 as `\uXXXX`.
- */
-function ensureAscii(json) {
-    return json.replace(/[\u0080-\uffff]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
-}
 /** Python `str[:n]` by CODE POINT (never splits a surrogate pair). */
 function codePointSlice(s, n) {
     return [...s].slice(0, n).join('');
@@ -120,7 +114,7 @@ export const defaultSubprocess = (cmd, opts = {}) => {
 // ---------------------------------------------------------------------------
 // Schema
 // ---------------------------------------------------------------------------
-export const SCHEMA_VERSION = 'https://github.com/bop-clocktower/canary/schemas/workflow-mapping/v1';
+const SCHEMA_VERSION = 'https://github.com/bop-clocktower/canary/schemas/workflow-mapping/v1';
 // Word-list used for automatic semantic-role heuristics.
 const ROLE_TRIGGERS = {
     qa_passed: ['qa pass', 'qa passed', 'qa done', 'tested', 'verified'],

package/dist/engine/core/workspace-detect.js

@@ -8,7 +8,7 @@
  */
 import { existsSync, readdirSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
-import { _CONFIG_PROBES, inferPlaywrightShape, probe, } from './framework-probes.js';
+import { CONFIG_PROBES, inferPlaywrightTestType, probeFramework, } from './framework-probes.js';
 import { comparePathParts, globDirs, isFile, parseJsonOrNull, readTextOrNull, } from './fs-glob.js';
 /**
  * Workspace package globs declared at *root*, from pnpm-workspace.yaml or
@@ -146,13 +146,13 @@ function toPosixRel(root, dir) {
 function configFindings(dir, rel) {
     const out = [];
     const seen = new Set();
-    for (const [filename, framework, shape, confidence] of _CONFIG_PROBES) {
+    for (const [filename, framework, shape, confidence] of CONFIG_PROBES) {
         if (!isFile(join(dir, filename)))
             continue;
         // Mirrors the config tier's own refinement: a playwright config with no
         // UI-fixture spec is an API suite, and the shape decides which skills ship.
         const refined = framework === 'playwright' && shape === 'e2e_ui'
-            ? inferPlaywrightShape(dir)
+            ? inferPlaywrightTestType(dir)
             : shape;
         // NUL separates the parts because it cannot occur in a path, a framework
         // name, or a shape -- so `a\0b` can never collide with `a` + `\0b`. Written
@@ -177,14 +177,15 @@ function configFindings(dir, rel) {
  * Findings for one package: every config-tier match, or -- only when the config
  * tier found nothing at all -- a single content-tier answer.
  *
- * The language tier is deliberately withheld; see `probe` for why inheriting a
- * root `language:` per package would invent findings (#504 part 1, spec test 8).
+ * The language tier is deliberately withheld; see `probeFramework` for why
+ * inheriting a root `language:` per package would invent findings (#504 part 1,
+ * spec test 8).
  */
 function probePackage(dir, config, rel) {
     const fromConfig = configFindings(dir, rel);
     if (fromConfig.length > 0)
         return fromConfig;
-    const [framework, shape, source, confidence] = probe(dir, config, ['content']);
+    const [framework, shape, source, confidence] = probeFramework(dir, config, ['content']);
     return framework === null
         ? []
         : [{ dir: rel, framework, shape, source, confidence }];

package/dist/engine/data/personas/registry.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "fallback": "junior",
+  "minDetectionConfidence": 0.5,
+  "minDetectionSignals": 2,
+  "detectionMap": {
+    "sdet": "sdet",
+    "manual": "manual"
+  },
+  "personas": [
+    {
+      "id": "sdet",
+      "label": "Senior SDET",
+      "audience": "Writes and owns automated tests daily; fluent in the framework and the codebase.",
+      "depth": "terse",
+      "formats": ["bullets", "code"],
+      "reasoning": false
+    },
+    {
+      "id": "junior",
+      "label": "Junior SDET",
+      "audience": "Writes automated tests but is still building judgement about which ones matter.",
+      "depth": "brief",
+      "formats": ["bullets", "code", "rationale"],
+      "reasoning": true
+    },
+    {
+      "id": "manual",
+      "label": "Manual tester",
+      "audience": "Tests by hand and reads test output; may not read or write the framework's code.",
+      "depth": "guided",
+      "formats": ["numbered-steps", "rationale"],
+      "reasoning": true
+    }
+  ]
+}