@veda-hq/pariksha 0.5.18 → 0.5.20

package/README.md

@@ -4,8 +4,8 @@
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
 ```sh
-npx @veda-hq/pariksha@0.5.18 <check> [flags]
-npx @veda-hq/pariksha@0.5.18 --version
+npx @veda-hq/pariksha@0.5.20 <check> [flags]
+npx @veda-hq/pariksha@0.5.20 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -467,6 +467,44 @@ config (an unknown, missing or bad key or pattern), a malformed baseline, no
 `node_modules/.bin` (DOC-DRIFT-02 would know no bin), a missing or failing
 lychee, a `--base` with no merge base, or a failed git call.
 
+## `duplicate-tests`
+
+```sh
+pariksha duplicate-tests [--config <file>] [--files-from <file>|-] [--root <dir>]
+```
+
+A test copied rather than written: two tests whose matchers, names and
+describe paths score at or above the threshold (default 0.85; across two
+files never below 0.95). The score weighs the matcher set (`expect()` and
+every `.to…()` call in the test, Jaccard) at 50%, the name at 20% and the
+describe path at 30% (edit distance); `describe(X.name)` names its block `X`,
+and two tests in no describe block compare their file stems. A pair is not
+compared when either test has fewer than three matcher calls, either name is
+generic (`should return`, …), the names are opposite cases (an opposite
+pair, other HTTP methods or statuses, other uppercase `AND`/`OR`, another
+endpoint), or, in one file, either name has a word the other lacks or the
+same words come in another order.
+
+Without `--files-from` every tracked file on disk is listed; with it, the
+listed paths (one per line or NUL-separated, relative to the root or
+absolute; `-` reads stdin). A listed path counts when `include` matches it
+relative to the root. A file that cannot be read warns on stderr and is
+skipped; a file that does not parse prints `❌ Parse error:` on stderr and
+gives no tests. The report goes to stdout. The JSON `--config` (relative to
+the root) replaces each default it names:
+
+- `include` (default `\.(test|spec)\.(ts|tsx|js|jsx)$`): which paths are tests.
+- `threshold` (default `0.85`).
+- `commonNames`: names too generic to compare, lowercased.
+- `oppositePairs`: `[word, word]` pairs that mark two names as opposite
+  cases (the default holds fifteen, such as `success`/`failure` and
+  `valid`/`invalid`). Names are lowercased before they are matched, so a pair
+  must be lowercase to match.
+
+Needs `typescript` `>=5.4 <6`, as `coverage-by-type` does. A `.ts` file is
+read as TypeScript and the rest as TSX; a `.ts` file that only parses as
+TSX is read so, and one with a `<T>value` assertion gives no tests.
+
 ## `enforcement-claims`
 
 ```sh
@@ -740,6 +778,34 @@ root-relative POSIX path, a check not in `checks`, an `exemptIn` group
 baseline, a root holding no tracked file, a group discovering nothing, no
 base without `--no-base`, a failed git call, or no `typescript`.
 
+## `flaky-tests`
+
+```sh
+pariksha flaky-tests [--config <file>] [--files-from <file>|-] [--runs <n>] [--root <dir>]
+```
+
+Runs the test files `--runs` times (default 5, at most 1000) with
+`npx vitest run --reporter=json --passWithNoTests`, the files under each
+package root together from that root and the rest from the repository root,
+and judges every run's JSON report strictly (a report that breaks Vitest's
+contract, or a clean exit with no report or one saying `success: false`, is
+not trusted). The verdicts, each exiting 1 but the last:
+
+1. a run exited non-zero without collecting a test case (an unloadable file,
+   a crashed runner): the runner output is printed, and any flaky test seen
+   in the other runs below it;
+2. a test passed in some runs and failed in others: flaky;
+3. every run failed, or a test failed in every run: not flaky, but broken;
+4. every run passed: `✅ No flaky tests found across N test cases.`
+
+The files are listed as for `duplicate-tests`. The JSON `--config` (relative
+to the root) replaces each default it names:
+
+- `include` (default `\.(test|spec)\.(ts|tsx|js|jsx)$`): which paths are tests.
+- `packageRoots` (default none): directories, relative to the root, whose
+  files Vitest runs from that directory, with its config.
+- `exclude` (default none): globs passed to Vitest as `--exclude`.
+
 ## `masked-exit-codes`
 
 ```sh
@@ -865,6 +931,47 @@ refuse is not passed: it is printed as a selector not version-checked.
 line to stdout; a missing input file is a failure (exit 1), a bad config or
 an unreadable `package.json` exits 2.
 
+## `python-floor`
+
+```sh
+pariksha python-floor --python <interpreter> --floor-file <path> [--exclude <regex>] [--selector <path>] [--root <dir>]
+```
+
+Every tracked Python source runs on the Python the repository declares. The
+floor drifts unseen: CI runners ship a new Python, and a PEP 604 union or a
+fresh stdlib import reads as ordinary code until it fails on an older
+interpreter, inside whatever was running it. Sources are `*.py` files, and
+heredocs and single-quoted `python3 -c '...'` payloads in `*.sh` files and
+under `.husky/`, read from the index (the commit being made, not the working
+tree). Each is refused for:
+
+1. syntax the floor cannot parse (`ast` with `feature_version` at the floor);
+2. a stdlib module added after the floor, or removed at or before it;
+3. on a floor below 3.10, a PEP 604 `X | Y` that is evaluated.
+
+A source it cannot read (an unknown encoding, a symlink, conflict stages) is
+refused, never skipped.
+
+- `--python` names the interpreter, at or above the floor; pariksha never
+  chooses or bundles one. Below the floor it refuses to judge (exit 2).
+- `--floor-file` is the file, relative to the root and tracked, holding one
+  `MAJOR.MINOR` (`#` comments allowed).
+- `--exclude` (default none) is a Python regular expression matched from the
+  start of each path; what it matches is not checked. One that does not
+  compile exits 2.
+- `--selector` (default none) names what picks an interpreter at or above
+  the floor in this repository, for the message given when `--python` is
+  below it.
+
+The check is a stdlib-only script shipped in the package
+(`python/python-floor.py`), run as `<interpreter> python/python-floor.py`;
+its stdout (the clean line), stderr (findings) and exit code are passed
+through unchanged. An interpreter that cannot be started, or that is stopped
+by a signal, exits 2. Two input errors exit 1, as the script always has: a
+floor file that is not in the index, not a regular file there, or not one
+`MAJOR.MINOR` (one line on stderr), and a `--root` outside a git repository
+(a Python traceback).
+
 ## `required-settings`
 
 ```sh

package/dist/cli.js

@@ -29,6 +29,9 @@ import { discover as discoverCodecs, fileOf as codecFileOf, findings as codecFin
 import { discoverGroup, findings as faultFindings, formatFindings as formatFaultFindings, parseBaseline as parseFaultBaseline, parseConfig as parseFaultConfig } from "./fault-injection-registry.js";
 import { emptyRoots, growthSince, readBaseline, wholeId } from "./registry-ratchet.js";
 import { checkClaims, formatOutcome, loadEslint, parseConfig as parseClaimsConfig } from "./enforcement-claims.js";
+import { parseConfig as parseDuplicateConfig, runDuplicateTests } from "./duplicate-tests.js";
+import { DEFAULT_RUNS, npxVitest, parseConfig as parseFlakyConfig, parseRuns, runFlakyTests } from "./flaky-tests.js";
+import { inheritRunner, runPythonFloor } from "./python-floor.js";
 export const DENY_FILE = '.veda/deny.sha256';
 const USAGE = [
     'usage: pariksha authority-citations [--mode staged|tree] [--authority <a,b>] [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]',
@@ -40,13 +43,16 @@ const USAGE = [
     '       pariksha coverage-exemptions --config <file> [--package <dir>] [--root <dir>]',
     '       pariksha doc-budgets --table <file> [--section <name>] [--root <dir>]',
     '       pariksha doc-references --config <file> (--staged | --base <ref> [--head <ref>] | --all [--update-baseline | --write-baseline]) [--checks <ids>] [--root <dir>]',
+    '       pariksha duplicate-tests [--config <file>] [--files-from <file>|-] [--root <dir>]',
     '       pariksha enforcement-claims --config <file> [--root <dir>]',
     '       pariksha env-gate-switches --config <file> [--mode staged|tree] [--root <dir>]',
     '       pariksha export-deletions [--base <ref>] [--root <dir>]',
     '       pariksha fault-injection-registry --config <file> [--base <ref> | --no-base] [--root <dir>]',
+    '       pariksha flaky-tests [--config <file>] [--files-from <file>|-] [--runs <n>] [--root <dir>]',
     '       pariksha masked-exit-codes [--config <file>] [--staged] [--root <dir>]',
     '       pariksha non-synced-resources [--config <file>] [--files-from <file>|-] [--root <dir>]',
     '       pariksha pnpm-settings [--config <file>] [--root <dir>]',
+    '       pariksha python-floor --python <interpreter> --floor-file <path> [--exclude <regex>] [--selector <path>] [--root <dir>]',
     '       pariksha required-settings --require <file> [--settings <file>] [--root <dir>]',
     '       pariksha shell-gates [--config <file>] [--staged | --all | --base <ref> | --files-from <file>|-] [--only <checks>] [--root <dir>]',
     '       pariksha hash <word>',
@@ -694,6 +700,97 @@ const requiredSettings = (f, io) => {
     result.err.forEach(io.err);
     return result.ok ? 0 : 1;
 };
+/**
+ * The test files duplicate-tests and flaky-tests judge, relative to the root:
+ * those `--files-from` lists (mode `files`; a relative entry is read from the
+ * root), or every tracked file on disk (mode `all`), kept when `include`
+ * matches the root-relative path.
+ */
+const testFiles = (f, io, root, include) => {
+    const from = f.get('--files-from');
+    const listed = from === undefined
+        ? must(gitAt(root), ['ls-files', '-z'])
+            .split('\0')
+            .filter((p) => p && existsSync(join(root, p)))
+        : entries(from === '-' ? (io.stdin ?? (() => readFileSync(0, 'utf8')))() : readFileSync(resolve(from), 'utf8')).map((e) => relative(root, resolve(root, e)));
+    return { mode: from === undefined ? 'all' : 'files', files: listed.filter((p) => include.test(p)) };
+};
+/** duplicate-tests: the report on stdout, warnings and parse errors on stderr, as the original printed them. */
+const duplicateTests = (f, io) => {
+    const P = 'pariksha duplicate-tests:';
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`${P} ${dir} is not in a git repository`);
+        return 2;
+    }
+    const ts = (io.typescript ?? (() => loadTypescript(typescriptLoaders(root))))();
+    if (typeof ts === 'string') {
+        io.err(`${P} ${ts}`);
+        return 2;
+    }
+    try {
+        const configPath = f.get('--config');
+        const config = parseDuplicateConfig(configPath === undefined ? undefined : readFileSync(resolve(root, configPath), 'utf8'));
+        const { mode, files } = testFiles(f, io, root, config.include);
+        const listed = files.map((file) => ({ file, path: resolve(root, file), read: () => readFileSync(resolve(root, file), 'utf8') }));
+        const result = runDuplicateTests(ts, config, mode, listed);
+        result.out.forEach(io.out);
+        result.err.forEach(io.err);
+        return result.code;
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+};
+/** flaky-tests: `--runs` passes (default 5) of Vitest over the test files, from each package root. */
+const flakyTests = (f, io) => {
+    const P = 'pariksha flaky-tests:';
+    const runsText = f.get('--runs');
+    const runs = runsText === undefined ? DEFAULT_RUNS : parseRuns(runsText);
+    if (runs === null) {
+        io.err('--runs must be an integer from 1 to 1000');
+        return 2;
+    }
+    const dir = resolve(f.get('--root') ?? '.');
+    const root = topOf(dir);
+    if (root === undefined) {
+        io.err(`${P} ${dir} is not in a git repository`);
+        return 2;
+    }
+    let selected;
+    try {
+        const configPath = f.get('--config');
+        const config = parseFlakyConfig(configPath === undefined ? undefined : readFileSync(resolve(root, configPath), 'utf8'));
+        selected = { config, ...testFiles(f, io, root, config.include) };
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    return runFlakyTests(selected.config, runs, selected.mode, root, selected.files, io.vitest ?? npxVitest, io.out);
+};
+/** python-floor: the packaged script under the `--python` the caller names, its output and exit code passed through. */
+const pythonFloor = (f, io) => {
+    const python = f.get('--python');
+    const floorFile = f.get('--floor-file');
+    if (python === undefined || floorFile === undefined) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = f.get('--root');
+    const exclude = f.get('--exclude');
+    const selector = f.get('--selector');
+    const options = {
+        python,
+        floorFile,
+        ...(root === undefined ? {} : { root }),
+        ...(exclude === undefined ? {} : { exclude }),
+        ...(selector === undefined ? {} : { selector }),
+    };
+    return runPythonFloor(options, io.python ?? inheritRunner, io.err);
+};
 const COMMANDS = {
     'codec-registry': { allowed: ['--config', '--base', '--root'], switches: ['--no-base'], run: codecRegistry },
     'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
@@ -702,12 +799,15 @@ const COMMANDS = {
     'aggregate-gate-needs': { allowed: ['--config', '--root'], run: aggregateGateNeeds },
     'non-synced-resources': { allowed: ['--config', '--files-from', '--root'], run: nonSyncedResources },
     'pnpm-settings': { allowed: ['--config', '--root'], run: pnpmSettings },
+    'python-floor': { allowed: ['--python', '--floor-file', '--exclude', '--selector', '--root'], run: pythonFloor },
     'authority-citations': { allowed: ['--mode', '--authority', '--issue-prefix', '--adr-dir', '--root'], run: authorityCitations },
     boundary: { allowed: ['--root', '--deny'], run: boundary },
     'coverage-by-type': { allowed: ['--config', '--files-from', '--root'], run: coverageByType },
     'doc-budgets': { allowed: ['--table', '--section', '--root'], run: docBudgets },
     'doc-references': { allowed: ['--config', '--base', '--head', '--checks', '--root'], switches: ['--staged', '--all', '--update-baseline', '--write-baseline'], run: docReferences },
+    'duplicate-tests': { allowed: ['--config', '--files-from', '--root'], run: duplicateTests },
     'enforcement-claims': { allowed: ['--config', '--root'], run: enforcementClaims },
+    'flaky-tests': { allowed: ['--config', '--files-from', '--runs', '--root'], run: flakyTests },
     'env-gate-switches': { allowed: ['--config', '--mode', '--root'], run: envGateSwitches },
     'export-deletions': { allowed: ['--base', '--root'], run: exportDeletions },
     'masked-exit-codes': { allowed: ['--config', '--root'], switches: ['--staged'], run: maskedExitCodes },

package/dist/duplicate-tests.js

@@ -0,0 +1,367 @@
+// duplicate-tests: test cases that look copied, by a weighted similarity of
+// their assertion matchers, their names and their describe paths.
+//
+// Read with the TypeScript compiler API (the optional peer), walking the nodes
+// a Babel CallExpression visitor would reach: an optional-chain call is not
+// one, and parentheses are not nodes.
+import { basename } from 'node:path';
+export const DEFAULT_CONFIG = {
+    include: /\.(test|spec)\.(ts|tsx|js|jsx)$/,
+    threshold: 0.85,
+    commonNames: ['should be defined', 'should exist', 'should return', 'should throw', 'should create', 'should update', 'should delete', 'should get', 'should set'],
+    oppositePairs: [
+        ['success', 'failure'],
+        ['success', 'error'],
+        ['pass', 'fail'],
+        ['valid', 'invalid'],
+        ['correct', 'incorrect'],
+        ['positive', 'negative'],
+        ['zero', 'negative'],
+        ['true', 'false'],
+        ['enabled', 'disabled'],
+        ['before', 'after'],
+        ['start', 'end'],
+        ['to', 'from'],
+        ['forward', 'backward'],
+        ['add', 'remove'],
+        ['create', 'delete'],
+    ],
+};
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStrings = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+/** The config a product passes; each field replaces its default, and an unknown field is refused. */
+export const parseConfig = (text) => {
+    if (text === undefined)
+        return DEFAULT_CONFIG;
+    const raw = JSON.parse(text);
+    if (!isRecord(raw))
+        throw new Error('the config is not a JSON object');
+    const known = ['include', 'threshold', 'commonNames', 'oppositePairs'];
+    const unknown = Object.keys(raw).filter((k) => !known.includes(k));
+    if (unknown.length > 0)
+        throw new Error(`the config has unknown field(s): ${unknown.join(', ')}`);
+    const { include, threshold, commonNames, oppositePairs } = raw;
+    if (include !== undefined && typeof include !== 'string')
+        throw new Error('include is not a regex string');
+    if (threshold !== undefined && (typeof threshold !== 'number' || !Number.isFinite(threshold)))
+        throw new Error('threshold is not a number');
+    if (commonNames !== undefined && !isStrings(commonNames))
+        throw new Error('commonNames is not a list of strings');
+    if (oppositePairs !== undefined && !(Array.isArray(oppositePairs) && oppositePairs.every((p) => isStrings(p) && p.length === 2))) {
+        throw new Error('oppositePairs is not a list of [word, word] pairs');
+    }
+    return {
+        include: include === undefined ? DEFAULT_CONFIG.include : new RegExp(include),
+        threshold: threshold ?? DEFAULT_CONFIG.threshold,
+        commonNames: commonNames ?? DEFAULT_CONFIG.commonNames,
+        oppositePairs: oppositePairs ?? DEFAULT_CONFIG.oppositePairs,
+    };
+};
+/** Through parentheses, which Babel does not keep as nodes. */
+const unwrap = (ts, node) => {
+    let n = node;
+    while (ts.isParenthesizedExpression(n))
+        n = n.expression;
+    return n;
+};
+const inChain = (ts, node) => (node.flags & ts.NodeFlags.OptionalChain) !== 0;
+/** A call Babel reads as a CallExpression: not one inside an optional chain. */
+const isPlainCall = (ts, node) => ts.isCallExpression(node) && !inChain(ts, node);
+const calleeName = (ts, call) => {
+    const callee = unwrap(ts, call.expression);
+    return ts.isIdentifier(callee) ? callee.text : undefined;
+};
+/**
+ * The matcher a call names, as Babel's MemberExpression with an Identifier
+ * property: `a.toBe()`, and `a[toBe]()` too; never `a?.toBe()` or `a['toBe']()`.
+ */
+const memberProperty = (ts, call) => {
+    const callee = unwrap(ts, call.expression);
+    if (inChain(ts, callee))
+        return undefined;
+    if (ts.isPropertyAccessExpression(callee))
+        return ts.isIdentifier(callee.name) ? callee.name.text : undefined;
+    if (ts.isElementAccessExpression(callee)) {
+        const arg = unwrap(ts, callee.argumentExpression);
+        return ts.isIdentifier(arg) ? arg.text : undefined;
+    }
+    return undefined;
+};
+const sourceText = (sf, node) => sf.text.slice(node.getStart(sf), node.end);
+/**
+ * The name a describe/test/it call gives its block. A string literal (or a
+ * template without expressions) yields its value; `describe(X.name)` yields
+ * `X`, the unit under test; any other argument its source text.
+ */
+export const extractTestName = (ts, sf, call) => {
+    const [arg] = call.arguments;
+    if (arg === undefined)
+        return 'unnamed test';
+    const first = unwrap(ts, arg);
+    if (ts.isStringLiteral(first) || ts.isNoSubstitutionTemplateLiteral(first))
+        return first.text;
+    const named = ts.isPropertyAccessExpression(first) && !inChain(ts, first) && ts.isIdentifier(first.name) && first.name.text === 'name' ? unwrap(ts, first.expression) : first;
+    return sourceText(sf, named);
+};
+/**
+ * TS for a `.ts` file, TSX for the rest. Babel had JSX on everywhere but reads
+ * `<T>(x) => …` in a `.ts` file as a generic arrow; TypeScript under TSX reads
+ * it as an element and loses the rest of the file.
+ */
+const scriptKind = (ts, file) => (/\.[cm]?ts$/.test(file) ? ts.ScriptKind.TS : ts.ScriptKind.TSX);
+/** The syntax errors the parse recorded; `parseDiagnostics` is the source file's own list, read without a program. */
+const syntaxErrors = (sf) => sf.parseDiagnostics ?? [];
+/**
+ * Syntax TypeScript reads and the Babel parse this replaces (plugins
+ * typescript, jsx and decorators-legacy) threw on, so the file gave no
+ * signatures: a `<T>value` assertion in a `.ts` file, which JSX reads as an
+ * unterminated element, and an `accessor` field, which needs a plugin it did
+ * not have.
+ */
+const babelRefusal = (ts, kind, node) => {
+    if (kind === ts.ScriptKind.TS && ts.isTypeAssertionExpression(node))
+        return 'a <T>value type assertion, which a JSX parse reads as an unterminated element';
+    if (ts.isPropertyDeclaration(node) && node.modifiers?.some((m) => m.kind === ts.SyntaxKind.AccessorKeyword) === true)
+        return 'an accessor field, which needs the decoratorAutoAccessors parser plugin';
+    if (ts.isClassLike(node)) {
+        const modifiers = node.modifiers ?? [];
+        const exported = modifiers.findIndex((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+        // `export default @dec class` is a decorated class expression, which they do take.
+        const isDefault = modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+        if (exported >= 0 && !isDefault && modifiers.slice(exported).some((m) => ts.isDecorator(m)))
+            return 'a decorator after export, which legacy decorators do not take';
+    }
+    return undefined;
+};
+/** Why the file gives no signatures: a syntax error, or what Babel refused; undefined when it reads. */
+const parseError = (ts, sf, refused) => {
+    const [first] = syntaxErrors(sf);
+    const at = (pos) => {
+        const { line, character } = sf.getLineAndCharacterOfPosition(pos);
+        return `(${String(line + 1)}:${String(character)})`;
+    };
+    if (first !== undefined)
+        return `${ts.flattenDiagnosticMessageText(first.messageText, '\n')} ${at(first.start)}`;
+    if (refused !== undefined)
+        return `${refused.why} ${at(refused.node.getStart(sf))}`;
+    return undefined;
+};
+/** Every test with an assertion in one file, in the order a depth-first walk meets them. */
+export const extractTestSignatures = (ts, file, content) => {
+    const parse = (k) => ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, k);
+    let kind = scriptKind(ts, file);
+    let sf = parse(kind);
+    if (kind === ts.ScriptKind.TS && syntaxErrors(sf).length > 0) {
+        // JSX in a `.ts` file, which Babel read: take the TSX parse when it is clean.
+        const tsx = parse(ts.ScriptKind.TSX);
+        if (syntaxErrors(tsx).length === 0) {
+            kind = ts.ScriptKind.TSX;
+            sf = tsx;
+        }
+    }
+    const signatures = [];
+    const describeStack = [];
+    let refused;
+    const assertions = (call) => {
+        const pattern = [];
+        const visit = (node) => {
+            if (isPlainCall(ts, node)) {
+                if (calleeName(ts, node) === 'expect')
+                    pattern.push('expect()');
+                const matcher = memberProperty(ts, node);
+                if (matcher?.startsWith('to') === true)
+                    pattern.push(matcher);
+            }
+            ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(call, visit);
+        return pattern;
+    };
+    const walk = (node) => {
+        if (refused === undefined) {
+            const why = babelRefusal(ts, kind, node);
+            if (why !== undefined)
+                refused = { node, why };
+        }
+        const call = isPlainCall(ts, node) ? node : undefined;
+        const name = call === undefined ? undefined : calleeName(ts, call);
+        if (call !== undefined && name === 'describe')
+            describeStack.push(extractTestName(ts, sf, call));
+        if (call !== undefined && (name === 'test' || name === 'it')) {
+            const assertionPattern = assertions(call);
+            if (assertionPattern.length > 0) {
+                signatures.push({
+                    file,
+                    testName: extractTestName(ts, sf, call),
+                    describePath: [...describeStack],
+                    assertionPattern,
+                    line: sf.getLineAndCharacterOfPosition(call.getStart(sf)).line + 1,
+                });
+            }
+        }
+        ts.forEachChild(node, walk);
+        if (name === 'describe')
+            describeStack.pop();
+    };
+    walk(sf);
+    const error = parseError(ts, sf, refused);
+    return error === undefined ? { signatures } : { signatures: [], parseError: error };
+};
+const levenshtein = (a, b) => {
+    let prev = Array.from({ length: a.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= b.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= a.length; j++) {
+            row[j] = b.charAt(i - 1) === a.charAt(j - 1) ? prev[j - 1] : Math.min(prev[j - 1] + 1, row[j - 1] + 1, prev[j] + 1);
+        }
+        prev = row;
+    }
+    return prev[a.length];
+};
+/** 1 minus the edit distance over the longer length, case-insensitive; 1 for two empty strings. */
+export const stringSimilarity = (a, b) => {
+    const max = Math.max(a.length, b.length);
+    return max > 0 ? 1 - levenshtein(a.toLowerCase(), b.toLowerCase()) / max : 1;
+};
+/** Jaccard similarity of two matcher lists, as sets; 0 when both are empty. */
+export const patternSimilarity = (a, b) => {
+    const setA = new Set(a);
+    const setB = new Set(b);
+    const union = new Set([...setA, ...setB]);
+    return union.size > 0 ? [...setA].filter((x) => setB.has(x)).length / union.size : 0;
+};
+/**
+ * Two tests in no describe block: full credit in one file; across files the
+ * file stems (the basename up to its first dot) are the only names they have.
+ */
+const neitherDescribed = (file1, file2) => {
+    if (file1 === file2)
+        return 1;
+    const stem = (f) => basename(f).split('.')[0];
+    return stringSimilarity(stem(file1), stem(file2));
+};
+/** 50% matchers, 20% name, 30% describe path. */
+export const compositeSimilarity = (a, b) => {
+    const path1 = a.describePath.join(' > ');
+    const path2 = b.describePath.join(' > ');
+    const describeSim = path1.length > 0 && path2.length > 0 ? stringSimilarity(path1, path2) : path1.length === 0 && path2.length === 0 ? neitherDescribed(a.file, b.file) : 0;
+    return patternSimilarity(a.assertionPattern, b.assertionPattern) * 0.5 + stringSimilarity(a.testName, b.testName) * 0.2 + describeSim * 0.3;
+};
+const MIN_ASSERTIONS = 3;
+const HTTP_INDICATORS = /\b(GET|POST|PUT|DELETE|PATCH|200|201|400|401|403|404|500|502)\b/gi;
+// Case-sensitive on purpose: lowercase "and"/"or" are prose, uppercase AND/OR are domain tokens.
+const COMBINATOR_INDICATORS = /\b(AND|OR)\b/g;
+const isCommon = (config, name) => {
+    const normalized = name.toLowerCase().trim();
+    return config.commonNames.some((p) => normalized === p || normalized.startsWith(`${p} `));
+};
+/** Two names for opposite or complementary cases: an opposite pair, other HTTP tokens, other AND/OR tokens, another endpoint. */
+export const areOppositeScenarios = (config, name1, name2) => {
+    const lower1 = name1.toLowerCase();
+    const lower2 = name2.toLowerCase();
+    for (const [w1, w2] of config.oppositePairs) {
+        if ((lower1.includes(w1) && lower2.includes(w2)) || (lower1.includes(w2) && lower2.includes(w1)))
+            return true;
+    }
+    const http1 = Array.from(name1.matchAll(HTTP_INDICATORS), (m) => m[0]);
+    const http2 = Array.from(name2.matchAll(HTTP_INDICATORS), (m) => m[0]);
+    if (http1.length > 0 && http2.length > 0 && http1.some((m) => !http2.includes(m)))
+        return true;
+    const comb1 = Array.from(name1.matchAll(COMBINATOR_INDICATORS), (m) => m[0]);
+    const comb2 = Array.from(name2.matchAll(COMBINATOR_INDICATORS), (m) => m[0]);
+    if (comb1.length > 0 && comb2.length > 0 && (comb1.some((c) => !comb2.includes(c)) || comb2.some((c) => !comb1.includes(c))))
+        return true;
+    const end1 = name1.match(/\/\w+/g) ?? [];
+    const end2 = name2.match(/\/\w+/g) ?? [];
+    return end1.length > 0 && end2.length > 0 && end1[0] !== end2[0];
+};
+const FILLER = new Set(['should', 'when', 'with', 'the', 'a', 'an', 'it', 'is', 'are', 'be', 'to', 'for', 'of', 'in', 'on', 'and', 'or', 'not', 'if', 'that', 'this', 'can', 'does']);
+const words = (name) => name
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]/g, ' ')
+    .split(/\s+/)
+    .filter((w) => w.length > 1 && !FILLER.has(w));
+/**
+ * Two tests in one file that are meant to differ: opposite names, the same
+ * name (so different describe blocks), a word only one has, or the same words
+ * in another order (a mirrored case).
+ */
+export const areSameFileComplementary = (config, file1, file2, name1, name2) => {
+    if (file1 !== file2)
+        return false;
+    if (areOppositeScenarios(config, name1, name2))
+        return true;
+    if (name1 === name2)
+        return true;
+    const words1 = new Set(words(name1));
+    const words2 = new Set(words(name2));
+    if ([...words1].some((w) => !words2.has(w)) || [...words2].some((w) => !words1.has(w)))
+        return true;
+    const seq1 = words(name1);
+    const seq2 = words(name2);
+    return [...seq1].sort().join(' ') === [...seq2].sort().join(' ') && seq1.join(' ') !== seq2.join(' ');
+};
+/** Every pair at or above the threshold, in signature order. */
+export const findDuplicates = (config, signatures) => {
+    const matches = [];
+    const processed = new Set();
+    for (let i = 0; i < signatures.length; i++) {
+        for (let j = i + 1; j < signatures.length; j++) {
+            const a = signatures[i];
+            const b = signatures[j];
+            if (a.assertionPattern.length < MIN_ASSERTIONS || b.assertionPattern.length < MIN_ASSERTIONS)
+                continue;
+            if (isCommon(config, a.testName) || isCommon(config, b.testName))
+                continue;
+            if (areOppositeScenarios(config, a.testName, b.testName))
+                continue;
+            if (areSameFileComplementary(config, a.file, b.file, a.testName, b.testName))
+                continue;
+            const key = `${a.file}:${a.testName}-${b.file}:${b.testName}`;
+            if (processed.has(key))
+                continue;
+            const similarity = compositeSimilarity(a, b);
+            // Different files test different modules: a higher bar.
+            const bar = a.file !== b.file ? Math.max(config.threshold, 0.95) : config.threshold;
+            if (similarity >= bar) {
+                matches.push({ file1: a.file, test1: a.testName, line1: a.line, file2: b.file, test2: b.testName, line2: b.line, similarity });
+                processed.add(key);
+            }
+        }
+    }
+    return matches;
+};
+/** The report, line by line, and the exit code; reading failures warn on stderr and the file is skipped. */
+export const runDuplicateTests = (ts, config, mode, files) => {
+    const out = [`🔍 Searching for duplicate tests (Threshold: ${String(config.threshold)})...`, `   Mode: ${mode}`];
+    const err = [];
+    if (files.length === 0) {
+        out.push('No files found to analyze.');
+        return { code: 0, out, err };
+    }
+    out.push(`   Analyzing ${String(files.length)} files...`);
+    const signatures = [];
+    for (const f of files) {
+        try {
+            const read = extractTestSignatures(ts, f.file, f.read());
+            if (read.parseError !== undefined)
+                err.push(`❌ Parse error: ${read.parseError}`);
+            signatures.push(...read.signatures);
+        }
+        catch (e) {
+            err.push(`⚠️  Failed to parse ${f.path}: ${e.message}`);
+        }
+    }
+    out.push(`   Extracted ${String(signatures.length)} test signatures.`);
+    const duplicates = findDuplicates(config, signatures);
+    if (duplicates.length === 0) {
+        out.push('', '✅ No duplicates found.');
+        return { code: 0, out, err };
+    }
+    out.push('', '❌ Found potential duplicate tests:');
+    for (const d of [...duplicates].sort((x, y) => y.similarity - x.similarity)) {
+        out.push('', `   ${(d.similarity * 100).toFixed(0)}% Match:`, `     A: ${d.file1}:${String(d.line1)} "${d.test1}"`, `     B: ${d.file2}:${String(d.line2)} "${d.test2}"`);
+    }
+    out.push('', `Total potential duplicates: ${String(duplicates.length)}`);
+    return { code: 1, out, err };
+};