@mintwork/honest-tests 0.0.0-stage → 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "honest-tests",
+  "owner": {
+    "name": "mintwork",
+    "url": "https://github.com/mintwork"
+  },
+  "metadata": {
+    "description": "Agent skill that stops AI coding agents from writing fake tests",
+    "version": "0.1.1"
+  },
+  "plugins": [
+    {
+      "name": "honest-tests",
+      "description": "Write and audit tests that actually verify behavior: detect fake tests and prove them with mutation testing",
+      "source": "./",
+      "strict": false,
+      "skills": [
+        "./skills/honest-tests"
+      ]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "honest-tests",
+  "displayName": "Honest Tests",
+  "version": "0.1.1",
+  "description": "Stop AI coding agents from writing fake tests. Skill + CLI that detects tests that can't fail and proves it with mutation testing.",
+  "author": {
+    "name": "mintwork",
+    "url": "https://github.com/mintwork"
+  },
+  "homepage": "https://github.com/mintwork/honest-tests#readme",
+  "repository": "https://github.com/mintwork/honest-tests",
+  "license": "MIT",
+  "keywords": [
+    "testing",
+    "test-smells",
+    "mutation-testing",
+    "vitest",
+    "jest"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.1] - 2026-11-14
+
+### Changed
+
+- The npm package is now **`@mintwork/honest-tests`**; run it with `npx @mintwork/honest-tests`. The unscoped
+  `honest-tests` package is deprecated and points here.
+- The repository moved to [github.com/mintwork/honest-tests](https://github.com/mintwork/honest-tests); old URLs
+  redirect.
+- Skill, plugin and editor-integration instructions use the new package name.
+
+## [0.1.0] - 2026-11-14
+
+First public release.
+
+### Added
+
+- **`honest-tests audit`**: static detection of JS/TS tests (vitest, jest, node:assert, chai) that
+  can't fail. It has 13 rules:
+  - errors: `no-assertions`, `tautological-assertion`, `asserts-on-mock`, `asserts-on-own-literal`,
+    `never-failing-assertion`, `swallowed-assertion`, `catch-only-assertion`,
+    `mocked-unit-under-test`, `focused-test`
+  - warnings: `excessive-mocking`, `snapshot-only`, `conditional-assertion`, `skipped-test`
+- **`asserts-on-own-literal`**: flags assertions on a literal the test just built, e.g.
+  `const p = { service: 's3' }; expect(p.service).toBe('s3')`. These are common in runtime "type
+  tests". The rule only fires when the value traces back purely to literals declared in the same
+  test, and that binding is never passed to code, mutated or reassigned.
+- **`honest-tests mutate <file>`**: built-in mutation testing. It works on a temporary copy of the
+  project and only runs the test files that reach the target, so the working tree is never touched,
+  even on Ctrl-C. Supports `--test-cmd`, `--max-mutants`, `--timeout` and `--min-score`.
+  `audit --mutate <file>` combines both checks in one run.
+- Output for humans and machines (`--json`, schema version 1), plus suppression comments
+  (`honest-tests-disable-next-line`, `-disable-line` and file-level `disable`) and `--fail-on`.
+- **Agent integrations**:
+  - Agent Skill (`skills/honest-tests`) with a smell catalog, a guide to writing honest tests, an
+    audit procedure and a mutation-testing reference.
+  - Claude Code plugin and marketplace, with `/honest-tests:audit` and `/honest-tests:mutate`.
+  - `honest-tests init claude|codex|cursor` installs the skill, an `AGENTS.md` section or a Cursor
+    rule.
+- `npm run demo:gif` renders the README demo from the real CLI output.
+
+### Known limitations
+
+- JS/TS only. The pytest adapter is planned; Python test files are reported as unsupported rather
+  than skipped silently.
+- `mutate` doesn't follow path-alias imports (`@/lib/x`) when picking related tests yet. Pass
+  `--test-cmd` in that case.
+- Mutants run one at a time.
+
+[0.1.1]: https://github.com/mintwork/honest-tests/releases/tag/v0.1.1
+[0.1.0]: https://github.com/mintwork/honest-tests/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 honest-tests contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# honest-tests
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/mintwork/honest-tests/actions/workflows/ci.yml/badge.svg)](https://github.com/mintwork/honest-tests/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@mintwork/honest-tests?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mintwork/honest-tests)
+[![npm downloads](https://img.shields.io/npm/dm/@mintwork/honest-tests?color=cb3837)](https://www.npmjs.com/package/@mintwork/honest-tests)
+[![node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](package.json)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/mintwork/honest-tests?style=social)](https://github.com/mintwork/honest-tests/stargazers)
+
+### Your AI wrote 200 tests. Many of them can't fail.
+
+**honest-tests** is an agent skill + CLI that stops Claude Code, Codex, Cursor and friends from writing
+fake tests — and proves which of your existing tests are fake by mutating your code and watching them
+stay green.
+
+<p align="center">
+  <img src="docs/demo.gif" width="1200" alt="honest-tests audit finds 11 of 15 tests that can't fail in a sample project; honest-tests mutate then shows 22 of 26 code changes survive the test suite, a 15.4% mutation score">
+</p>
+
+```bash
+npx @mintwork/honest-tests audit .                       # find tests that can't fail
+npx @mintwork/honest-tests mutate src/pricing.ts         # prove it: break the code, see who notices
+```
+
+---
+
+## The problem
+
+Ask an agent to "add tests" and you get a wall of green checkmarks. Look closer:
+
+```ts
+it('handles multiple items', () => {
+  const result = subtotal(items);
+  expect(result).toBe(result);                  // compares a value to itself
+});
+
+it('applies a percentage discount', () => {
+  applyDiscount(100, 10);                       // no assertion at all
+});
+
+it('computes the discounted price', () => {
+  try {
+    expect(applyDiscount(100, 20)).toBe(70);    // WRONG (it's 80) — and still passes
+  } catch {}
+});
+
+it('gives members free shipping', () => {
+  const qualifies = vi.fn().mockReturnValue(true);
+  expect(qualifies(10, true)).toBe(true);       // tests the mock it just configured
+});
+```
+
+Every one of these passes. Coverage goes up. Nothing is verified.
+
+## What honest-tests says about it
+
+```text
+$ npx @mintwork/honest-tests audit test/pricing.test.ts
+
+test/pricing.test.ts
+  16:5    error   Compares `result` to itself — this can never fail. tautological-assertion
+          │ expect(result).toBe(result);
+  25:1    error   Test "applies a percentage discount" has no assertions — it can only fail by crashing. no-assertions
+          │ it('applies a percentage discount', () => {
+  39:7    error   Assertion is inside a try/catch that swallows errors — when it fails, the catch eats the AssertionError and the test passes. swallowed-assertion
+          │ expect(applyDiscount(100, 20)).toBe(70); // wrong! but the catch hides it
+  53:5    error   Asserts on what mock `qualifies` returns (configured on line 52) — this verifies the mock, not your code. asserts-on-mock
+          │ expect(qualifies(10, true)).toBe(true);
+  ... 5 more
+
+7 of 10 tests can't fail (or don't test what they claim).
+1 file, 10 tests: 7 errors, 2 warnings. Run with --verbose for fixes.
+```
+
+Then the killer demo — **mutation testing, built in**. honest-tests flips operators, booleans,
+constants and return values in your source (on a temp copy), runs your tests, and shows every change
+nobody noticed:
+
+```text
+$ npx @mintwork/honest-tests mutate src/pricing.ts
+
+  22 mutants survived — your tests don't actually check these lines:
+
+  src/pricing.ts:15  if (percent < 0 || percent > 100) {
+      ✗ `<` → `<=`
+      ✗ `||` → `&&`
+      ✗ `>` → `>=`
+      ✗ `100` → `101`
+
+  src/pricing.ts:22  return isMember || total >= 50;
+      ✗ `>=` → `>`
+      ✗ `50` → `51`
+  ...
+
+  Mutation score: 15.4% (4 killed, 0 timed out, 22 survived of 26; baseline 0.5s)
+```
+
+## After: the same code, honest tests
+
+```ts
+it('takes the percentage off the amount', () => {
+  expect(applyDiscount(200, 25)).toBe(150);
+});
+
+it('accepts the 0% and 100% boundaries', () => {
+  expect(applyDiscount(200, 0)).toBe(200);
+  expect(applyDiscount(200, 100)).toBe(0);
+});
+
+it('rejects percentages outside 0..100', () => {
+  expect(() => applyDiscount(200, -1)).toThrow(RangeError);
+  expect(() => applyDiscount(200, 101)).toThrow(RangeError);
+});
+
+it('starts free shipping exactly at 50 for non-members', () => {
+  expect(qualifiesForFreeShipping(49.99, false)).toBe(false);
+  expect(qualifiesForFreeShipping(50, false)).toBe(true);
+});
+```
+
+```text
+$ npx @mintwork/honest-tests audit test && npx @mintwork/honest-tests mutate src/pricing.ts
+✓ 12 tests in 2 files: no fake tests found.
+  Mutation score: 100% (26 killed, 0 timed out, 0 survived of 26; baseline 0.5s)
+  ✓ Every mutation was caught. These tests actually test something.
+```
+
+Both projects live in [`fixtures/`](fixtures) — run `npm run demo:bad` / `npm run demo:good` yourself
+(`npm run demo:gif` re-renders the GIF above from the real CLI output).
+
+---
+
+## Install
+
+### Claude Code (plugin + skill)
+
+```text
+/plugin marketplace add mintwork/honest-tests
+/plugin install honest-tests@honest-tests
+```
+
+Or drop just the skill into a repo: `npx @mintwork/honest-tests init claude` (writes `.claude/skills/honest-tests/`).
+
+Then ask: *"write tests for src/cart.ts"* or *"audit my tests"* — or use the slash commands
+`/honest-tests:audit [path]` and `/honest-tests:mutate <file>`.
+
+### Codex
+
+```bash
+npx @mintwork/honest-tests init codex      # appends an honest-tests section to AGENTS.md (idempotent)
+```
+
+### Cursor
+
+```bash
+npx @mintwork/honest-tests init cursor     # writes .cursor/rules/honest-tests.mdc (auto-attaches to test files)
+```
+
+### Any agent / CI
+
+```bash
+npx @mintwork/honest-tests audit . --json                 # machine-readable findings
+npx @mintwork/honest-tests mutate src/x.ts --min-score 80 # fail CI below 80% mutation score
+```
+
+---
+
+## How the skill works
+
+The [skill](skills/honest-tests/SKILL.md) (Agent Skills format) teaches agents one rule — *a test is
+honest only if it fails when the behavior it names is broken* — plus two workflows:
+
+- **Writing tests:** name the bug each test catches, derive expected values independently, mock only
+  boundaries, cover boundaries and error paths, then self-audit with `audit` + `mutate` before saying
+  "done". Hard rules forbid the classic agent moves: weakening assertions to get green, changing the
+  expected value to match output, mocking the unit under test, `try/catch` around asserts.
+- **Auditing tests**, in phases, like a security audit:
+  1. **Detect** — `honest-tests audit --json` plus a manual pass for smells static analysis can't see.
+  2. **Verify** — every finding is opened and marked *confirmed / false-positive / accepted*; key
+     findings are proven with surviving mutants.
+  3. **Report** — "N of M tests can't fail", confirmed findings, surviving mutants, next steps.
+  4. **Fix** — only when asked; re-run and show the before/after mutation score.
+
+References the agent loads on demand: [test smell catalog](skills/honest-tests/references/test-smells.md),
+[writing honest tests](skills/honest-tests/references/writing-honest-tests.md),
+[audit procedure](skills/honest-tests/references/audit-procedure.md),
+[mutation testing](skills/honest-tests/references/mutation-testing.md).
+
+## Rules
+
+| Rule | Severity | Catches |
+| --- | --- | --- |
+| `no-assertions` | error | Test body never asserts — passes unless it crashes |
+| `tautological-assertion` | error | `expect(x).toBe(x)`, `expect(f(1)).toBe(f(1))`, `expect(true).toBe(true)`, `toHaveLength(list.length)` |
+| `asserts-on-mock` | error | Asserting on the return value of a mock the test configured (`vi.fn().mockReturnValue`, `spyOn`, `vi.mocked`, `.mock.results`) |
+| `asserts-on-own-literal` | error | Asserting on a literal the test just built: `const p = { service: 's3' }; expect(p.service).toBe('s3')` — common in runtime "type tests" |
+| `never-failing-assertion` | error | `expect(x).toBeTruthy` (never called), bare `expect(x)`, un-awaited `.resolves`/`.rejects`, `typeof x` "defined", `length >= 0`, `{}` truthy |
+| `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')` inside `cart.test.ts`; spying on and replacing the unit's own exports |
+| `focused-test` | error | `.only`, `fit`, `fdescribe` left in |
+| `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` |
+
+`npx @mintwork/honest-tests rules` prints the list. Suppress a deliberate case with a reason:
+
+```ts
+// honest-tests-disable-next-line no-assertions -- smoke test: module must import cleanly
+it('loads', () => { require('../src/plugin'); });
+```
+
+(`honest-tests-disable-line <rule>` and file-level `/* honest-tests-disable <rule> */` also work.)
+
+## Mutation check
+
+| Operator | Example |
+| --- | --- |
+| binary | `>=` → `>`, `<` → `<=`, `===` → `!==`, `+` → `-`, `*` → `/` |
+| logical | `&&` ↔ `\|\|` |
+| assignment | `+=` ↔ `-=` |
+| boolean | `true` ↔ `false` |
+| negation | `!x` → `x` |
+| number | `50` → `51`, `0` → `1` |
+| condition | `if (c)` → `if (true)` / `if (false)` |
+| return | `return x` → `return undefined` |
+
+**Safe by design:** the project is copied to a temp dir (`node_modules` symlinked), mutants are written
+only to the copy and restored after every run, and the copy is removed at the end — even on Ctrl-C. A red
+baseline aborts the run. Only test files that import the target — directly or through other local
+modules — are run (vitest/jest), once and with coverage off, so it's fast: 26 mutants in ~12s on the
+fixture. Imports through path aliases (`@/lib/x`) aren't followed yet; pass `--test-cmd` if your tests
+reach the target that way.
+
+```text
+--test-cmd "<cmd>"   custom command; {files} expands to related test files
+--max-mutants <n>    cap (default 100)          --timeout <ms>   per-run timeout
+--min-score <0-100>  exit 1 below this score    --root <dir>     project root
+```
+
+## CLI reference
+
+```text
+honest-tests audit [paths...]   [--json] [-v] [--ignore <glob>] [--rule <id>] [--disable <id>]
+                                [--fail-on error|warning|never] [--mutate <file> ...]
+honest-tests mutate <file>      [--json] [--test-cmd <cmd>] [--max-mutants <n>] [--min-score <n>]
+honest-tests rules              [--json]
+honest-tests init <claude|codex|cursor> [--dir <repo>]
+```
+
+Exit codes: `0` clean, `1` findings at/above `--fail-on` (default `error`) or score below `--min-score`,
+`2` usage/runtime error. JSON output schema is documented in
+[audit-procedure.md](skills/honest-tests/references/audit-procedure.md#phase-1--detect).
+
+## Dogfooding
+
+honest-tests audits its own suite in CI (`npm run dogfood` → zero findings) and mutation-checks its own
+rules. While building v1, `mutate src/rules/asserts-on-mock.ts` scored **50%** against our first rule
+tests — the tool found the gaps in the tests for the tool. After adding the missing negative cases it's
+at 84%, and `never-failing-assertion.ts` is at 100%; the remaining survivors are near-equivalent mutants
+such as early-exit optimizations.
+
+## Roadmap
+
+- [ ] **pytest adapter** — the rule engine is language-neutral; an adapter only has to emit the
+      `TestFileModel` ([src/adapters/python](src/adapters/python/index.ts) documents the mapping)
+- [ ] Parallel mutant runs and per-test coverage mapping (run only tests that execute the mutated line)
+- [ ] SARIF output for GitHub code scanning; `--changed` mode for PR diffs
+- [ ] More rules: oracle copied from output, re-implemented algorithm in test, weak `toHaveBeenCalled()`
+- [ ] Mocha, node:test, Bun, Deno; Go and Rust adapters
+- [ ] GitHub Action with a PR comment: "this PR adds 12 tests, 4 can't fail"
+
+## Contributing
+
+PRs welcome — especially new rules with a bad/good fixture and pytest adapter work. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

package/commands/audit.md

@@ -0,0 +1,17 @@
+---
+description: Audit tests for fake/weak tests (detect → verify → report) using the honest-tests skill
+argument-hint: "[path] [--mutate <source-file>]"
+---
+
+Use the `honest-tests` skill to audit the tests in: $ARGUMENTS (default: the whole repo).
+
+Follow the skill's phased procedure exactly:
+
+1. **Detect** — run `npx @mintwork/honest-tests audit <path> --json` (add `--mutate <file>` if given), plus the manual
+   "beyond the detector" pass.
+2. **Verify** — open every finding, classify it as confirmed / false-positive / accepted with a one-line note.
+   Prove the important ones with surviving mutants (`npx @mintwork/honest-tests mutate <source-file>`).
+3. **Report** — use the report template from `references/audit-procedure.md`, leading with
+   "N of M tests can't fail" and the mutation score.
+
+Do not modify any files unless I ask you to fix the findings.

package/commands/mutate.md

@@ -0,0 +1,10 @@
+---
+description: Mutation-check a source file and explain which behaviors its tests don't actually verify
+argument-hint: "<source-file>"
+---
+
+Run `npx @mintwork/honest-tests mutate $ARGUMENTS --json` (it works on a temp copy; the working tree is not modified).
+
+Then, for every surviving mutant, explain in one line which behavior is untested and propose the exact
+assertion that would kill it (following `references/writing-honest-tests.md` from the `honest-tests` skill).
+Flag mutants you believe are equivalent, with a reason. Finish with the mutation score.

package/dist/adapters/index.d.ts

@@ -0,0 +1,3 @@
+import type { LanguageAdapter } from '../core/types.js';
+export declare const adapters: LanguageAdapter[];
+export declare function adapterFor(path: string): LanguageAdapter | undefined;

package/dist/adapters/index.js

@@ -0,0 +1,8 @@
+import { extname } from 'node:path';
+import { jsAdapter } from './js/index.js';
+import { pythonAdapter } from './python/index.js';
+export const adapters = [jsAdapter, pythonAdapter];
+export function adapterFor(path) {
+    const ext = extname(path).toLowerCase();
+    return adapters.find((a) => a.extensions.includes(ext));
+}

package/dist/adapters/js/ast.d.ts

@@ -0,0 +1,24 @@
+import type * as t from '@babel/types';
+import type { ExprInfo } from '../../core/types.js';
+export type Node = t.Node;
+export declare function parseSource(path: string, source: string): t.File;
+/**
+ * Depth-first walk. `visit` receives the node and its ancestors (outermost first).
+ * Return `false` from `visit` to skip the node's children.
+ */
+export declare function walk(root: Node, visit: (node: Node, ancestors: Node[]) => boolean | void, ancestors?: Node[]): void;
+export declare function textOf(source: string, node: Node): string;
+export declare function normalize(text: string): string;
+export declare function normText(source: string, node: Node): string;
+/** Strip wrappers that don't change runtime meaning for our purposes. */
+export declare function unwrap(node: Node): Node;
+export declare function isCall(node: Node | null | undefined): node is t.CallExpression | t.OptionalCallExpression;
+export declare function isMember(node: Node | null | undefined): node is t.MemberExpression | t.OptionalMemberExpression;
+export declare function isFunction(node: Node | null | undefined): node is t.ArrowFunctionExpression | t.FunctionExpression;
+export declare function propName(member: t.MemberExpression | t.OptionalMemberExpression): string | null;
+export declare function stringValue(node: Node | undefined): string | null;
+/** Root identifier name of a member/call chain: `vi.fn().mockReturnValue(1)` -> `vi`. */
+export declare function chainRoot(node: Node): Node;
+/** All member property names along a call chain, outermost last. */
+export declare function chainProps(node: Node): string[];
+export declare function describeExpr(source: string, raw: Node): ExprInfo;

package/dist/adapters/js/ast.js

@@ -0,0 +1,199 @@
+import { parse } from '@babel/parser';
+import { extname } from 'node:path';
+export function parseSource(path, source) {
+    const ext = extname(path).toLowerCase();
+    const plugins = ['decorators-legacy', 'importAttributes'];
+    if (['.ts', '.mts', '.cts'].includes(ext))
+        plugins.push('typescript');
+    else if (ext === '.tsx')
+        plugins.push('typescript', 'jsx');
+    else
+        plugins.push('jsx');
+    return parse(source, {
+        sourceType: 'unambiguous',
+        plugins,
+        errorRecovery: true,
+        allowReturnOutsideFunction: true,
+        allowAwaitOutsideFunction: true,
+        allowImportExportEverywhere: true,
+        allowUndeclaredExports: true,
+    });
+}
+const SKIP_KEYS = new Set([
+    'type',
+    'loc',
+    'start',
+    'end',
+    'range',
+    'extra',
+    'leadingComments',
+    'trailingComments',
+    'innerComments',
+    'comments',
+    'tokens',
+]);
+function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.type === 'string';
+}
+/**
+ * Depth-first walk. `visit` receives the node and its ancestors (outermost first).
+ * Return `false` from `visit` to skip the node's children.
+ */
+export function walk(root, visit, ancestors = []) {
+    if (visit(root, ancestors) === false)
+        return;
+    ancestors.push(root);
+    for (const key of Object.keys(root)) {
+        if (SKIP_KEYS.has(key))
+            continue;
+        const value = root[key];
+        if (Array.isArray(value)) {
+            for (const child of value)
+                if (isNode(child))
+                    walk(child, visit, ancestors);
+        }
+        else if (isNode(value)) {
+            walk(value, visit, ancestors);
+        }
+    }
+    ancestors.pop();
+}
+export function textOf(source, node) {
+    return source.slice(node.start ?? 0, node.end ?? 0);
+}
+export function normalize(text) {
+    return text
+        .replace(/\s+/g, ' ')
+        .replace(/\s*([(),.[\]{}])\s*/g, '$1')
+        .replace(/;+$/, '')
+        .trim();
+}
+export function normText(source, node) {
+    return normalize(textOf(source, node));
+}
+/** Strip wrappers that don't change runtime meaning for our purposes. */
+export function unwrap(node) {
+    let cur = node;
+    for (;;) {
+        switch (cur.type) {
+            case 'TSAsExpression':
+            case 'TSSatisfiesExpression':
+            case 'TSNonNullExpression':
+            case 'TSTypeAssertion':
+            case 'ParenthesizedExpression':
+            case 'AwaitExpression':
+                cur = cur.expression ?? cur.argument;
+                continue;
+            default:
+                return cur;
+        }
+    }
+}
+export function isCall(node) {
+    return !!node && (node.type === 'CallExpression' || node.type === 'OptionalCallExpression');
+}
+export function isMember(node) {
+    return !!node && (node.type === 'MemberExpression' || node.type === 'OptionalMemberExpression');
+}
+export function isFunction(node) {
+    return !!node && (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression');
+}
+export function propName(member) {
+    const p = member.property;
+    if (!member.computed && p.type === 'Identifier')
+        return p.name;
+    if (p.type === 'StringLiteral')
+        return p.value;
+    return null;
+}
+export function stringValue(node) {
+    if (!node)
+        return null;
+    if (node.type === 'StringLiteral')
+        return node.value;
+    if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
+        return node.quasis.map((q) => q.value.cooked ?? q.value.raw).join('');
+    }
+    return null;
+}
+/** Root identifier name of a member/call chain: `vi.fn().mockReturnValue(1)` -> `vi`. */
+export function chainRoot(node) {
+    let cur = node;
+    for (;;) {
+        if (isCall(cur))
+            cur = cur.callee;
+        else if (isMember(cur))
+            cur = cur.object;
+        else
+            return cur;
+    }
+}
+/** All member property names along a call chain, outermost last. */
+export function chainProps(node) {
+    const props = [];
+    let cur = node;
+    for (;;) {
+        if (isCall(cur))
+            cur = cur.callee;
+        else if (isMember(cur)) {
+            const name = propName(cur);
+            if (name)
+                props.unshift(name);
+            cur = cur.object;
+        }
+        else
+            return props;
+    }
+}
+export function describeExpr(source, raw) {
+    const node = unwrap(raw);
+    const text = normText(source, node);
+    switch (node.type) {
+        case 'NumericLiteral':
+        case 'BigIntLiteral':
+            return { text, kind: 'literal', literalValue: Number(node.value) };
+        case 'StringLiteral':
+            return { text, kind: 'literal', literalValue: node.value };
+        case 'BooleanLiteral':
+            return { text, kind: 'literal', literalValue: node.value };
+        case 'NullLiteral':
+            return { text, kind: 'literal', literalValue: null };
+        case 'RegExpLiteral':
+            return { text, kind: 'object' };
+        case 'TemplateLiteral':
+            return node.expressions.length === 0
+                ? { text, kind: 'literal', literalValue: stringValue(node) ?? '' }
+                : { text, kind: 'other' };
+        case 'Identifier':
+            if (node.name === 'undefined')
+                return { text, kind: 'literal', literalValue: undefined, isUndefinedLiteral: true };
+            return { text, kind: 'identifier' };
+        case 'UnaryExpression':
+            if (node.operator === 'typeof')
+                return { text, kind: 'typeof' };
+            if (node.operator === 'void')
+                return { text, kind: 'literal', literalValue: undefined, isUndefinedLiteral: true };
+            if ((node.operator === '-' || node.operator === '+') && node.argument.type === 'NumericLiteral') {
+                return { text, kind: 'literal', literalValue: Number(text) };
+            }
+            return { text, kind: 'other' };
+        case 'MemberExpression':
+        case 'OptionalMemberExpression':
+            return { text, kind: 'member' };
+        case 'CallExpression':
+        case 'OptionalCallExpression':
+            return { text, kind: 'call', calleeText: normText(source, node.callee) };
+        case 'ObjectExpression':
+            return { text, kind: 'object' };
+        case 'ArrayExpression':
+            return { text, kind: 'array' };
+        case 'ArrowFunctionExpression':
+        case 'FunctionExpression':
+        case 'ClassExpression':
+            return { text, kind: 'function' };
+        case 'NewExpression':
+            return { text, kind: 'new' };
+        default:
+            return { text, kind: 'other' };
+    }
+}