headlamp 0.1.33 → 0.1.35

package/README.md

@@ -1,205 +1,157 @@
-# Headlamp CLI
+### Headlamp
 
-Coverage-first, runner-agnostic test UX for Jest. Delegates execution to your runner, focuses on better selection and coverage insights.
+Headlamp is a **Rust-powered test UX CLI**: smarter test selection, cleaner output, and a unified workflow across **jest**, **cargo test**, and **cargo nextest**.
 
-## Install
+Headlamp is useful when you want a consistent way to run tests across different projects and keep feedback fast as your repo grows. It can select tests based on what changed, surface failures in a readable format, and keep common defaults (like runner args and coverage settings) in a single config file so your team doesn’t have to remember a long list of flags.
 
-Use via npx (recommended):
+### Why Headlamp
 
-```bash
-npx headlamp --help
-```
+- **One CLI, many runners**: `--runner=jest|cargo-nextest|cargo-test`
+- **Selection that scales**: run what changed (`--changed`) and what’s related (dependency-graph driven)
+- **Coverage-first UX**: coverage output you can actually read
+- **Fast**: Rust core + caching
 
-Or install locally:
+### Installation
 
-```bash
-npm i -D headlamp
-```
+#### npm (recommended)
 
-## Usage
+Requirements:
 
-- Delegates to your local Jest install
-- Renders improved coverage tables and hotspots
-- Selects tests by import-graph when you pass production paths
+- Node **>= 18**
+- A GitHub Release for your version tag (see “Releases” below)
 
-Quick examples:
+Install:
 
 ```bash
-# Run tests with coverage
-npx headlamp --coverage
-
-# Run only tests related to selected production files
-npx headlamp src/services/user.ts src/components/UserCard.tsx
+npm i -D headlamp
 ```
 
-## CLI flags
-
-Pass your regular Jest flags (e.g. `-t`, `--testNamePattern`, paths). Headlamp forwards them, and strips/adjusts coverage-related flags when listing tests.
-
-### General
-
-- `--bootstrapCommand <cmd>`: run once before tests (npm script name or full shell command)
-- `--onlyFailures[=true|false]`: show only failing tests during live output; always shows final summary
-- `--showLogs[=true|false]`: include full console output under failing tests/files
+Run:
 
-### Concurrency
-
-- `--sequential[=true|false]`: serialize execution
-  - Effect: adds Jest `--runInBand` and runs Headlamp’s per‑project execution with stride 1 (no parallel projects)
+```bash
+npx headlamp --help
+```
 
-### Selection
+#### Cargo (from source)
 
-- `paths...`: any file/dir paths; production paths trigger related test discovery by import graph
-- `-t <pattern>` / `--testNamePattern <pattern>`: filter by test name
-- `--changed[=all|staged|unstaged|branch|lastCommit]`: select tests related to changed files
-- `--changed.depth=<n>`: cap transitive import scan depth for changed-file discovery (default: 5)
+```bash
+cargo install --path headlamp
+```
 
-### Coverage
+### Quickstart
 
-- `--coverage`: enable coverage collection and merged reporting
-- `--coverage.ui=jest|both` (alias: `--coverage-ui`): output mode for Istanbul text reports (default: `both`)
-- `--coverage.abortOnFailure`: exit immediately with test code and skip coverage print on failures
-- Display/detail options:
-  - `--coverage.mode=compact|full|auto` (default: `auto`)
-  - `--coverage.detail=<n>|all|auto` (default: `auto`)
-  - `--coverage.showCode=true|false` (default: `true` on TTY)
-  - `--coverage.maxFiles=<n>`
-  - `--coverage.maxHotspots=<n>`
-  - `--coverage.pageFit=true|false` (default: `true` on TTY)
-  - Globbing filters: `--coverage.include=a,b,c`, `--coverage.exclude=a,b,c`
+#### Jest
 
-## Configuration
+```bash
+npx headlamp --runner=jest
+```
 
-Project-level file at repo root. CLI always overrides config. No env vars or hidden presets.
+Forward runner args after `--` (unknown args are forwarded):
 
-### Supported filenames
+```bash
+npx headlamp --runner=jest -- --runInBand
+```
 
-- `headlamp.config.ts`
-- `headlamp.config.js` / `headlamp.config.mjs` / `headlamp.config.cjs`
-- `headlamp.config.json` / `headlamp.config.yaml` / `headlamp.config.yml`
+#### Cargo nextest / cargo test
 
-### Base defaults (always applied)
+```bash
+headlamp --runner=cargo-nextest
+headlamp --runner=cargo-test
+```
 
-- `bootstrapCommand: string`
-- `jestArgs: string[]`
-- `sequential?: boolean` – serialize tests across Jest and Headlamp
+### CLI
+
+Current `--help` output:
+
+```text
+headlamp
+
+Usage:
+  headlamp [--runner=<jest|vitest|pytest|cargo-nextest|cargo-test>] [--coverage] [--changed[=<mode>]] [args...]
+
+Flags:
+  --runner <runner>              Select runner (default: jest)
+  --coverage                     Enable coverage collection (runner-specific)
+  --coverage-ui=jest|both         Coverage output mode
+  --coverage.abortOnFailure       Exit on test failures without printing coverage
+  --watch                        Re-run on file changes (runner-agnostic polling watch)
+  --ci                           CI mode (disable interactive UI and set CI=1)
+  --verbose                      More Headlamp diagnostics
+  --no-cache                     Disable Headlamp caches (and runner caches when possible)
+  --onlyFailures                 Show only failing tests during live output
+  --showLogs                     Show full logs under failing tests
+  --sequential                   Serialize execution (maps to jest --runInBand)
+  --bootstrapCommand <cmd>       Run once before tests (npm script name or shell cmd)
+  --changed[=all|staged|unstaged|branch|lastCommit]
+  --changed.depth=<n>
+
+Notes:
+  Unknown args are forwarded to the runner.
+```
 
-### Coverage-context defaults (applied only when coverage is active)
+### Configuration
 
-Prefer the nested `coverage` section:
+Headlamp discovers config from your repo root. Supported file names:
 
-```ts
-export default {
-  coverage: {
-    abortOnFailure: true, // -> --coverage.abortOnFailure
-    mode: 'auto', // -> --coverage.mode=auto
-    pageFit: true, // -> --coverage.pageFit=true
-  },
-};
-```
+- `headlamp.config.ts`
+- `headlamp.config.js`
+- `headlamp.config.mjs`
+- `headlamp.config.cjs`
+- `headlamp.config.json`
+- `headlamp.config.json5`
+- `headlamp.config.jsonc`
+- `headlamp.config.yaml`
+- `headlamp.config.yml`
+- `.headlamprc` plus `.headlamprc.*` variants (`.json`, `.json5`, `.jsonc`, `.yaml`, `.yml`, `.js`, `.cjs`, `.mjs`, `.ts`)
 
-Additional recognized fields when coverage is active:
+#### Example: `headlamp.config.ts`
 
-- `editorCmd` -> `--coverage.editor`
-- `include`, `exclude` -> `--coverage.include`, `--coverage.exclude`
-- `coverageDetail`, `coverageShowCode`, `coverageMaxFiles`, `coverageMaxHotspots`
+Rules:
 
-### Changed-context defaults (applied only when changed selection is active)
+- Must have a **default export**
+- Only **relative imports** are supported inside the config file (`./` and `../`)
 
 ```ts
 export default {
-  changed: {
-    depth: 20, // default for all modes -> --changed.depth=20
-    branch: { depth: 10 },
-    staged: { depth: 8 },
-    unstaged: { depth: 6 },
-    all: { depth: 12 },
-  },
-};
-```
+  // Runner defaults
+  jestArgs: ["--runInBand"],
 
-You may also set a top‑level default mode (e.g., `changed: 'branch'`); CLI still wins.
+  // Run once before tests (npm script name or a shell command)
+  bootstrapCommand: "test:jest:bootstrap",
 
-### Full example
+  // Global toggles
+  ci: false,
+  verbose: false,
+  noCache: false,
 
-```ts
-// headlamp.config.ts
-export default {
-  // Base
-  bootstrapCommand: 'test:jest:bootstrap',
-  sequential: true, // serialize tests (maps to Jest --runInBand and single-project stride)
-  jestArgs: ['--runInBand'], // optional: redundant when sequential is true
-
-  // Coverage-context
+  // Coverage defaults
+  coverage: true,
+  coverageUi: "both",
   coverage: {
     abortOnFailure: true,
-    mode: 'auto',
+    mode: "auto",
     pageFit: true,
   },
 
-  // Changed-context
-  changed: {
-    depth: 20,
-    branch: { depth: 10 },
-  },
+  // Changed selection defaults
+  changed: { depth: 2 },
 };
 ```
 
-## Scripts
-
-```json
-{
-  "scripts": {
-    "test": "headlamp --sequential",
-    "test:coverage": "headlamp --coverage --sequential",
-    "test:dev": "npm run test -- --changed=branch --coverage --onlyFailures"
-  }
-}
-```
-
-## Bootstrap command
+### Contributing
 
-Use `--bootstrapCommand` to run setup work before tests (e.g., database migrations/seeding). If omitted, no bootstrap runs.
+Pull requests are welcome. For large changes, open an issue first to align on direction.
 
-- Single token: treated as an npm script name and run as `npm run -s <name>`
-- With spaces: treated as a full command and executed via the system shell
-
-Examples:
+Local dev:
 
 ```bash
-npx headlamp --bootstrapCommand test:jest:bootstrap
-npx headlamp --bootstrapCommand "sequelize db:migrate --env test"
-```
-
-## Examples
-
-```bash
-# Abort on failing tests without printing coverage
-npx headlamp --coverage --coverage.abortOnFailure
-
-# Show compact coverage limited to 50 files and 5 hotspots per file
-npx headlamp --coverage --coverage.mode=compact --coverage.maxFiles=50 --coverage.maxHotspots=5
-
-# Sequential run to avoid DB deadlocks
-npx headlamp --sequential
-```
-
-## Editor links
-
-Headlamp prints clickable links (OSC 8) to open files at hotspots. Set `--coverage.editor` to override the default editor URL template if needed.
-
-## API
-
-Programmatic use:
-
-```ts
-import { printCompactCoverage, resolveImportWithRoot } from 'headlamp';
+cargo test
 ```
 
-## Status
+### Support
 
-Alpha. Expect changes. Feedback welcome.
+- Bug reports and feature requests: GitHub Issues
 
-## License
+### License
 
-MIT
+MIT — see `LICENSE`.

package/bin/.gitkeep

@@ -0,0 +1,4 @@
+
+
+
+