headlamp 0.1.17 → 0.1.19

package/README.md

@@ -1,159 +1,187 @@
 # Headlamp CLI
 
-Coverage-first, runner-agnostic test UX for Jest/Vitest. Delegates execution to your runner, focuses on better selection and coverage insights.
+Coverage-first, runner-agnostic test UX for Jest. Delegates execution to your runner, focuses on better selection and coverage insights.
 
 ## Install
 
-Only in /Users/david/src/headlamp/src/lib: PLACEHOLDER
-Only in /Users/david/src/headlamp/src/lib: \_exec.ts
-Files /Users/david/src/gigworx-node/scripts/cli/coverage-print.ts and /Users/david/src/headlamp/src/lib/coverage-print.ts differ
-Files /Users/david/src/gigworx-node/scripts/cli/discovery.ts and /Users/david/src/headlamp/src/lib/discovery.ts differ
-Only in /Users/david/src/headlamp/src/lib: env-utils.ts
-Only in /Users/david/src/headlamp/src/lib: fast-related.ts
-Files /Users/david/src/gigworx-node/scripts/cli/graph-distance.ts and /Users/david/src/headlamp/src/lib/graph-distance.ts differ
-Files /Users/david/src/gigworx-node/scripts/cli/index.ts and /Users/david/src/headlamp/src/lib/index.ts differ
-Files /Users/david/src/gigworx-node/scripts/cli/program.ts and /Users/david/src/headlamp/src/lib/program.ts differ
+Use via npx (recommended):
 
-## Usage
+```bash
+npx headlamp --help
+```
 
-removed
-removed
+Or install locally:
+
+```bash
+npm i -D headlamp
+```
 
-- Delegates to your local Jest/Vitest install
+## Usage
+
+- Delegates to your local Jest install
 - Renders improved coverage tables and hotspots
 - Selects tests by import-graph when you pass production paths
 
-## Why
+Quick examples:
 
-- Keep Jest/Vitest as-is. Get a better UI/UX for coverage and selection.
+```bash
+# Run tests with coverage
+npx headlamp --coverage
 
-## Status
+# Run only tests related to selected production files
+npx headlamp src/services/user.ts src/components/UserCard.tsx
+```
 
-Alpha. API/CLI flags may change.
-und hotspots
+## CLI flags
 
-- `--coverage.mode=compact|full|auto`: compact table vs full per-file details
-- `--coverage.maxFiles`, `--coverage.maxHotspots`: limit rows to fit your terminal
-- `--coverage.pageFit=true|false`: adapt output to terminal rows
+Pass your regular Jest flags (e.g. `-t`, `--testNamePattern`, paths). Headlamp forwards them, and strips/adjusts coverage-related flags when listing tests.
 
-Pass all your regular Jest flags (e.g. `-t`, `--testNamePattern`, paths). Headlamp strips/adjusts coverage-related flags when listing tests.
+### General
 
-## Examples
+- `--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
 
-- Show coverage with detailed hotspots, auto-fit to terminal rows:
+### Concurrency
 
-```bash
-npx headlamp --coverage
-```
+- `--sequential[=true|false]`: serialize execution
+  - Effect: adds Jest `--runInBand` and runs Headlamp’s per‑project execution with stride 1 (no parallel projects)
 
-- Focus on specific production files and run only directly-related tests:
+### Selection
 
-```bash
-npx headlamp --coverage src/services/user.ts src/components/UserCard.tsx
-```
+- `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)
 
-## Output flags
+### Coverage
 
-- `--onlyFailures[=true|false]`:
-  - When enabled, the CLI prints only failing tests during execution across all views, while still printing the final test summary (files/tests/time) at the end.
-  - Supported forms: `--onlyFailures`, `--onlyFailures=true`, `--onlyFailures=false`.
-  - Works with other selection flags (e.g., `-t`, `--changed`).
+- `--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`
 
-Examples:
+## Configuration
 
-```bash
-# Show only failures during the run, but still print the final summary
-npx headlamp --onlyFailures
+Project-level file at repo root. CLI always overrides config. No env vars or hidden presets.
 
-# Combine with changed-file selection
-npx headlamp --changed --onlyFailures
-```
+### Supported filenames
 
-- `--showLogs[=true|false]`:
-  - When enabled, Headlamp prints a dedicated "Logs" section under each failing test and failing file with the full console output captured by the runner.
-  - By default (without this flag), Headlamp shows a condensed "Console errors" snippet with only the most relevant error messages. `--showLogs` includes all console entries (log/info/warn/error).
-  - Supported forms: `--showLogs`, `--showLogs=true`, `--showLogs=false`.
-  - Works alongside `--onlyFailures`, coverage flags, and selection flags.
+- `headlamp.config.ts`
+- `headlamp.config.js` / `headlamp.config.mjs` / `headlamp.config.cjs`
+- `headlamp.config.json` / `headlamp.config.yaml` / `headlamp.config.yml`
 
-Examples:
+### Base defaults (always applied)
 
-```bash
-# Always include the full console output for each failure
-npx headlamp --showLogs
+- `bootstrapCommand: string`
+- `jestArgs: string[]`
+- `sequential?: boolean` – serialize tests across Jest and Headlamp
 
-# Combine with only failures visible during the run
-npx headlamp --onlyFailures --showLogs
-```
+### Coverage-context defaults (applied only when coverage is active)
 
-## Changed-file selection
-
-- `--changed[=mode]` selects tests by files changed in your working tree or branch.
-  - Modes:
-    - `all` (default when `--changed` is passed without a value): includes staged + unstaged + untracked files.
-    - `staged`: only staged changes.
-    - `unstaged`: only unstaged + untracked files.
-    - `branch`: union of
-      - files changed on the current branch relative to the default branch (via merge-base), and
-      - your current uncommitted changes (staged, unstaged tracked, and untracked files).
-      - Default branch is resolved via `origin/HEAD` when available, falling back to `origin/main` or `origin/master`.
-  - Effects:
-    - Uses changed production files as seeds to discover related tests by import-graph.
-    - Coverage tables prioritize and annotate files related to selection/changed files.
-  - Additional flags:
-    - `--changed.depth=<n>`: cap the transitive import scan depth when refining related tests from changed production files. Default: 5. Increase to include more indirectly-related tests (slower), decrease for speed.
+Prefer the nested `coverage` section:
 
-Examples:
+```ts
+export default {
+  coverage: {
+    abortOnFailure: true, // -> --coverage.abortOnFailure
+    mode: 'auto', // -> --coverage.mode=auto
+    pageFit: true, // -> --coverage.pageFit=true
+  },
+};
+```
 
-```bash
-# Staged changes only
-npx headlamp --changed=staged
+Additional recognized fields when coverage is active:
 
-# All working tree changes
-npx headlamp --changed
+- `editorCmd` -> `--coverage.editor`
+- `include`, `exclude` -> `--coverage.include`, `--coverage.exclude`
+- `coverageDetail`, `coverageShowCode`, `coverageMaxFiles`, `coverageMaxHotspots`
 
-# Diff current branch against default branch (merge-base)
-npx headlamp --changed=branch
+### Changed-context defaults (applied only when changed selection is active)
 
-# Combine with coverage
-npx headlamp --coverage --changed=branch
+```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 },
+  },
+};
 ```
 
-Depth examples:
+You may also set a top‑level default mode (e.g., `changed: 'branch'`); CLI still wins.
 
-```bash
-# Scan imports up to 10 levels deep when resolving related tests for changed files
-npx headlamp --changed=all --changed.depth=10
+### Full example
 
-# With branch mode
-npx headlamp --changed=branch --changed.depth=12
+```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: {
+    abortOnFailure: true,
+    mode: 'auto',
+    pageFit: true,
+  },
+
+  // Changed-context
+  changed: {
+    depth: 20,
+    branch: { depth: 10 },
+  },
+};
 ```
 
-## Coverage flags
-
-- `--coverage`: enables coverage collection and prints merged coverage output after test execution. Uses your project's Jest/Vitest setup and reads coverage JSON from Jest.
-  - Prints a compact per-file table with hotspots and optionally detailed per-file breakdowns.
-  - Honors file selection and include/exclude globs when rendering coverage tables.
-  - When `--changed` is specified, coverage views factor in those changed files as selection seeds, influencing relevancy ordering and the “changed-related” highlighting.
-- `--coverage.abortOnFailure`: if tests fail, exit immediately with the test exit code and skip coverage printing. Useful in CI when failures should short-circuit.
-- `--coverage.ui=jest|both`:
-  - `jest`: write Istanbul text report to `coverage/merged/coverage.txt` only.
-  - `both` (default): write both `coverage.txt` and `coverage-summary.txt`.
-- Display and filtering options:
-  - `--coverage.mode=compact|full|auto` (default: `auto`): choose compact table-only or full per-file details.
-  - `--coverage.detail=<n>|all|auto` (default: `auto`): number of uncovered lines per file to show; `all` shows everything.
-  - `--coverage.showCode=true|false` (default: `true` when TTY): show code snippets for uncovered lines in full mode.
-  - `--coverage.maxFiles=<n>`: limit number of files in printed tables.
-  - `--coverage.maxHotspots=<n>`: limit hotspots per file in compact mode.
-  - `--coverage.pageFit=true|false` (default: `true` when TTY): fit output to terminal rows.
+## Scripts
+
+```json
+{
+  "scripts": {
+    "test": "headlamp --sequential",
+    "test:coverage": "headlamp --coverage --sequential",
+    "test:dev": "npm run test -- --changed=branch --coverage --onlyFailures"
+  }
+}
+```
+
+## Bootstrap command
+
+Use `--bootstrapCommand` to run setup work before tests (e.g., database migrations/seeding). If omitted, no bootstrap runs.
+
+- 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:
 
+```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
@@ -162,7 +190,7 @@ Headlamp prints clickable links (OSC 8) to open files at hotspots. Set `--covera
 
 ## API
 
-You can import pieces programmatically:
+Programmatic use:
 
 ```ts
 import { printCompactCoverage, resolveImportWithRoot } from 'headlamp';