@mintwork/honest-tests 0.0.0-stage → 0.1.1

package/dist/rules/excessive-mocking.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../core/types.js';
+export declare const EXCESSIVE_MOCK_THRESHOLD = 5;
+export declare const excessiveMocking: Rule;

package/dist/rules/excessive-mocking.js

@@ -0,0 +1,22 @@
+export const EXCESSIVE_MOCK_THRESHOLD = 5;
+export const excessiveMocking = {
+    id: 'excessive-mocking',
+    severity: 'warning',
+    description: `File mocks ${EXCESSIVE_MOCK_THRESHOLD}+ modules — the test mostly exercises mocks wired to each other.`,
+    fix: 'Mock at the system boundary (HTTP, DB, clock) and let internal modules run for real, or split the unit so it needs fewer collaborators.',
+    check(file) {
+        // Re-mocking the same module in several tests (vi.doMock per case) is still one collaborator.
+        const specs = [...new Set(file.moduleMocks.map((m) => m.specifier))];
+        if (specs.length < EXCESSIVE_MOCK_THRESHOLD)
+            return [];
+        const first = file.moduleMocks[0];
+        return [
+            {
+                line: first.line,
+                column: 1,
+                evidence: specs.join(', '),
+                message: `Mocks ${specs.length} modules — little real code is left under test.`,
+            },
+        ];
+    },
+};

package/dist/rules/focused-test.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const focusedTest: Rule;

package/dist/rules/focused-test.js

@@ -0,0 +1,15 @@
+export const focusedTest = {
+    id: 'focused-test',
+    severity: 'error',
+    description: '.only / fit / fdescribe left in — every other test in the file silently stops running.',
+    fix: 'Remove .only before committing.',
+    check(file) {
+        const out = [];
+        for (const t of file.tests) {
+            if (t.modifier === 'only') {
+                out.push({ line: t.line, column: 1, evidence: t.headText, test: t.name, message: `${t.kind === 'suite' ? 'Suite' : 'Test'} "${t.name}" is focused — the rest of the file is skipped.` });
+            }
+        }
+        return out;
+    },
+};

package/dist/rules/helpers.d.ts

@@ -0,0 +1,5 @@
+import type { Assertion, RawFinding, TestCase, TestFileModel } from '../core/types.js';
+export declare function eachTest(file: TestFileModel): Generator<TestCase>;
+export declare function atAssertion(t: TestCase, a: Assertion, message: string, extra?: Partial<RawFinding>): RawFinding;
+export declare function atTest(t: TestCase, message: string, extra?: Partial<RawFinding>): RawFinding;
+export declare function code(s: string, max?: number): string;

package/dist/rules/helpers.js

@@ -0,0 +1,18 @@
+export function* eachTest(file) {
+    for (const t of file.tests) {
+        if (t.kind !== 'test' || !t.analyzable)
+            continue;
+        if (t.modifier === 'todo' || t.modifier === 'skip')
+            continue;
+        yield t;
+    }
+}
+export function atAssertion(t, a, message, extra = {}) {
+    return { line: a.line, column: a.column, message, evidence: a.text, test: t.name, ...extra };
+}
+export function atTest(t, message, extra = {}) {
+    return { line: t.line, column: 1, message, evidence: t.headText, test: t.name, ...extra };
+}
+export function code(s, max = 60) {
+    return '`' + (s.length > max ? s.slice(0, max - 1) + '…' : s) + '`';
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from '../core/types.js';
+export declare const rules: Rule[];
+export declare function ruleById(id: string): Rule | undefined;

package/dist/rules/index.js

@@ -0,0 +1,31 @@
+import { assertsOnMock } from './asserts-on-mock.js';
+import { assertsOnOwnLiteral } from './asserts-on-own-literal.js';
+import { catchOnlyAssertion } from './catch-only-assertion.js';
+import { conditionalAssertion } from './conditional-assertion.js';
+import { excessiveMocking } from './excessive-mocking.js';
+import { focusedTest } from './focused-test.js';
+import { mockedUnitUnderTest } from './mocked-unit-under-test.js';
+import { neverFailingAssertion } from './never-failing-assertion.js';
+import { noAssertions } from './no-assertions.js';
+import { skippedTest } from './skipped-test.js';
+import { snapshotOnly } from './snapshot-only.js';
+import { swallowedAssertion } from './swallowed-assertion.js';
+import { tautologicalAssertion } from './tautological-assertion.js';
+export const rules = [
+    noAssertions,
+    tautologicalAssertion,
+    assertsOnMock,
+    assertsOnOwnLiteral,
+    neverFailingAssertion,
+    swallowedAssertion,
+    catchOnlyAssertion,
+    mockedUnitUnderTest,
+    excessiveMocking,
+    snapshotOnly,
+    conditionalAssertion,
+    focusedTest,
+    skippedTest,
+];
+export function ruleById(id) {
+    return rules.find((r) => r.id === id);
+}

package/dist/rules/mocked-unit-under-test.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const mockedUnitUnderTest: Rule;

package/dist/rules/mocked-unit-under-test.js

@@ -0,0 +1,32 @@
+import { code } from './helpers.js';
+export const mockedUnitUnderTest = {
+    id: 'mocked-unit-under-test',
+    severity: 'error',
+    description: 'The module the test file is named after is itself mocked, so the real implementation never runs.',
+    fix: 'Mock only the unit\'s dependencies (network, clock, filesystem, other modules) — never the unit itself. Import the real module and assert on its behavior.',
+    check(file) {
+        const out = [];
+        for (const m of file.moduleMocks) {
+            if (!m.isUnitUnderTest)
+                continue;
+            out.push({
+                line: m.line,
+                column: 1,
+                evidence: m.text,
+                severity: m.partial ? 'warning' : 'error',
+                message: m.partial
+                    ? `Partially mocks ${code(m.specifier)}, the module under test — the overridden exports are never really tested here.`
+                    : `Mocks ${code(m.specifier)}, the module this file is testing — every assertion runs against the mock, not the real code.`,
+            });
+        }
+        for (const s of file.unitSpies) {
+            out.push({
+                line: s.line,
+                column: 1,
+                evidence: s.text,
+                message: `Replaces ${code(s.target)} (an export of the module under test) with a mock implementation.`,
+            });
+        }
+        return out;
+    },
+};

package/dist/rules/never-failing-assertion.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const neverFailingAssertion: Rule;

package/dist/rules/never-failing-assertion.js

@@ -0,0 +1,43 @@
+import { atAssertion, code, eachTest } from './helpers.js';
+const ALWAYS_DEFINED = new Set(['object', 'array', 'function', 'new', 'typeof']);
+const ALWAYS_TRUTHY = new Set(['object', 'array', 'function', 'new']);
+export const neverFailingAssertion = {
+    id: 'never-failing-assertion',
+    severity: 'error',
+    description: 'Assertion is structurally unable to fail: missing matcher call, un-awaited async matcher, or a check that is always true.',
+    fix: 'Make the assertion specific: call the matcher, await async matchers, and assert the exact expected value instead of "is defined"/"is truthy".',
+    check(file) {
+        const out = [];
+        for (const t of eachTest(file)) {
+            for (const a of t.assertions) {
+                const s = a.subject;
+                if (a.style === 'expect' && a.matcherKind === 'none') {
+                    out.push(atAssertion(t, a, a.matcher
+                        ? `Matcher ${code('.' + a.matcher)} is referenced but never called — add \`()\`. As written it asserts nothing.`
+                        : '`expect(...)` without a matcher asserts nothing.'));
+                    continue;
+                }
+                if (a.async && !a.awaitedOrReturned) {
+                    out.push(atAssertion(t, a, `Async matcher (.resolves/.rejects) is not awaited or returned — the test can finish before it runs.`));
+                    continue;
+                }
+                if (!s || a.negated)
+                    continue;
+                if (a.matcherKind === 'defined' && ALWAYS_DEFINED.has(s.kind)) {
+                    out.push(atAssertion(t, a, `${code(s.text)} is always defined — this assertion can never fail.`));
+                }
+                else if (a.matcherKind === 'truthy' && ALWAYS_TRUTHY.has(s.kind)) {
+                    out.push(atAssertion(t, a, `${code(s.text)} is always truthy — this assertion can never fail.`));
+                }
+                else if ((a.matcherKind === 'compare-gte' || a.matcherKind === 'compare-other') &&
+                    /\.(length|size)$/.test(s.text) &&
+                    a.args[0] &&
+                    ((a.matcherKind === 'compare-gte' && a.args[0].literalValue === 0) ||
+                        (a.matcher === 'toBeGreaterThan' && typeof a.args[0].literalValue === 'number' && a.args[0].literalValue < 0))) {
+                    out.push(atAssertion(t, a, `${code(s.text)} is never negative — this assertion can never fail.`));
+                }
+            }
+        }
+        return out;
+    },
+};

package/dist/rules/no-assertions.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const noAssertions: Rule;

package/dist/rules/no-assertions.js

@@ -0,0 +1,16 @@
+import { atTest, eachTest } from './helpers.js';
+export const noAssertions = {
+    id: 'no-assertions',
+    severity: 'error',
+    description: 'Test contains no assertions, so it passes as long as nothing throws.',
+    fix: 'Assert on the observable result (return value, state change, emitted call). If "does not throw" is the real contract, say so: expect(() => fn()).not.toThrow().',
+    check(file) {
+        const out = [];
+        for (const t of eachTest(file)) {
+            if (t.assertions.length === 0 && t.helperAssertionCalls === 0 && !t.hasAssertionCountGuard) {
+                out.push(atTest(t, `Test "${t.name}" has no assertions — it can only fail by crashing.`));
+            }
+        }
+        return out;
+    },
+};

package/dist/rules/skipped-test.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const skippedTest: Rule;

package/dist/rules/skipped-test.js

@@ -0,0 +1,15 @@
+export const skippedTest = {
+    id: 'skipped-test',
+    severity: 'warning',
+    description: '.skip / xit / xdescribe left in — the test counts toward the total but verifies nothing.',
+    fix: 'Fix the test, delete it, or turn it into it.todo("...") with a tracking issue.',
+    check(file) {
+        const out = [];
+        for (const t of file.tests) {
+            if (t.modifier === 'skip') {
+                out.push({ line: t.line, column: 1, evidence: t.headText, test: t.name, message: `${t.kind === 'suite' ? 'Suite' : 'Test'} "${t.name}" is skipped.` });
+            }
+        }
+        return out;
+    },
+};

package/dist/rules/snapshot-only.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const snapshotOnly: Rule;

package/dist/rules/snapshot-only.js

@@ -0,0 +1,18 @@
+import { atTest, eachTest } from './helpers.js';
+export const snapshotOnly = {
+    id: 'snapshot-only',
+    severity: 'warning',
+    description: 'The only assertions are snapshots, which record whatever the code does today — bugs included.',
+    fix: 'Add at least one explicit assertion on the property that matters (a value, a field, a call). Keep the snapshot only as a change detector.',
+    check(file) {
+        const out = [];
+        for (const t of eachTest(file)) {
+            if (t.assertions.length === 0 || t.helperAssertionCalls > 0)
+                continue;
+            if (t.assertions.every((a) => a.matcherKind === 'snapshot')) {
+                out.push(atTest(t, `Test "${t.name}" only asserts a snapshot — it will happily approve a wrong result the first time it runs.`));
+            }
+        }
+        return out;
+    },
+};

package/dist/rules/swallowed-assertion.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const swallowedAssertion: Rule;

package/dist/rules/swallowed-assertion.js

@@ -0,0 +1,18 @@
+import { atAssertion, eachTest } from './helpers.js';
+export const swallowedAssertion = {
+    id: 'swallowed-assertion',
+    severity: 'error',
+    description: 'Assertion sits inside a try block whose catch does not rethrow, so a failing assertion is caught and the test passes.',
+    fix: 'Remove the try/catch. For expected errors use expect(() => fn()).toThrow(...) or await expect(p).rejects.toThrow(...).',
+    check(file) {
+        const out = [];
+        for (const t of eachTest(file)) {
+            for (const a of t.assertions) {
+                if (a.context.inSwallowingTry) {
+                    out.push(atAssertion(t, a, 'Assertion is inside a try/catch that swallows errors — when it fails, the catch eats the AssertionError and the test passes.'));
+                }
+            }
+        }
+        return out;
+    },
+};

package/dist/rules/tautological-assertion.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from '../core/types.js';
+export declare const tautologicalAssertion: Rule;

package/dist/rules/tautological-assertion.js

@@ -0,0 +1,42 @@
+import { atAssertion, code, eachTest } from './helpers.js';
+/**
+ * Expected values that are the actual value restated: `toHaveLength(list.length)`, `toEqual(list.slice())`.
+ * Transformations (`toEqual(keys.toSorted())`, `toEqual(xs.map(lower))`) are real property checks.
+ */
+function isCopyOf(actual, expected, kind) {
+    if (kind === 'length')
+        return expected === `${actual}.length` || expected === `${actual}.size`;
+    return [`${actual}.slice()`, `${actual}.concat()`, `${actual}.valueOf()`, `[...${actual}]`, `{...${actual}}`, `structuredClone(${actual})`].includes(expected);
+}
+export const tautologicalAssertion = {
+    id: 'tautological-assertion',
+    severity: 'error',
+    description: 'Assertion compares a value to itself or asserts on a constant, so its outcome is fixed before any code runs.',
+    fix: 'Compare the output of the code under test against an independently known expected value (a literal you worked out by hand, or a fixture).',
+    check(file) {
+        const out = [];
+        for (const t of eachTest(file)) {
+            for (const a of t.assertions) {
+                const s = a.subject;
+                if (!s || a.matcherKind === 'none')
+                    continue;
+                if (s.kind === 'literal') {
+                    out.push(atAssertion(t, a, `Asserts on the constant ${code(s.text)} — no code under test is involved, so this can never fail.`));
+                    continue;
+                }
+                const expected = a.args[0];
+                if (!expected)
+                    continue;
+                if (a.matcherKind !== 'equal' && a.matcherKind !== 'length')
+                    continue;
+                if (expected.text === s.text) {
+                    out.push(atAssertion(t, a, `Compares ${code(s.text)} to itself — this can never fail.`));
+                }
+                else if ((s.kind === 'identifier' || s.kind === 'member') && isCopyOf(s.text, expected.text, a.matcherKind)) {
+                    out.push(atAssertion(t, a, `Expected value ${code(expected.text)} is derived from the actual value ${code(s.text)} — the assertion checks nothing.`));
+                }
+            }
+        }
+        return out;
+    },
+};

package/dist/run.d.ts

@@ -0,0 +1,12 @@
+export declare const PACKAGE_ROOT: string;
+export declare function version(): string;
+export interface IO {
+    stdout: (s: string) => void;
+    stderr: (s: string) => void;
+    cwd: string;
+    /** Show mutation progress on stderr. */
+    progress?: boolean;
+}
+export declare function run(argv: string[], io: IO): Promise<number>;
+/** First and last lines of a test run: the error is usually at the top, the summary at the bottom. */
+export declare function excerpt(output: string, headLines?: number, tailLines?: number): string;

package/dist/run.js

@@ -0,0 +1,204 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { audit } from './core/engine.js';
+import { mutate } from './mutate/runner.js';
+import { c } from './report/colors.js';
+import { formatAudit, formatMutation } from './report/human.js';
+import { toJson } from './report/json.js';
+import { rules } from './rules/index.js';
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export function version() {
+    try {
+        return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const HELP = `honest-tests — find tests that can't fail.
+
+Usage
+  honest-tests audit [paths...]          Detect fake/weak tests (default: .)
+  honest-tests audit [paths] --mutate <file>
+                                         ...then mutation-check a source file
+  honest-tests mutate <file>             Mutation check only
+  honest-tests rules                     List rules
+  honest-tests init <claude|codex|cursor> Install the agent skill/rules into this repo
+
+Audit options
+  --json                 Machine-readable output (findings with file/line/rule/severity/evidence)
+  -v, --verbose          Show fix advice for each finding
+  --ignore <glob>        Ignore paths (repeatable), e.g. --ignore "fixtures/**"
+  --rule <id>            Only run these rules (repeatable)
+  --disable <id>         Skip these rules (repeatable)
+  --fail-on <level>      error (default) | warning | never
+
+Mutation options
+  --mutate <file>        Source file to mutate (with audit)
+  --test-cmd <cmd>       Test command (default: package.json "test" script, scoped to related tests).
+                         "{files}" is replaced with test files that import the target.
+  --root <dir>           Project root (default: nearest package.json above the target)
+  --max-mutants <n>      Cap on mutants to run (default 100)
+  --timeout <ms>         Per-run timeout (default: 4x baseline + 5s)
+  --min-score <0-100>    Exit 1 if mutation score is below this (default: 0, report only)
+
+Suppress a finding:   // honest-tests-disable-next-line <rule-id>`;
+export async function run(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                json: { type: 'boolean' },
+                verbose: { type: 'boolean', short: 'v' },
+                ignore: { type: 'string', multiple: true },
+                rule: { type: 'string', multiple: true },
+                disable: { type: 'string', multiple: true },
+                'fail-on': { type: 'string' },
+                mutate: { type: 'string' },
+                'test-cmd': { type: 'string' },
+                root: { type: 'string' },
+                'max-mutants': { type: 'string' },
+                timeout: { type: 'string' },
+                'min-score': { type: 'string' },
+                dir: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e.message}\n\n${HELP}\n`);
+        return 2;
+    }
+    const { values: v, positionals } = parsed;
+    if (v.version) {
+        io.stdout(version() + '\n');
+        return 0;
+    }
+    const [command, ...rest] = positionals;
+    if (v.help || !command) {
+        io.stdout(HELP + '\n');
+        return command || v.help ? 0 : 2;
+    }
+    if (command === 'rules') {
+        if (v.json)
+            io.stdout(JSON.stringify(rules.map(({ id, severity, description, fix }) => ({ id, severity, description, fix })), null, 2) + '\n');
+        else
+            for (const r of rules)
+                io.stdout(`${c.bold(r.id.padEnd(26))} ${r.severity.padEnd(8)} ${r.description}\n`);
+        return 0;
+    }
+    if (command === 'init')
+        return init(rest[0], v.dir ?? io.cwd, io);
+    if (command !== 'audit' && command !== 'mutate') {
+        io.stderr(`Unknown command "${command}".\n\n${HELP}\n`);
+        return 2;
+    }
+    const unknownRules = [...(v.rule ?? []), ...(v.disable ?? [])].filter((id) => !rules.some((r) => r.id === id));
+    if (unknownRules.length) {
+        io.stderr(`Unknown rule(s): ${unknownRules.join(', ')}. Run "honest-tests rules".\n`);
+        return 2;
+    }
+    const failOn = v['fail-on'] ?? 'error';
+    if (!['error', 'warning', 'never'].includes(failOn)) {
+        io.stderr(`--fail-on must be error, warning or never.\n`);
+        return 2;
+    }
+    let auditResult = null;
+    let exit = 0;
+    if (command === 'audit') {
+        auditResult = audit({ paths: rest, cwd: io.cwd, ignore: v.ignore, only: v.rule, disable: v.disable }, version());
+        const { error, warning } = auditResult.summary;
+        if ((failOn === 'error' && error > 0) || (failOn === 'warning' && error + warning > 0))
+            exit = 1;
+        if (!v.json)
+            io.stdout(formatAudit(auditResult, { verbose: v.verbose }) + '\n');
+    }
+    const target = command === 'mutate' ? rest[0] : v.mutate;
+    if (command === 'mutate' && !target) {
+        io.stderr('Usage: honest-tests mutate <source-file>\n');
+        return 2;
+    }
+    let mutation = null;
+    if (target) {
+        const num = (s) => (s === undefined ? undefined : Number(s));
+        const showProgress = !v.json && io.progress;
+        try {
+            mutation = await mutate({
+                target,
+                cwd: io.cwd,
+                root: v.root,
+                testCmd: v['test-cmd'],
+                maxMutants: num(v['max-mutants']),
+                timeoutMs: num(v.timeout),
+                onProgress: showProgress
+                    ? (done, total, r) => io.stderr(`\r  mutating ${target}: ${done}/${total} ${r.status === 'survived' ? c.red('survived') : c.green(r.status)}   `)
+                    : undefined,
+            });
+            if (showProgress)
+                io.stderr('\r\x1b[2K');
+        }
+        catch (e) {
+            if (showProgress)
+                io.stderr('\n');
+            const err = e;
+            io.stderr(c.red(`Mutation check failed: ${err.message}\n`));
+            if (err.output)
+                io.stderr(c.dim(excerpt(err.output)) + '\n');
+            return 2;
+        }
+        if (!v.json)
+            io.stdout(formatMutation(mutation) + '\n');
+        const minScore = num(v['min-score']) ?? 0;
+        if (mutation.score < minScore)
+            exit = 1;
+    }
+    if (v.json)
+        io.stdout(toJson(auditResult, mutation) + '\n');
+    return exit;
+}
+/** First and last lines of a test run: the error is usually at the top, the summary at the bottom. */
+export function excerpt(output, headLines = 20, tailLines = 20) {
+    const lines = output.replace(/\n{3,}/g, '\n\n').trimEnd().split('\n');
+    if (lines.length <= headLines + tailLines)
+        return lines.join('\n');
+    return [...lines.slice(0, headLines), `  … ${lines.length - headLines - tailLines} lines …`, ...lines.slice(-tailLines)].join('\n');
+}
+const MARK_START = '<!-- honest-tests:start -->';
+const MARK_END = '<!-- honest-tests:end -->';
+function init(target, dir, io) {
+    const base = resolve(io.cwd, dir);
+    switch (target) {
+        case 'claude': {
+            const dest = join(base, '.claude', 'skills', 'honest-tests');
+            cpSync(join(PACKAGE_ROOT, 'skills', 'honest-tests'), dest, { recursive: true });
+            io.stdout(`Installed skill → ${dest}\nClaude Code will pick it up automatically. Try: "audit my tests with honest-tests".\n`);
+            return 0;
+        }
+        case 'codex': {
+            const snippet = readFileSync(join(PACKAGE_ROOT, 'integrations', 'codex', 'AGENTS.md'), 'utf8').trim();
+            const dest = join(base, 'AGENTS.md');
+            const block = `${MARK_START}\n${snippet}\n${MARK_END}`;
+            let content = existsSync(dest) ? readFileSync(dest, 'utf8') : '';
+            const re = new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`);
+            content = re.test(content) ? content.replace(re, block) : (content ? content.trimEnd() + '\n\n' : '') + block + '\n';
+            writeFileSync(dest, content);
+            io.stdout(`Added honest-tests section → ${dest}\n`);
+            return 0;
+        }
+        case 'cursor': {
+            const destDir = join(base, '.cursor', 'rules');
+            mkdirSync(destDir, { recursive: true });
+            cpSync(join(PACKAGE_ROOT, 'integrations', 'cursor', 'honest-tests.mdc'), join(destDir, 'honest-tests.mdc'));
+            io.stdout(`Installed rule → ${join(destDir, 'honest-tests.mdc')}\n`);
+            return 0;
+        }
+        default:
+            io.stderr('Usage: honest-tests init <claude|codex|cursor> [--dir <repo>]\n');
+            return 2;
+    }
+}

package/integrations/codex/AGENTS.md

@@ -0,0 +1,20 @@
+## Testing: honest tests only
+
+A test is honest only if it **fails when the behavior it names is broken**. When writing or changing tests:
+
+- Never weaken an assertion, change an expected value, add `.skip`, or wrap an assertion in `try/catch` to make a test pass. When a test fails, first assume the code is wrong.
+- Expected values must come from a spec or a hand calculation, never from re-running the code under test (`expect(f(x)).toBe(f(x))`) or copying its output unverified.
+- Never mock the module under test. Mock only boundaries (network, DB, clock, randomness, filesystem).
+- Assert on what the unit returns or changes, not on what a mock was configured to return. Use mocks for interaction checks (`toHaveBeenCalledWith`). Never assert on a literal the test just built (`const p = { a: 1 }; expect(p.a).toBe(1)`) — pass it through the unit.
+- Every test asserts something specific: exact values over `toBeDefined()`/`toBeTruthy()`; no snapshot-only tests; `await` every `.resolves`/`.rejects`; errors via `expect(() => f()).toThrow(Type)`.
+- Cover boundaries (`>=` vs `>`), empty inputs, and error paths.
+- Never commit `.only`.
+
+Before reporting that tests are done, run and fix:
+
+```bash
+npx @mintwork/honest-tests audit <test files>    # must report 0 errors
+npx @mintwork/honest-tests mutate <source file>  # report the mutation score; add tests for surviving mutants
+```
+
+To audit an existing suite: run `npx @mintwork/honest-tests audit . --json`, verify each finding by reading the test (confirmed / false-positive / accepted), prove key findings with `npx @mintwork/honest-tests mutate <file>`, then report "N of M tests can't fail" with the confirmed findings and surviving mutants. Do not edit files during an audit unless asked.

package/integrations/cursor/honest-tests.mdc

@@ -0,0 +1,24 @@
+---
+description: Write and audit tests that actually verify behavior (no fake tests). Apply when writing, editing, or reviewing test files.
+globs: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/test_*.py", "**/*_test.py"]
+alwaysApply: false
+---
+
+# Honest tests
+
+A test is honest only if it **fails when the behavior it names is broken**.
+
+Rules:
+- Never weaken an assertion, change an expected value, `.skip` a test, or wrap an assertion in `try/catch` to get green. When a test fails, first suspect the code.
+- Expected values come from a spec or hand calculation — never `expect(f(x)).toBe(f(x))`, never output copied unverified.
+- Never mock the module under test; mock only boundaries (network, DB, clock, randomness, fs).
+- Assert on what the unit produces, not on what a mock was told to return. Use mocks for `toHaveBeenCalledWith` checks. Never assert on a literal the test just built — pass it through the unit.
+- Prefer exact matchers over `toBeDefined()` / `toBeTruthy()`; no snapshot-only tests; `await` `.resolves`/`.rejects`; use `expect(() => f()).toThrow(Type)` for errors.
+- Test boundaries (`>=` vs `>`), empty inputs, and error paths. Never commit `.only`.
+
+Before saying tests are done, run in the terminal and fix all errors:
+
+```bash
+npx @mintwork/honest-tests audit <test files>
+npx @mintwork/honest-tests mutate <source file>   # add assertions for each surviving mutant
+```