npm package: @manzoid2/test-intent-map
Description: Extract test metadata from any codebase and generate an interactive intent-map report with Claude Code
Latest version: 0.1.1

# @manzoid2/test-intent-map

Extract test metadata from any codebase and generate an interactive intent-map report with Claude Code.

**Two-part architecture:** the tool does the mechanical extraction (test discovery, source inference, line ranges), Claude Code does the intelligence (classifying each test by intent type, describing what it exercises, identifying failure modes). The output is an interactive HTML report with type filtering.

## Install

```
npm install -g @manzoid2/test-intent-map
```

Requires Node.js >= 18. No other system dependencies.

## Setup (required)

Add the following to your **global** Claude Code instructions (`~/.claude/CLAUDE.md`):

```markdown
## test-intent-map
Globally installed CLI (`npm i -g @manzoid2/test-intent-map`) for test suite analysis.
Run `test-intent-map` with no arguments to get the full analysis prompt — then follow those instructions.
```

This tells Claude Code the tool exists and how to use it. Without this, Claude won't know to invoke it.

## Usage

Open Claude Code in any repo and tell it to run `test-intent-map`. Claude will:

1. Run `test-intent-map` with no args to get the analysis prompt
2. Follow the prompt: run the tool with `--json` to extract test metadata
3. Read each test and its inferred source files
4. Classify every test by intent type (one of 8 categories)
5. Do a straggler check for tests the regex may have missed
6. Generate an interactive HTML report with filtering

### CLI reference

```
test-intent-map                        # Print the Claude Code analysis prompt
test-intent-map <path>                 # Extract test metadata, print summary
test-intent-map <path> --json <out>    # Also write JSON to file
test-intent-map --help                 # Show help
```

### Standalone extraction

You can run the extraction step directly for a quick preview:

```
test-intent-map ~/code/myproject --json /tmp/census.json
```

Prints a summary to stdout and writes structured JSON to the specified file.

## Supported Languages

| Language | Test patterns | Source inference |
|----------|--------------|-----------------|
| **Python** (pytest) | `test_*.py`, `*_test.py`, `class Test*`, `def test_*` | Import scanning, path convention, mock targets |
| **TypeScript/JavaScript** (Jest, Vitest, Mocha) | `*.test.ts`, `*.spec.ts`, `describe()`, `it()`, `test()` | Co-located files, `__tests__/` convention, import scanning |
| **Go** | `*_test.go`, `func Test*` | Same-package convention |

Adding a new language: implement the `LanguageProfile` interface (3 methods: `isTestFile`, `extractTests`, `inferSources`) and add it to the `LANGUAGES` array in `census.ts`.

## Test Type Taxonomy

Claude classifies each test into one of 8 intent types:

| Type | What it checks |
|------|---------------|
| **Wiring** | Dependencies are connected correctly |
| **Resilience** | System handles bad/missing/edge input |
| **Control Flow** | Branching and conditional logic |
| **Data Transform** | Input→output mapping correctness |
| **State Mgmt** | State changes correctly over time |
| **Contract** | Interface/schema compliance |
| **Log Presence** | Logging and observability behavior |
| **Side Effect** | External side effects occur correctly |

## JSON Schema

See `examples/sample-output.json` for the full schema. Key fields:

- **`tests[]`**: Every test with `testFile`, `className`, `methodName`, `line`, `endLine`, `inferredSources`
- **`testFiles[]`**: Each test file with `group` (directory-based), `inferredSources` with confidence levels
- **`github`**: Auto-detected from `.git/config` for constructing link URLs
- **`languages`**: Which languages were detected in the test suite

## HTML Report

The `templates/report.html` is a self-contained interactive template. Claude replaces the `DATA_PLACEHOLDER` with classified test data. Features:

- Color-coded type pills with click-to-filter (multi-select)
- Group header rows (by directory)
- GitHub links to test and source files
- Sticky header, hover highlights

## License

MIT