phantom-pr 0.4.19 → 0.5.1

package/README.md

@@ -1,41 +1,99 @@
 # phantom-pr
 
-`phantom-pr` is a CI-friendly CLI that opens PRs with passing Jest unit tests (bounded + deterministic, PR-only, no auto-merge).
+`phantom-pr` is a CI-friendly CLI that opens PRs with passing Jest/Vitest/pytest unit tests (bounded + deterministic, PR-only, no auto-merge).
 
-## Quick start
+## Installation
 
-### Using npm (PowerShell-friendly)
+```bash
+npm install -g phantom-pr
+```
 
-```powershell
-npm install
-npm run build
-npm run smoke
+Or use directly with npx:
+
+```bash
+npx phantom-pr --help
+```
+
+## Quick Start
+
+```bash
+# 1. Create config file
+cat > phantom-pr.yml << EOF
+baseBranch: main
+github:
+  owner: your-org
+  repo: your-repo
+  tokenEnvVar: GITHUB_TOKEN
+mode:
+  dryRun: true
+test:
+  command: npm test
+EOF
+
+# 2. Index your codebase
+phantom-pr index --root .
+
+# 3. Generate a plan
+phantom-pr plan --root .
+
+# 4. Run in dry mode first
+phantom-pr full --root . --dryRun
+```
+
+## Features
+
+### 🧪 Automatic Test Generation
+
+Generate unit tests for any file:
+
+```bash
+phantom-pr tests src/components/Button.tsx --local
 ```
 
-## What you get
+### 🔍 AST-Powered Analysis (New in 0.5.0)
+
+The test generator now uses AST analysis to:
+
+- **Detect branches** - Finds `if`, ternary, switch, and `&&`/`||` operators
+- **Identify effects** - Detects `useEffect`, `useLayoutEffect` with cleanup detection
+- **Map child components** - Finds components that need mocking
+- **Track external calls** - Identifies imported functions being called
+
+This enables smarter test generation with better branch coverage.
+
+### 🔄 Smart Retry with Error Parsing
 
-- **Strict TypeScript**: configured in `tsconfig.json`
-- **Minimal formatting**: Prettier config in `.prettierrc.json`
-- **CLI entrypoint**: `src/cli.ts` (prints `--help`, exits 0)
-- **Config MVP + status**: `phantom-pr status` loads `phantom-pr.yml` (or `--config <path>`) and prints resolved config + missing fields
-- **Full orchestration**: `phantom-pr full` is the “one safe unit of work” command for CI (caps + stale handling + deterministic target choice)
-- **Testability lane (MVP)**: `phantom-pr testability` can open a minimal “add data-testid” PR for React targets
-- **Tests lane**: `phantom-pr tests` generates tests, runs the test command, and writes `.phantom-pr/report.json`
-- **Folder structure**:
-  - `src/core/` (domain logic)
-  - `src/adapters/` (IO boundaries: git hosting, filesystem, process, network)
-  - `src/commands/` (CLI commands)
+When tests fail, the retry system now:
 
-## Scripts
+- Parses Jest/Vitest error output
+- Identifies specific error types (mock not called, assertion mismatch, import errors)
+- Generates targeted fix suggestions
+- Creates focused retry prompts
 
-- **build**: `tsc` compile to `dist/`
-- **test**: unit tests for the CLI itself (`node --test tests`)
-- **lint**: typecheck-only (`tsc --noEmit`)
-- **smoke**: build + run `--help`
+### 📊 Post-Generation Validation
 
-## Config (MVP)
+After generating tests, validation checks:
 
-Create `phantom-pr.yml` at the repo root (or pass `--config path/to/phantom-pr.yml`):
+- Branch coverage completeness
+- Effect cleanup testing (for `useEffect` with cleanup)
+- Child component mocking
+- Returns specific `llm_reject_*` codes for failures
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `phantom-pr status` | Show config and status |
+| `phantom-pr index` | Index the codebase |
+| `phantom-pr plan` | Generate test plan |
+| `phantom-pr tests <file>` | Generate tests for a file |
+| `phantom-pr full` | Full orchestration (CI mode) |
+| `phantom-pr pr --prNumber <n>` | PR companion mode |
+| `phantom-pr testability <file>` | Add data-testid attributes |
+
+## Configuration
+
+Create `phantom-pr.yml` at repo root:
 
 ```yaml
 baseBranch: main
@@ -43,8 +101,7 @@ github:
   owner: your-org
   repo: your-repo
   tokenEnvVar: GITHUB_TOKEN
-  # Safety default: fork PRs are denied unless explicitly allowed.
-  allowForkPrs: false
+  allowForkPrs: false  # Safety default
 limits:
   maxFilesChanged: 50
   maxLinesChanged: 5000
@@ -52,92 +109,171 @@ limits:
   maxOpenBotPRs: 3
   maxPRsPerRun: 1
 mode:
-  dryRun: true
+  dryRun: true  # Set false for real PRs
 test:
   command: npm test
 ```
 
-Check config resolution (never prints token values):
+### Config Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `baseBranch` | Target branch for PRs | `main` |
+| `limits.maxIterations` | Max test retry attempts | `5` |
+| `limits.maxPRsPerRun` | Max PRs per CI run | `1` |
+| `mode.dryRun` | Disable real Git/GitHub operations | `true` |
+| `test.command` | Test command to run | `npm test` |
+
+## CI Integration
 
-```powershell
-node dist/cli.js status
-node dist/cli.js status --config path/to/phantom-pr.yml
+### Scheduled Runs (Recommended: 4x/day)
+
+```yaml
+# GitHub Actions example
+on:
+  schedule:
+    - cron: '0 1,7,13,19 * * *'
+
+jobs:
+  phantom-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx phantom-pr full --root .
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-## Local run
+### Jenkins
+
+See `docs/jenkins.md` for Pipeline examples.
+
+## Understanding Reports
+
+### `tests` command → `.phantom-pr/report.json`
+
+See `docs/report-json.md` for schema details.
+
+Key fields:
+- `finalOutcome`: `pass` | `fail` | `timeout`
+- `attempts`: Array of test run attempts
+- `generatorWarnings`: Any validation issues
 
-Recommended “safe first run” in a real repo (no network side effects):
+### `full` command → `.phantom-pr/full.json`
 
-```powershell
+- `caps`: Open PR count and limits
+- `chosenTarget`: What file was selected
+- `lane`: `tests` | `testability` | `skipped`
+
+## Contributing
+
+### Development Setup
+
+```bash
+git clone https://github.com/norralak/blacksand-phantom-pr.git
+cd blacksand-phantom-pr
+npm install
 npm run build
-node dist/cli.js index --root .
-node dist/cli.js plan --root .
-node dist/cli.js full --root . --dryRun --report .phantom-pr/full.json
+npm test
 ```
 
-What “success” looks like:
-- `full` exits `0` and prints a stable JSON object to stdout.
-- In dryRun, it never opens/closes/comments on PRs and may set `refreshSkippedReason` (e.g. `dryrun_no_github_token`).
+### Project Structure
 
-## Scheduled CI run (4x/day)
+```
+src/
+├── cli.ts              # CLI entrypoint
+├── commands/           # Command implementations
+├── adapters/           # IO boundaries (git, github, fs)
+└── core/
+    ├── analysis/       # AST extraction (NEW)
+    ├── context/        # Context packing & selection
+    ├── validation/     # Post-generation validation (NEW)
+    ├── retry/          # Error parsing & feedback (NEW)
+    ├── generator/      # Test generators (LLM, smoke)
+    ├── testRunner/     # Test execution
+    └── ...
+```
 
-Minimal pattern: install deps, build, then run `full` (the orchestrator). Schedule it **4 times/day** in your CI system:
+### Running Tests
 
-- Example cron (works for Jenkins “Build periodically”, and similarly in other systems): `H 1,7,13,19 * * *`
+```bash
+# All tests
+npm test
 
-Jenkins notes and a Pipeline example: see `docs/jenkins.md`.
+# Specific test file
+npm test -- tests/ast-extractor.test.mjs
 
-Notes:
-- Prefer running `full` on a clean workspace with the repo checked out and a configured Git remote.
-- Keep `mode.dryRun: true` until you verify behavior on your repo and CI environment.
-- `limits.maxPRsPerRun` is enforced (default `1`): one run does at most one unit of work.
+# With verbose output
+npm test -- --test-reporter=spec
+```
 
-## Required permissions
+### Code Style
 
-### Git permissions (for real mode PR workflows)
-- The CI checkout must be able to create branches and push (e.g. SSH deploy key or HTTPS token configured for `git push`).
+- **TypeScript**: Strict mode enabled
+- **Formatting**: Prettier (run `npm run format`)
+- **Linting**: TypeScript compiler (`npm run lint`)
 
-### GitHub API permissions (for real mode PR workflows)
-`phantom-pr` uses the env var named by `github.tokenEnvVar` from `phantom-pr.yml` (and never prints its value).
+### Adding New Features
 
-For a GitHub Fine-grained token, the minimum typically needed:
-- **Contents**: Read & Write (push branches)
-- **Pull requests**: Read & Write (open PRs, read PR status)
-- **Issues**: Read & Write (comment on PRs / add labels)
-- **Metadata**: Read
+1. **Create types first** in `types.ts`
+2. **Implement with tests** - follow TDD
+3. **Add barrel export** in `index.ts`
+4. **Update README** if user-facing
+
+### Risk Register
+
+When adding features with heuristics (parsing, detection), document risks:
 
-For a classic PAT, this is commonly covered by `repo` scope, but prefer fine-grained when possible.
+| When to add risk | Example |
+|------------------|---------|
+| Regex-based parsing | Error parser patterns |
+| Static lists | External package detection |
+| Heuristic detection | Branch/effect identification |
 
-## How to interpret `.phantom-pr/report.json` (tests command)
+### Pull Request Guidelines
 
-See `docs/report-json.md`.
+- One feature per PR
+- Include tests for new functionality
+- Update documentation
+- Run `npm test` before submitting
 
-## How to interpret `.phantom-pr/full.json` (full command)
+## Required Permissions
 
-`phantom-pr full` writes a small orchestration report (default: `<root>/.phantom-pr/full.json`):
-- **`caps`** shows open PR count and whether the cap was hit
-- **`refreshSkippedReason`** explains why GitHub refresh wasn’t attempted (dryRun safety)
-- **`stale`** summarizes stale PR consideration and actions
-- **`chosenTarget`** and **`lane`** show what it decided to do
+### Git
+- Create branches
+- Push commits
 
-## Logging
+### GitHub API (via `tokenEnvVar`)
+- **Contents**: Read & Write
+- **Pull requests**: Read & Write
+- **Issues**: Read & Write (for comments)
+- **Metadata**: Read
+
+## Troubleshooting
 
-Commands use a structured logger with levels (**debug/info/warn/error**). Logs go to **stderr** to keep command output clean.
+### "Cannot find module" errors
 
-- Enable debug logs:
+The test generator mocks child components. If you see import errors:
 
-```powershell
-node dist/cli.js status --verbose
+```typescript
+// Add to test file
+jest.mock('./ChildComponent');
 ```
 
-## Golden demo (real PRs)
+### Tests timing out
+
+- Check for async operations without proper `await`
+- Use `waitFor()` from testing-library
+- Increase timeout in jest config
 
-There is a PowerShell-friendly script that runs both modes (scheduled + PR companion) in **real mode**:
-- Scheduled: `full` (opens/updates a bot PR on `baseBranch`)
-- PR companion: `pr --prNumber <n>` (opens/updates a companion PR)
+### LLM not generating tests
 
-See `DEMO.md` and run `scripts/golden-demo.ps1`.
+Check `.phantom-pr/report.json` for:
+- `llm.allowed`: Must be `true`
+- `generatorWarnings`: Shows rejection reasons
 
 ## License
-Proprietary — All Rights Reserved. See LICENSE.
 
+Proprietary — All Rights Reserved. See LICENSE.md.

package/dist/core/analysis/astExtractor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AST extractor that analyzes React/TypeScript component files.
+ * Uses TypeScript's built-in compiler API (no external parser dependency).
+ *
+ * Pure function: parse file → return ComponentAnalysis.
+ * Handles parse errors gracefully (returns partial analysis, doesn't throw).
+ */
+import type { ComponentAnalysis } from './types.js';
+/**
+ * Extract component analysis from a React/TypeScript file.
+ * @param filePath - Path to the file (for reference in output)
+ * @param fileContent - Source code content
+ * @returns ComponentAnalysis with extracted structure info
+ */
+export declare function extractComponentAnalysis(filePath: string, fileContent: string): ComponentAnalysis;