@mintwork/honest-tests 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@mintwork/honest-tests",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Stop AI coding agents from writing fake tests. An agent skill + CLI that detects tests that can't fail, and proves it with mutation testing.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mintwork/honest-tests.git"
+  },
+  "homepage": "https://github.com/mintwork/honest-tests#readme",
+  "bugs": {
+    "url": "https://github.com/mintwork/honest-tests/issues"
+  },
+  "type": "module",
+  "bin": {
+    "honest-tests": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "commands",
+    "integrations",
+    ".claude-plugin",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "dogfood": "node dist/cli.js audit test",
+    "demo:bad": "node dist/cli.js audit fixtures/bad-project --mutate fixtures/bad-project/src/pricing.ts",
+    "demo:good": "node dist/cli.js audit fixtures/good-project --mutate fixtures/good-project/src/pricing.ts",
+    "demo:gif": "npm run build && node scripts/demo-gif.mjs",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "testing",
+    "test-smells",
+    "mutation-testing",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cursor",
+    "ai",
+    "vitest",
+    "jest",
+    "lint"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.29.0"
+  },
+  "devDependencies": {
+    "@babel/types": "^7.29.0",
+    "@types/node": "^22.20.5",
+    "playwright-core": "^1.65.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/honest-tests/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: honest-tests
+description: Write and audit tests that actually verify behavior instead of tests that merely pass. Use when writing, generating, reviewing or fixing unit tests (vitest, jest; pytest planned), when asked to "add tests", "increase coverage", "audit/review the tests", or before claiming a change is tested. Detects fake tests (tautological assertions, no assertions, asserting on mocks you configured or on literals the test just built, mocking the unit under test, snapshot-only tests, try/catch that swallows failures, assertions that can never fail, leftover .only/.skip) and proves weak tests with lightweight mutation testing via the `honest-tests` CLI.
+license: MIT
+metadata:
+  version: "0.1.1"
+  cli: "npx @mintwork/honest-tests"
+---
+
+# Honest Tests
+
+A test is honest only if **it fails when the behavior it names is broken**. Everything in this skill
+serves that one rule. Green is not the goal; *a test that can go red for the right reason* is.
+
+AI-written test suites fail this rule in predictable ways: they assert that a value equals itself,
+assert on the return value of a mock they just configured, mock the very module under test, wrap
+assertions in `try/catch`, or never assert at all. They pass forever and protect nothing.
+
+Use this skill in two modes:
+
+- **Writing tests** — follow the rules below, then self-audit before you report done.
+- **Auditing tests** — run the phased procedure: detect → verify → report (→ fix, if asked).
+
+## Hard rules (never break these)
+
+1. **Never weaken an assertion to make a test pass.** If a test fails, first assume the *code* may be
+   wrong. Changing `toBe(70)` to `toBe(80)` because the output was 80 is only allowed after you have
+   independently confirmed 80 is correct (spec, hand calculation, domain rule).
+2. **The expected value must come from somewhere other than the code under test.** Hand-computed
+   literals, fixtures, or a spec — never `expect(fn(x)).toBe(fn(x))` and never a value copied from a
+   run of the code you are testing without checking it.
+3. **Never mock the unit under test.** Mock only its boundaries (network, DB, clock, randomness,
+   filesystem, other services). If you must mock half the module to test it, say so — that is a design
+   smell to report, not hide.
+4. **Assert on what the unit produces**, not on what a mock was told to return. Mocks are for
+   *isolating* the unit and for *interaction* checks (`toHaveBeenCalledWith`), not for producing the
+   value you assert on. The same goes for literals the test built itself: `const p = { service: 's3' };
+   expect(p.service).toBe('s3')` checks nothing. Types don't exist at runtime — check types with
+   `expectTypeOf` / `tsd` / `// @ts-expect-error`, and check behavior by passing the literal *through* the unit.
+5. **No assertion inside `try/catch`.** Use `expect(() => f()).toThrow(...)` /
+   `await expect(p).rejects.toThrow(...)`.
+6. **Every test asserts something specific.** "Does not throw", `toBeDefined()`, `toBeTruthy()` and a
+   bare snapshot are almost never the real contract. Assert the exact value, field, or call.
+7. **Never leave `.only` / `.skip` / `xit`** in committed code. Use `it.todo('...')` for planned tests.
+8. **Coverage is not verification.** A line executed by a test is not a line checked by a test.
+
+Detailed patterns and examples: [references/writing-honest-tests.md](references/writing-honest-tests.md).
+
+## Mode 1 — Writing tests
+
+Before writing each test, answer in one line: *"Which bug would make this test fail?"* If you can't
+name one, don't write the test.
+
+For each unit:
+
+1. List its behaviors: normal results, **boundaries** (0, empty, max, `>=` vs `>`), error paths, and
+   side effects (calls it must make).
+2. Write one focused test per behavior with a hand-derived expected value. Name the test after the
+   behavior (`'charges 5 below the free-shipping threshold'`), not the function (`'works'`).
+3. Mock only boundaries. Prefer real collaborators when they are cheap and deterministic.
+4. Self-audit when done (both commands are safe; neither modifies your files):
+
+   ```bash
+   npx @mintwork/honest-tests audit <test files or dir>
+   npx @mintwork/honest-tests mutate <source file you just tested>
+   ```
+
+5. Fix every `error` finding. For each **surviving mutant**, either add the missing assertion (usually
+   a boundary or an exact value) or explain why the mutant is equivalent. Report the final mutation
+   score to the user.
+
+## Mode 2 — Auditing tests (phased)
+
+Run the phases in order. Do not skip Phase 2: unverified findings erode trust.
+
+### Phase 1 — Detect
+
+```bash
+npx @mintwork/honest-tests audit <path> --json > honest-tests.json
+```
+
+The JSON contains `findings[]` with `ruleId`, `severity`, `file`, `line`, `column`, `test`, `message`,
+`evidence`, `fix`, plus a `summary`. If the CLI cannot be installed, use the manual grep checklist in
+[references/audit-procedure.md](references/audit-procedure.md#manual-fallback).
+
+Also look for smells the detector does not catch yet (see the "beyond the detector" list in
+[references/test-smells.md](references/test-smells.md)), e.g. expected values copied from output,
+tests that re-implement the algorithm, or assertions on irrelevant details.
+
+### Phase 2 — Verify each finding
+
+For every finding, open the file at `line`, read the whole test, and classify it:
+
+- **confirmed** — the test cannot fail for the bug its name implies.
+- **false-positive** — the detector misread the code (explain why in one sentence).
+- **accepted** — technically a smell but intentional and harmless (e.g. a deliberate smoke test).
+  Suggest `// honest-tests-disable-next-line <rule-id>` with a reason.
+
+Prove the important ones. The strongest proof is a mutation that survives:
+
+```bash
+npx @mintwork/honest-tests mutate <source file the test targets> --json
+```
+
+Surviving mutants are concrete, line-level evidence: "changing `>=` to `>` on line 22 does not fail any
+test". Mutation runs on a temporary copy of the project; your working tree is never modified. See
+[references/mutation-testing.md](references/mutation-testing.md) for reading results and equivalent
+mutants.
+
+Per-rule verification notes: [references/test-smells.md](references/test-smells.md).
+
+### Phase 3 — Report
+
+Lead with the headline number, then confirmed findings grouped by severity, then surviving mutants.
+Use the template in [references/audit-procedure.md](references/audit-procedure.md#report-template).
+When the user wants machine-readable output, return the verified findings as JSON with an added
+`verdict` (`confirmed` | `false-positive` | `accepted`) and `note` per finding.
+
+### Phase 4 — Fix (only when asked)
+
+Rewrite confirmed findings into honest tests following Mode 1. Re-run `audit` and `mutate`, and show the
+before/after mutation score. Never "fix" a finding by deleting the assertion or adding a disable comment
+without the user's agreement.
+
+## Rules detected by the CLI
+
+| Rule | Severity | Catches |
+| --- | --- | --- |
+| `no-assertions` | error | Test body never asserts |
+| `tautological-assertion` | error | `expect(x).toBe(x)`, `expect(true).toBe(true)`, expected derived from actual |
+| `asserts-on-mock` | error | Asserting on the return value of a mock the test configured |
+| `asserts-on-own-literal` | error | Asserting on a literal the test just built (`const p = { service: 's3' }; expect(p.service).toBe('s3')`) — typical of runtime "type tests" |
+| `never-failing-assertion` | error | `expect(x).toBeTruthy` (no call), bare `expect(x)`, un-awaited `.resolves`, `typeof x` "defined", `length >= 0` |
+| `swallowed-assertion` | error | Assertion inside `try` whose `catch` doesn't rethrow |
+| `catch-only-assertion` | error | Assertions only in `catch` — passes when nothing throws |
+| `mocked-unit-under-test` | error | `vi.mock('./cart')` in `cart.test.ts`; spying on and replacing the unit's exports |
+| `focused-test` | error | `.only`, `fit`, `fdescribe` |
+| `excessive-mocking` | warning | 5+ module mocks in one file |
+| `snapshot-only` | warning | The only assertion is a snapshot |
+| `conditional-assertion` | warning | Assertion behind `if`/`&&`/ternary |
+| `skipped-test` | warning | `.skip`, `xit`, `xdescribe` |

package/skills/honest-tests/references/audit-procedure.md

@@ -0,0 +1,128 @@
+# Audit procedure (detailed)
+
+## Phase 0 — Scope
+
+- Identify the test runner (`package.json` scripts, `vitest.config.*`, `jest.config.*`) and the test
+  directories. Confirm the suite passes as-is: `npm test`. Mutation results are meaningless on a red
+  suite.
+- Agree on scope with the user if the repo is large: a package, a directory, or the files touched by a
+  PR (`git diff --name-only main... | grep -E '\.(test|spec)\.'`).
+
+## Phase 1 — Detect
+
+```bash
+npx @mintwork/honest-tests audit <paths...> --json > honest-tests.json
+# useful flags
+#   --ignore "fixtures/**"     skip paths (repeatable)
+#   --rule <id> / --disable <id>
+#   --fail-on warning|never     exit code policy (default: error)
+```
+
+Output shape (`schemaVersion: 1`):
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "tool": "honest-tests",
+  "version": "0.1.0",
+  "filesScanned": 3,
+  "testsScanned": 14,
+  "summary": { "error": 12, "warning": 3, "info": 0, "suspiciousTests": 10 },
+  "findings": [
+    {
+      "ruleId": "swallowed-assertion",
+      "severity": "error",
+      "file": "test/pricing.test.ts",
+      "line": 39,
+      "column": 7,
+      "test": "computes the discounted price",
+      "message": "Assertion is inside a try/catch that swallows errors ...",
+      "evidence": "expect(applyDiscount(100, 20)).toBe(70);",
+      "fix": "Remove the try/catch. For expected errors use ..."
+    }
+  ],
+  "unsupported": [],   // test files in languages not yet supported (e.g. pytest)
+  "parseErrors": [],
+  "mutation": { ... }  // present when --mutate was used
+}
+```
+
+Then do a manual pass for the "beyond the detector" smells in `test-smells.md`.
+
+## Phase 2 — Verify
+
+For each finding:
+
+1. Open `file` at `line`; read the entire test and any helpers it calls.
+2. Check the per-rule "Verify" notes in `test-smells.md`.
+3. Assign a verdict: `confirmed`, `false-positive`, or `accepted`, with a one-sentence note.
+4. For high-impact findings, **prove** them:
+   - Run `npx @mintwork/honest-tests mutate <source-file>`; cite a surviving mutant on the relevant line.
+   - Or reason concretely: "If `applyDiscount` returned `amount` unchanged, this test would still pass
+     because the `catch` swallows the AssertionError."
+
+Never modify the user's source to prove a point; `mutate` works on a temp copy.
+
+Group duplicates: the same smell repeated across 30 tests is one finding with 30 locations.
+
+## Phase 3 — Report
+
+### Report template
+
+```markdown
+## Test honesty audit — <scope>
+
+**<N> of <M> tests can't fail** (or don't test what they claim). Mutation score for
+<file>: **<S>%** (<survived> of <tested> mutants survived).
+
+### Confirmed — errors
+| Test | Rule | Why it can't fail | Fix |
+| --- | --- | --- | --- |
+| `pricing.test.ts:39` "computes the discounted price" | swallowed-assertion | catch eats the AssertionError; the asserted value (70) is actually wrong | drop try/catch, expect 80 |
+
+### Confirmed — warnings
+...
+
+### Surviving mutants (untested behavior)
+- `pricing.ts:22` `>=` → `>` — no test checks the exact free-shipping threshold (50).
+- `pricing.ts:15` `100` → `101` — no test passes 101%.
+
+### False positives / accepted
+- `x.test.ts:12` no-assertions — smoke test for module import; accepted, added disable comment.
+
+### Recommended next steps
+1. ...
+```
+
+Machine-readable variant: the `findings` array from Phase 1 with two extra fields per finding:
+`"verdict": "confirmed" | "false-positive" | "accepted"` and `"note": "<one sentence>"`.
+
+## Phase 4 — Fix (only if asked)
+
+- Rewrite confirmed findings following `writing-honest-tests.md`.
+- Re-run `audit` (expect zero errors) and `mutate` (show before → after score).
+- If a fixed test now fails, you may have found a real bug — stop and report it rather than adjusting
+  the expectation.
+
+## Manual fallback
+
+Use this when the CLI cannot be installed.
+
+```bash
+# focused / skipped
+grep -rnE '\b(it|test|describe)\.(only|skip)\b|\b(fit|fdescribe|xit|xdescribe|xtest)\(' --include='*.test.*' --include='*.spec.*' .
+# constant / self comparisons
+grep -rnE 'expect\((true|false|[0-9]+|null|undefined)\)\.' --include='*.test.*' .
+grep -rnE 'expect\(([A-Za-z_.]+)\)\.(toBe|toEqual|toStrictEqual)\(\1\)' --include='*.test.*' .
+# matcher never called
+grep -rnE 'expect\(.*\)\.(not\.)?to[A-Za-z]+;\s*$' --include='*.test.*' .
+# try/catch in tests
+grep -rn -A3 'try {' --include='*.test.*' . | grep -n 'expect('
+# mocked unit: for each foo.test.ts, look for vi.mock/jest.mock of a path ending in /foo
+grep -rnE '(vi|jest)\.mock\(' --include='*.test.*' .
+# snapshot-only
+grep -rn 'toMatchSnapshot\|toMatchInlineSnapshot' --include='*.test.*' .
+```
+
+Then read each hit and apply Phase 2. For mutation without the CLI, change one operator in the source
+on a scratch copy, run the tests, and restore; repeat for the most important comparisons.

package/skills/honest-tests/references/mutation-testing.md

@@ -0,0 +1,68 @@
+# Mutation testing with honest-tests
+
+Static rules find tests that *look* fake. Mutation testing proves whether tests *are* fake: it makes
+small, deliberate bugs in the source and checks whether any test notices.
+
+```bash
+npx @mintwork/honest-tests mutate src/pricing.ts
+npx @mintwork/honest-tests audit test/ --mutate src/pricing.ts --json   # both, one JSON document
+```
+
+## What it does
+
+1. Finds the project root (nearest `package.json`) and the test files that import the target.
+2. Copies the project to a temp directory (`node_modules` is symlinked, `.git` is skipped).
+   **Your working tree is never written to.** The copy is deleted at the end, including on Ctrl-C.
+3. Runs the tests once unmutated (baseline). If they fail, it stops — fix the suite first.
+4. For each mutant: writes the mutated file into the copy, runs the tests, restores the file.
+   - tests fail → **killed** (good)
+   - tests pass → **survived** (the tests don't check this behavior)
+   - tests hang past the timeout → **timeout** (counted as killed)
+5. Reports the mutation score = (killed + timeout) / tested, and every survivor with its line.
+
+Default test command: the package's `test` script, scoped to the related test files for vitest/jest
+(`npm test --silent -- test/pricing.test.ts`). Override with `--test-cmd "pnpm vitest run {files}"`;
+`{files}` expands to the related test files.
+
+## Mutation operators
+
+| Operator | Example | A surviving mutant usually means |
+| --- | --- | --- |
+| binary | `>=` → `>`, `<` → `<=`, `===` → `!==`, `+` → `-`, `*` → `/` | boundary or arithmetic not checked with an exact value |
+| logical | `&&` → `\|\|` | only one side of the condition is ever exercised |
+| assignment | `+=` → `-=` | accumulation not checked |
+| boolean | `true` → `false` | the flag's effect is never asserted |
+| negation | `!x` → `x` | the negative branch is untested |
+| number | `50` → `51`, `0` → `1` | the constant's exact value (threshold, initial value) is unchecked |
+| condition | `if (c)` → `if (true)` / `if (false)` | one branch of the `if` is untested |
+| return | `return x` → `return undefined` | the return value is never asserted |
+
+Types, imports, string concatenation and `console.*`/logger calls are never mutated.
+
+## Reading survivors
+
+```
+pricing.ts:22  return isMember || total >= 50;
+    ✗ `>=` → `>`
+    ✗ `50` → `51`
+```
+
+Translate each survivor into the missing test:
+
+- `>=` → `>` survived on `total >= 50` → add `expect(qualifiesForFreeShipping(50, false)).toBe(true)`.
+- `return x` → `undefined` survived → some test calls the function but never checks the result.
+- `if (c)` → `if (false)` survived → no test enters that branch with an observable effect.
+
+## Equivalent mutants
+
+Some mutants don't change behavior (e.g. `i < len` → `i <= len` where the extra iteration is a no-op, or
+an `if` guard that only short-circuits an optimization). They can't be killed. When you judge a mutant
+equivalent, say so explicitly with a one-line reason — don't write a contrived test for it.
+
+## Practical tips
+
+- Target one file at a time: the one you just wrote tests for, or the riskiest module in the audit.
+- Cap long runs with `--max-mutants <n>`; use `--timeout <ms>` for slow suites.
+- Gate CI with `--min-score 80` (exit 1 below the threshold).
+- A score of 100% does not mean the tests are perfect; it means every simple mutation was caught.
+  A low score is very strong evidence that tests are fake.

package/skills/honest-tests/references/test-smells.md

@@ -0,0 +1,268 @@
+# Test smell catalog
+
+Each entry: what it looks like, why the test can't fail, the honest version, and how to verify a
+finding in Phase 2 (including known false positives).
+
+---
+
+## no-assertions (error)
+
+```ts
+it('applies a percentage discount', () => {
+  applyDiscount(100, 10); // runs the code, checks nothing
+});
+```
+
+**Why it's fake:** the test fails only if the code crashes. A wrong result passes.
+
+**Honest:**
+
+```ts
+it('takes 10% off', () => {
+  expect(applyDiscount(100, 10)).toBe(90);
+});
+```
+
+**Verify:** look for assertions hidden in helpers the detector didn't recognize. Calls named
+`expect*`, `assert*`, `verify*`, `check*`, `ensure*`, `should*`, `validate*`, and `.expect(...)` (supertest)
+already count. If the test genuinely asserts "does not throw", rewrite it as
+`expect(() => fn()).not.toThrow()` so the intent is explicit.
+
+---
+
+## tautological-assertion (error)
+
+```ts
+const result = subtotal(items);
+expect(result).toBe(result);           // value vs itself
+expect(format(5)).toEqual(format(5));  // recomputed with the same code
+expect(list).toHaveLength(list.length) // expected derived from actual
+expect(true).toBe(true);               // constant
+```
+
+**Why it's fake:** the outcome is decided before any code under test runs.
+
+**Honest:** compare against an independently known value: `expect(subtotal(items)).toBe(35)`.
+
+**Verify:** almost never a false positive. One exception: deliberately checking referential identity of
+a memoized call (`expect(memo(a)).toBe(memo(a))`) — that is a real check; mark as `accepted` and add a
+comment explaining it.
+
+---
+
+## asserts-on-mock (error)
+
+```ts
+const qualifies = vi.fn().mockReturnValue(true);
+expect(qualifies(10, true)).toBe(true); // you told it to return true
+```
+
+```ts
+vi.mocked(checkoutTotal).mockReturnValue(42);
+expect(checkoutTotal(items, 0, false)).toBe(42);
+```
+
+**Why it's fake:** it verifies the mocking library, not your code.
+
+**Honest:** call the *real* unit, which uses the mock as a dependency, and assert on what the unit
+produces. Assert on the mock only for interactions:
+
+```ts
+const repo = { find: vi.fn().mockResolvedValue({ name: 'Ada' }) };
+const svc = new UserService(repo);
+expect(await svc.greet(1)).toBe('Hello, Ada');
+expect(repo.find).toHaveBeenCalledWith(1);
+```
+
+**Verify:** confirm the asserted call is the mock itself (or a variable holding its direct result),
+not the real unit that happens to share a name.
+
+---
+
+## asserts-on-own-literal (error)
+
+```ts
+it('accepts an S3 provider config', () => {
+  const p: ProviderConfig = { service: 's3', region: 'eu-west-1' };
+  expect(p.service).toBe('s3');          // reads back the literal it just wrote
+  expect(p).toEqual({ service: 's3', region: 'eu-west-1' });
+});
+```
+
+**Why it's fake:** nothing from the code under test is involved — the value is built from literals in
+the test and read straight back. Common in "type tests": TypeScript types don't exist at runtime, so
+`const p: ProviderConfig = {...}` followed by `expect(p.service)` checks nothing the compiler hasn't
+already checked, and nothing at runtime at all.
+
+**Honest:** pass the literal through the code under test and assert on what comes out:
+
+```ts
+expect(resolveEndpoint({ service: 's3', region: 'eu-west-1' })).toBe('https://s3.eu-west-1.amazonaws.com');
+```
+
+For a genuinely type-level contract, use a compile-time check instead of a runtime assertion:
+`expectTypeOf(cfg).toMatchTypeOf<ProviderConfig>()`, `tsd`, or a `// @ts-expect-error` line that breaks
+the build when the type gets too loose.
+
+**Verify:** the rule only fires when the asserted value traces back purely to literals declared in the
+same test (object/array/template literals, operators, own-property reads) and the binding is never
+passed to a function, mutated or reassigned. Calls, `new`, imports, parameters and outer variables all
+stop it, as do reads that could reach the prototype (`{}.polluted`, `'x' in obj`, `toHaveProperty`) and
+custom matchers. If a hit is a deliberate sanity check of the test's own fixture data, delete it or
+mark it `accepted`.
+
+---
+
+## never-failing-assertion (error)
+
+```ts
+expect(config).toBeTruthy;                        // matcher never called
+expect(load());                                   // no matcher at all
+expect(load()).resolves.toBe(1);                  // not awaited/returned
+expect(typeof value).toBeDefined();               // typeof is always a string
+expect({ a: 1 }).toBeTruthy();                    // objects are always truthy
+expect(items.length).toBeGreaterThanOrEqual(0);   // lengths are never negative
+expect(new Cart()).toBeDefined();                 // constructors always return
+```
+
+**Why it's fake:** structurally unable to fail.
+
+**Honest:** call the matcher, `await` async matchers, assert the exact value
+(`expect(config).toEqual({ currency: 'USD' })`, `expect(items).toHaveLength(2)`).
+
+**Verify:** for un-awaited `.resolves/.rejects`, check whether the promise is returned or awaited via a
+variable later (`const p = expect(...).resolves...; await p;`) — that's a false positive.
+
+---
+
+## swallowed-assertion (error)
+
+```ts
+try {
+  expect(applyDiscount(100, 20)).toBe(70); // wrong, but...
+} catch {
+  // ...the AssertionError is caught here and the test passes
+}
+```
+
+**Why it's fake:** assertion failures are exceptions; catching them hides the failure.
+
+**Honest:** remove the `try/catch`. For error paths: `expect(() => f()).toThrow(RangeError)`.
+
+**Verify:** a `catch` that rethrows (`throw e`) or calls `fail()` is not flagged. If the catch logs and
+then re-asserts something, read carefully — usually still confirmed.
+
+---
+
+## catch-only-assertion (error, warning if other assertions exist)
+
+```ts
+try {
+  applyDiscount(100, 150);
+} catch (e) {
+  expect(e).toBeInstanceOf(RangeError); // never runs if nothing throws
+}
+```
+
+**Why it's fake:** if the code stops throwing, the catch is skipped and the test passes with zero
+assertions.
+
+**Honest:** `expect(() => applyDiscount(100, 150)).toThrow(RangeError)`. If you need the error object,
+add `expect.assertions(1)` at the top, or `expect.fail('should have thrown')` after the call.
+
+---
+
+## mocked-unit-under-test (error; warning for partial mocks)
+
+```ts
+// checkout.test.ts
+import { checkoutTotal } from '../src/checkout';
+vi.mock('../src/checkout'); // the thing under test is now a stub
+```
+
+```ts
+import * as cart from '../src/cart';
+vi.spyOn(cart, 'total').mockReturnValue(3); // replaces the real implementation
+```
+
+**Why it's fake:** every assertion runs against the mock. The real code never executes.
+
+**Honest:** import the real module; mock its dependencies (`vi.mock('../src/tax')`, HTTP clients,
+clocks).
+
+**Verify:** the detector matches the test file name (`cart.test.ts`) to the mocked module name
+(`./cart`, `../src/cart/index`). If the file is misnamed and actually tests something else, it's a
+false positive. Partial mocks (`importOriginal`/`requireActual`) are warnings — check whether the
+overridden export is the one being tested.
+
+---
+
+## excessive-mocking (warning)
+
+Five or more `vi.mock`/`jest.mock` calls in one file. Little real code remains under test; the test
+mostly checks that mocks are wired to each other. **Verify:** read what is left unmocked. If the unit
+is a thin orchestrator, recommend an integration test at the boundary instead.
+
+---
+
+## snapshot-only (warning)
+
+```ts
+it('renders the cart', () => {
+  expect(render(cart)).toMatchSnapshot();
+});
+```
+
+**Why it's weak:** the first run records whatever the code outputs — bugs included — and later runs
+only detect *change*, not *wrongness*. Agents also "fix" failing snapshots with `-u` reflexively.
+
+**Honest:** add at least one explicit assertion on what matters (`toContain('Total: $35')`), keep the
+snapshot as a change detector if useful.
+
+**Verify:** inline snapshots of small, reviewed values (`toMatchInlineSnapshot('true')`) are closer to a
+literal assertion; check whether the recorded value is actually correct.
+
+---
+
+## conditional-assertion (warning)
+
+```ts
+const cost = shippingCost(20, false);
+if (cost > 0) {
+  expect(cost).toBeGreaterThan(0);
+}
+```
+
+**Why it's weak:** when the guard is false the test passes with nothing checked.
+
+**Honest:** assert unconditionally on the exact value (`expect(shippingCost(20, false)).toBe(5)`).
+Split data-dependent branches into separate tests.
+
+---
+
+## focused-test (error) / skipped-test (warning)
+
+`.only`, `fit`, `fdescribe` silently disable every other test in the file. `.skip`, `xit`, `xdescribe`
+inflate the test count while verifying nothing. `skipIf/runIf` are not flagged.
+
+**Honest:** remove `.only`; fix or delete skipped tests, or convert to `it.todo('...')` with an issue.
+
+---
+
+## Beyond the detector (check these manually in Phase 1)
+
+These are common in AI-written suites but need judgement:
+
+- **Oracle copied from output** — the expected literal was pasted from a run of the code (`toBe(79.99)`
+  with no derivation). Ask: where did this number come from? Recompute it by hand.
+- **Re-implemented algorithm** — the test computes the expected value with the same formula as the code
+  (`expect(total).toBe(price * qty * (1 - d))`). Bugs in the formula are copied into the test.
+- **Asserting irrelevant details** — tests pass/fail on log text or call order nobody depends on, while
+  the business result is unchecked.
+- **Happy path only** — no boundary (`>=` vs `>`), empty input, or error path tests. Mutation testing
+  exposes these as surviving `>=` → `>` mutants.
+- **Test name lies** — `'rejects invalid input'` but no invalid input is passed.
+- **Weak matchers everywhere** — `toBeDefined()`, `toBeTruthy()`, `toHaveBeenCalled()` (without args),
+  `expect.anything()` where an exact value is known.
+- **Assertion-free type tests** — `const x: Foo = make()` relies on the type checker, which test runners
+  usually skip.