headlamp 0.1.18 → 0.1.20

package/README.md

@@ -1,54 +1,78 @@
 # 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
 
-## Configuration
+- `--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
+
+### Concurrency
 
-Headlamp supports a project-level config file. The config is explicit and contextual:
+- `--sequential[=true|false]`: serialize execution
+  - Effect: adds Jest `--runInBand` and runs Headlamp’s per‑project execution with stride 1 (no parallel projects)
 
-- Base defaults: always applied (safe, non-surprising)
-- Coverage-context defaults: only applied if coverage is active (i.e., you passed `--coverage` or you set `coverage: true` in config)
-- Changed-context defaults: only applied if changed selection is active (i.e., you passed `--changed=…` or set a default mode in config)
+### Selection
 
-CLI always overrides config. No environment variables or hidden presets are used.
+- `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)
 
-### Supported filenames (repo root)
+### Coverage
+
+- `--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`
+
+## Configuration
+
+Project-level file at repo root. CLI always overrides config. No env vars or hidden presets.
+
+### Supported filenames
 
 - `headlamp.config.ts`
 - `headlamp.config.js` / `headlamp.config.mjs` / `headlamp.config.cjs`
@@ -56,24 +80,13 @@ CLI always overrides config. No environment variables or hidden presets are used
 
 ### Base defaults (always applied)
 
-These are applied to every run and should be non-controversial project choices:
+- `bootstrapCommand: string`
+- `jestArgs: string[]`
+- `sequential?: boolean` – serialize tests across Jest and Headlamp
 
-- `bootstrapCommand: string` – command or npm script to run before tests
-- `jestArgs: string[]` – extra args passed to Jest (e.g., `['--runInBand']`)
+### Coverage-context defaults (applied only when coverage is active)
 
-Example:
-
-```ts
-// headlamp.config.ts
-export default {
-  bootstrapCommand: 'test:jest:bootstrap',
-  jestArgs: ['--runInBand'],
-};
-```
-
-### Coverage-context defaults
-
-Applied only when coverage is active (triggered by `--coverage` on the CLI or `coverage: true` in config). Prefer the nested `coverage` section:
+Prefer the nested `coverage` section:
 
 ```ts
 export default {
@@ -85,59 +98,37 @@ export default {
 };
 ```
 
-Optional extras (honored when coverage is active):
+Additional recognized fields when coverage is active:
 
 - `editorCmd` -> `--coverage.editor`
-- `include: string[]` -> `--coverage.include=a,b,c`
-- `exclude: string[]` -> `--coverage.exclude=a,b,c`
-- `coverageDetail: number | 'all' | 'auto'` -> `--coverage.detail`
-- `coverageShowCode: boolean` -> `--coverage.showCode`
-- `coverageMaxFiles: number` -> `--coverage.maxFiles`
-- `coverageMaxHotspots: number` -> `--coverage.maxHotspots`
+- `include`, `exclude` -> `--coverage.include`, `--coverage.exclude`
+- `coverageDetail`, `coverageShowCode`, `coverageMaxFiles`, `coverageMaxHotspots`
 
-Back-compat: legacy top-level fields (`coverageAbortOnFailure`, `coverageMode`, `coveragePageFit`, etc.) are still recognized, but the nested `coverage` section is preferred.
-
-### Changed-context defaults
-
-Applied only when changed selection is active (triggered by `--changed=…` on the CLI, or by specifying a default mode in config). Prefer the nested `changed` section:
+### Changed-context defaults (applied only when changed selection is active)
 
 ```ts
 export default {
   changed: {
-    depth: 20, // default depth for all modes -> --changed.depth=20
-    branch: {
-      depth: 10, // per-mode override when --changed=branch
-    },
-    staged: {
-      depth: 8,
-    },
-    unstaged: {
-      depth: 6,
-    },
-    all: {
-      depth: 12,
-    },
+    depth: 20, // default for all modes -> --changed.depth=20
+    branch: { depth: 10 },
+    staged: { depth: 8 },
+    unstaged: { depth: 6 },
+    all: { depth: 12 },
   },
 };
 ```
 
-If you also want to enforce a default mode for everyone, you can set a string at the legacy top-level: `changed: 'branch'`. Headlamp will emit `--changed=branch` unless the CLI already specified a mode. Otherwise, prefer to let scripts opt-in on the CLI and keep config focused on depth/details.
-
-### Precedence and gating rules
-
-- CLI always wins. If you pass `--coverage.mode=full`, it overrides the config’s `coverage.mode`.
-- Coverage extras only apply when coverage is active.
-- Changed depth only applies when changed selection is active. If a per‑mode depth exists, it’s used; otherwise we fall back to the default `changed.depth`.
+You may also set a top‑level default mode (e.g., `changed: 'branch'`); CLI still wins.
 
-### Example configs and scripts
-
-Config (headlamp.config.ts):
+### Full example
 
 ```ts
+// headlamp.config.ts
 export default {
   // Base
   bootstrapCommand: 'test:jest:bootstrap',
-  jestArgs: ['--runInBand'],
+  sequential: true, // serialize tests (maps to Jest --runInBand and single-project stride)
+  jestArgs: ['--runInBand'], // optional: redundant when sequential is true
 
   // Coverage-context
   coverage: {
@@ -154,159 +145,33 @@ export default {
 };
 ```
 
-Scripts:
+## Scripts
 
 ```json
 {
   "scripts": {
-    "test": "headlamp --runInBand",
-    "test:coverage": "headlamp --coverage --runInBand",
+    "test": "headlamp --sequential",
+    "test:coverage": "headlamp --coverage --sequential",
     "test:dev": "npm run test -- --changed=branch --coverage --onlyFailures"
   }
 }
 ```
 
-Resulting behavior:
-
-- `headlamp --runInBand`: base defaults only; no coverage/changed extras.
-- `headlamp --coverage --runInBand`: applies coverage abortOnFailure/mode/pageFit; changed depth is not applied.
-- `headlamp --changed=branch --coverage --onlyFailures`: applies per‑mode changed depth (10) and coverage group; `onlyFailures` is opt‑in via CLI.
-
-## Examples
-
-- Show coverage with detailed hotspots, auto-fit to terminal rows:
-
-```bash
-npx headlamp --coverage
-```
-
-- Focus on specific production files and run only directly-related tests:
-
-```bash
-npx headlamp --coverage src/services/user.ts src/components/UserCard.tsx
-```
-
 ## Bootstrap command
 
 Use `--bootstrapCommand` to run setup work before tests (e.g., database migrations/seeding). If omitted, no bootstrap runs.
 
-- Single token value is treated as an npm script name and run as `npm run -s <name>`.
-- Values containing whitespace are treated as full commands and executed via the system shell.
+- 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
-# 1) Run an npm script before tests
 npx headlamp --bootstrapCommand test:jest:bootstrap
-
-# 2) Run an npm script with its own args
-npx headlamp --bootstrapCommand "db:migrate -- --reset"
-
-# 3) Run an arbitrary command (e.g., sequelize migrations for test env)
 npx headlamp --bootstrapCommand "sequelize db:migrate --env test"
-
-# 4) Seed a test database via a node script
-npx headlamp --bootstrapCommand "node scripts/seed-test-db.js"
-```
-
-This bootstrap step executes once before Jest is started. If the bootstrap exits non‑zero, the run aborts with an error.
-
-## Output flags
-
-- `--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`).
-
-Examples:
-
-```bash
-# Show only failures during the run, but still print the final summary
-npx headlamp --onlyFailures
-
-# Combine with changed-file selection
-npx headlamp --changed --onlyFailures
-```
-
-- `--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.
-
-Examples:
-
-```bash
-# Always include the full console output for each failure
-npx headlamp --showLogs
-
-# Combine with only failures visible during the run
-npx headlamp --onlyFailures --showLogs
 ```
 
-## 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`.
-    - `lastCommit`: files changed in the last commit (`git diff --name-only HEAD^ HEAD`). Useful on main to scope to the most recent change.
-  - 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.
-
-Examples:
-
-```bash
-# Staged changes only
-npx headlamp --changed=staged
-
-# All working tree changes
-npx headlamp --changed
-
-# Diff current branch against default branch (merge-base)
-npx headlamp --changed=branch
-
-# Combine with coverage
-npx headlamp --coverage --changed=branch
-```
-
-Depth examples:
-
-```bash
-# Scan imports up to 10 levels deep when resolving related tests for changed files
-npx headlamp --changed=all --changed.depth=10
-
-# With branch mode
-npx headlamp --changed=branch --changed.depth=12
-```
-
-## 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.
-
-Examples:
+## Examples
 
 ```bash
 # Abort on failing tests without printing coverage
@@ -314,6 +179,9 @@ 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
@@ -322,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';

package/dist/cli.cjs

@@ -53569,6 +53569,7 @@ var init_args = __esm({
       coverageAbortOnFailure: (value2) => ({ type: "coverageAbortOnFailure", value: value2 }),
       onlyFailures: (value2) => ({ type: "onlyFailures", value: value2 }),
       showLogs: (value2) => ({ type: "showLogs", value: value2 }),
+      sequential: (value2) => ({ type: "sequential", value: value2 }),
       bootstrapCommand: (value2) => ({ type: "bootstrapCommand", value: value2 }),
       jestArg: (value2) => ({ type: "jestArg", value: value2 }),
       jestArgs: (values) => ({ type: "jestArgs", values }),
@@ -53745,6 +53746,16 @@ var init_args = __esm({
           "--onlyFailures",
           (_flag, lookahead) => step([ActionBuilders.onlyFailures(isTruthy(String(lookahead)))], true)
         ),
+        // --sequential flag (boolean) → serialize projects and map to jest --runInBand
+        rule.eq("--sequential", () => step([ActionBuilders.sequential(true)])),
+        rule.startsWith(
+          "--sequential=",
+          (value2) => step([ActionBuilders.sequential(isTruthy((value2.split("=")[1] ?? "").trim().toLowerCase()))])
+        ),
+        rule.withLookahead(
+          "--sequential",
+          (_flag, lookahead) => step([ActionBuilders.sequential(isTruthy(String(lookahead)))], true)
+        ),
         // --showLogs flag (boolean)
         rule.eq("--showLogs", () => step([ActionBuilders.showLogs(true)])),
         rule.startsWith(
@@ -53915,6 +53926,8 @@ var init_args = __esm({
           return { vitest: [], jest: [], coverage: false, onlyFailures: action.value };
         case "showLogs":
           return { vitest: [], jest: [], coverage: false, showLogs: action.value };
+        case "sequential":
+          return { vitest: [], jest: [], coverage: false, sequential: action.value };
         case "jestArgs":
           return { vitest: [], jest: action.values, coverage: false };
         case "selectionHint":
@@ -53994,6 +54007,7 @@ var init_args = __esm({
         ...right.coverageAbortOnFailure !== void 0 || left.coverageAbortOnFailure !== void 0 ? { coverageAbortOnFailure: right.coverageAbortOnFailure ?? left.coverageAbortOnFailure } : {},
         ...right.onlyFailures !== void 0 || left.onlyFailures !== void 0 ? { onlyFailures: right.onlyFailures ?? left.onlyFailures } : {},
         ...right.showLogs !== void 0 || left.showLogs !== void 0 ? { showLogs: right.showLogs ?? left.showLogs } : {},
+        ...right.sequential !== void 0 || left.sequential !== void 0 ? { sequential: right.sequential ?? left.sequential } : {},
         ...right.coverageDetail !== void 0 || left.coverageDetail !== void 0 ? { coverageDetail: right.coverageDetail ?? left.coverageDetail } : {},
         ...right.coverageShowCode !== void 0 || left.coverageShowCode !== void 0 ? { coverageShowCode: right.coverageShowCode ?? left.coverageShowCode } : {},
         ...right.coverageMode !== void 0 || left.coverageMode !== void 0 ? { coverageMode: right.coverageMode ?? left.coverageMode } : {},
@@ -54019,6 +54033,7 @@ var init_args = __esm({
       let coverageAbortOnFailure = false;
       let onlyFailures = false;
       let showLogs = false;
+      let sequential = false;
       let coverageShowCode = Boolean(process.stdout.isTTY);
       let coverageMode = "auto";
       const coverageMaxFilesLocalInit = void 0;
@@ -54052,6 +54067,7 @@ var init_args = __esm({
                 if (conf.onlyFailures !== void 0)
                   p3.onlyFailures = Boolean(conf.onlyFailures);
                 if (conf.showLogs !== void 0) p3.showLogs = Boolean(conf.showLogs);
+                if (conf.sequential !== void 0) p3.sequential = Boolean(conf.sequential);
                 if (conf.editorCmd) p3.editorCmd = String(conf.editorCmd);
                 if (conf.workspaceRoot) p3.workspaceRoot = String(conf.workspaceRoot);
                 if (Array.isArray(conf.include)) p3.includeGlobs = conf.include;
@@ -54090,6 +54106,7 @@ var init_args = __esm({
       coverageAbortOnFailure = contrib.coverageAbortOnFailure ?? coverageAbortOnFailure;
       onlyFailures = contrib.onlyFailures ?? onlyFailures;
       showLogs = contrib.showLogs ?? showLogs;
+      sequential = contrib.sequential ?? sequential;
       coverageShowCode = contrib.coverageShowCode ?? coverageShowCode;
       const { bootstrapCommand } = contrib;
       const coverageDetailComputed = contrib.coverageDetail ?? (contrib.selection ? "auto" : void 0);
@@ -54110,6 +54127,9 @@ var init_args = __esm({
       if (showLogs) {
         jestArgs.push("--no-silent");
       }
+      if (sequential && !jestArgs.includes("--runInBand")) {
+        jestArgs.push("--runInBand");
+      }
       const selectionLooksLikeTestPath = (contrib.selectionPaths ?? []).some(
         (selectionPath) => /\.(test|spec)\.[tj]sx?$/i.test(selectionPath) || /(^|\/)tests?\//i.test(selectionPath)
       );
@@ -54129,6 +54149,7 @@ var init_args = __esm({
         coverageAbortOnFailure: configFromFile?.coverageAbortOnFailure ?? coverageAbortOnFailure,
         onlyFailures: configFromFile?.onlyFailures ?? onlyFailures,
         showLogs: configFromFile?.showLogs ?? showLogs,
+        sequential: configFromFile?.sequential ?? sequential,
         ...bootstrapCommand !== void 0 ? { bootstrapCommand } : {},
         selectionSpecified: Boolean(contrib.selection),
         selectionPaths: [...contrib.selectionPaths ?? []],
@@ -60154,6 +60175,9 @@ var program = async () => {
     if (cfg.bootstrapCommand) {
       pushKV("--bootstrapCommand", cfg.bootstrapCommand);
     }
+    if (cfg.sequential === true) {
+      t2.push("--sequential");
+    }
     if (Array.isArray(cfg.jestArgs) && cfg.jestArgs.length) {
       t2.push(...cfg.jestArgs);
     }
@@ -60240,6 +60264,7 @@ var program = async () => {
     coverageAbortOnFailure,
     onlyFailures,
     showLogs,
+    sequential,
     bootstrapCommand,
     selectionSpecified,
     selectionPaths,
@@ -60946,7 +60971,7 @@ var program = async () => {
         os4.tmpdir(),
         `jest-bridge-${Date.now()}-${Math.random().toString(36).slice(2)}.json`
       );
-      const reporterPath = path13.resolve("scripts/jest-vitest-bridge.cjs");
+      const reporterPath = path13.join(os4.tmpdir(), "headlamp", "jest-vitest-bridge.cjs");
       try {
         const needsWrite = (() => {
           try {
@@ -60960,7 +60985,7 @@ var program = async () => {
           fsSync3.mkdirSync(path13.dirname(reporterPath), { recursive: true });
           fsSync3.writeFileSync(reporterPath, JEST_BRIDGE_REPORTER_SOURCE, "utf8");
         }
-        const envPath = path13.resolve("scripts/jest-bridge-env.cjs");
+        const envPath = path13.join(os4.tmpdir(), "headlamp", "jest-bridge-env.cjs");
         try {
           const existingEnv = fsSync3.readFileSync(envPath, "utf8");
           if (existingEnv !== JEST_BRIDGE_ENV_SOURCE) {
@@ -61234,7 +61259,8 @@ ${stripFooter(rawAlso)}`.trimEnd();
         jestExitCode = code;
       }
     };
-    await runParallelStride(projectsToRun, 3, async (cfg, index) => {
+    const stride = sequential ? 1 : 3;
+    await runParallelStride(projectsToRun, stride, async (cfg, index) => {
       await runOneProject(cfg);
     });
   } else {