headlamp 0.1.36 → 0.1.58

package/README.md

@@ -1,19 +1,19 @@
-### Headlamp
+# Headlamp
 
 Headlamp is a **Rust-powered test UX CLI**: smarter test selection, cleaner output, and a unified workflow across **jest**, **cargo test**, **cargo nextest**, and **pytest**.
 
 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.
 
-### Why Headlamp
+## Why Headlamp
 
 - **One CLI, many runners**: `--runner=jest|cargo-nextest|cargo-test|pytest`
 - **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
 
-### Installation
+## Installation
 
-#### npm (Node.js projects)
+### npm (Node.js projects)
 
 Requirements:
 
@@ -31,7 +31,7 @@ Run:
 npx headlamp --help
 ```
 
-#### Cargo (Rust projects)
+### Cargo (Rust projects)
 
 Install from crates.io:
 
@@ -39,9 +39,21 @@ Install from crates.io:
 cargo install headlamp
 ```
 
-### Quickstart
+### Python (pytest projects)
 
-#### Jest
+Install:
+
+```bash
+pip install headlamp
+```
+
+```bash
+headlamp --runner=pytest
+```
+
+## Quickstart
+
+### Jest
 
 ```bash
 npx headlamp --runner=jest
@@ -53,14 +65,14 @@ Forward runner args after `--` (unknown args are forwarded):
 npx headlamp --runner=jest -- --runInBand
 ```
 
-#### Cargo nextest / cargo test
+### Cargo nextest / cargo test
 
 ```bash
 headlamp --runner=cargo-nextest
 headlamp --runner=cargo-test
 ```
 
-### CLI
+## CLI
 
 Run `headlamp --help` to see the up-to-date flags list.
 
@@ -69,12 +81,19 @@ Highlights:
 - **runners**: `--runner=jest|pytest|cargo-nextest|cargo-test`
 - **changed selection**: `--changed=all|staged|unstaged|branch|lastCommit|lastRelease`
   - `lastRelease` selects changes since the previous stable SemVer release tag
-- **coverage**: `--coverage` plus `--coverage-ui`, `--coverage.detail`, thresholds, etc.
+- **coverage**: `--coverage` plus `--coverage-ui`, `--coverage-detail`, thresholds, etc.
+- **artifacts** (default: none): `--keep-artifacts` to keep runner artifacts on disk
+
+Legacy aliases (still accepted, but not recommended):
+
+- `--keepArtifacts`
+- `--coverage.detail`
 
-### Configuration
+## Configuration
 
 Headlamp discovers config from your repo root. Supported file names:
 
+- `headlamp.toml` (highest precedence)
 - `headlamp.config.ts`
 - `headlamp.config.js`
 - `headlamp.config.mjs`
@@ -86,7 +105,28 @@ Headlamp discovers config from your repo root. Supported file names:
 - `headlamp.config.yml`
 - `.headlamprc` plus `.headlamprc.*` variants (`.json`, `.json5`, `.jsonc`, `.yaml`, `.yml`, `.js`, `.cjs`, `.mjs`, `.ts`)
 
-#### Example: `headlamp.config.ts`
+Headlamp also supports embedded TOML config (lower precedence than explicit config files):
+
+- `pyproject.toml` under `[tool.headlamp]`
+- `Cargo.toml` under `[package.metadata.headlamp]`
+
+### Example: `headlamp.toml` (recommended for Rust + Python)
+
+```toml
+# Run tests sequentially (useful for very heavy integration tests)
+sequential = true
+
+[coverage]
+abort_on_failure = true
+mode = "auto"
+page_fit = true
+keep_artifacts = false
+
+[changed]
+depth = 20
+```
+
+### Example: `headlamp.config.ts`
 
 Rules:
 
@@ -105,6 +145,7 @@ export default {
   ci: false,
   verbose: false,
   noCache: false,
+  keepArtifacts: false,
 
   // Coverage defaults
   coverage: true,
@@ -120,14 +161,23 @@ export default {
 };
 ```
 
-### Contributing
+## Artifacts (coverage, caches, temp files)
+
+By default, headlamp runs **artifact-free**: it uses an ephemeral per-run workspace and **does not leave files behind** in your repo (e.g. `coverage/`, `.coverage`, `.pytest_cache`, `target/`) or OS temp.
+
+If you need artifacts on disk (for example, to upload coverage reports in CI), opt out:
+
+- CLI: `--keep-artifacts`
+- Config: `keepArtifacts: true`
+
+## Contributing
 
 Pull requests are welcome. For large changes, open an issue first to align on direction.
 
-### Support
+## Support
 
 - Bug reports and feature requests: GitHub Issues
 
-### License
+## License
 
 MIT — see `LICENSE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "headlamp",
-  "version": "0.1.36",
+  "version": "0.1.58",
   "description": "The smart searchlight for your test suite. Fast, graph-powered selection for Jest and Cargo.",
   "keywords": [
     "testing",