headlamp 0.1.60__py3-none-macosx_11_0_arm64.whl

headlamp/__init__.py

@@ -0,0 +1,6 @@
+"""
+PyPI wrapper for the Headlamp CLI.
+
+The `headlamp` console entrypoint executes a bundled platform binary located at:
+`headlamp/bin/headlamp` or `headlamp/bin/headlamp.exe`.
+"""

headlamp/_bin.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+import platform
+from pathlib import Path
+
+try:
+    # Python 3.9+
+    from importlib import resources as importlib_resources  # type: ignore
+except Exception:  # pragma: no cover
+    import importlib_resources  # type: ignore
+
+
+_OVERRIDE_ENV = "HEADLAMP_PYPI_BIN_OVERRIDE"
+
+
+def _default_binary_resource_name() -> str:
+    return "headlamp.exe" if platform.system().lower().startswith("win") else "headlamp"
+
+
+def get_binary_path() -> Path:
+    """
+    Returns the absolute path to the bundled `headlamp` binary.
+
+    Test override:
+    - If `HEADLAMP_PYPI_BIN_OVERRIDE` is set, that path is used (if it exists).
+    """
+
+    override = os.environ.get(_OVERRIDE_ENV, "").strip()
+    if override:
+        p = Path(override).expanduser()
+        if not p.is_absolute():
+            p = (Path.cwd() / p).resolve()
+        if not p.exists():
+            raise FileNotFoundError(
+                f"headlamp (PyPI): override binary not found at {_OVERRIDE_ENV}={p}"
+            )
+        return p
+
+    resource_name = _default_binary_resource_name()
+
+    try:
+        # pkg is headlamp.bin (a namespace for resources)
+        bin_dir = importlib_resources.files("headlamp").joinpath("bin")
+        candidate = bin_dir.joinpath(resource_name)
+        candidate_path = Path(str(candidate))
+    except Exception as e:  # pragma: no cover
+        raise FileNotFoundError(
+            "headlamp (PyPI): could not resolve bundled binary resources"
+        ) from e
+
+    if not candidate_path.exists():
+        raise FileNotFoundError(_missing_binary_message(candidate_path))
+    return candidate_path
+
+
+def _missing_binary_message(expected_path: Path) -> str:
+    return (
+        "headlamp (PyPI): bundled headlamp binary not found.\n"
+        f"Expected at: {expected_path}\n\n"
+        "This usually means you installed an sdist (source distribution) or a wheel for a\n"
+        "different platform.\n\n"
+        "Fix:\n"
+        "  - Reinstall wheels only: pip install --only-binary :all: headlamp\n"
+    )
+

headlamp/_cli.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+from ._bin import get_binary_path
+
+
+def main() -> None:
+    try:
+        bin_path = get_binary_path()
+    except FileNotFoundError as e:
+        sys.stderr.write(str(e).rstrip() + os.linesep)
+        raise SystemExit(1)
+
+    argv = [str(bin_path), *sys.argv[1:]]
+    try:
+        completed = subprocess.run(argv)
+    except FileNotFoundError:
+        sys.stderr.write(f"headlamp (PyPI): failed to execute: {bin_path}{os.linesep}")
+        raise SystemExit(1)
+
+    raise SystemExit(completed.returncode)
+

headlamp-0.1.60.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: headlamp
+Version: 0.1.60
+Summary: Dependency-graph based test runner in Rust that supports Rust, Python, and JavaScript.
+Author: David Piper
+License: MIT
+Project-URL: Homepage, https://github.com/dbpiper/headlamp
+Project-URL: Repository, https://github.com/dbpiper/headlamp
+Keywords: testing,cli,pytest,jest,nextest
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Headlamp
+
+Headlamp is a **Rust-powered test UX CLI**: smarter test selection, cleaner output, and a unified workflow across **jest**, **Rust tests (headlamp runner)**, **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
+
+- **One CLI, many runners**: `--runner=headlamp|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
+
+### npm (Node.js projects)
+
+Requirements:
+
+- Node **>= 18**
+
+Install:
+
+```bash
+npm i -D headlamp
+```
+
+Run:
+
+```bash
+npx headlamp --help
+```
+
+### Cargo (Rust projects)
+
+Install from crates.io:
+
+```bash
+cargo install headlamp
+```
+
+### Python (pytest projects)
+
+Install:
+
+```bash
+pip install headlamp
+```
+
+```bash
+headlamp --runner=pytest
+```
+
+## Peer dependencies (system requirements)
+
+Headlamp is a wrapper around your project’s runners. It does **not** vendor the runners themselves, so you need the runner executables available in your environment for the features you’re using.
+
+### Common (all runners)
+
+- **Git**: required for `--changed=...` modes (e.g. `--changed=branch`).
+
+### Jest runner (`--runner=jest`)
+
+- **Node.js**: required.
+- **Jest installed in the repo**: Headlamp expects Jest to be runnable from your project (typically `./node_modules/.bin/jest`).
+- **Coverage** (`--coverage`): requires Jest coverage support (standard Jest `--coverage` + reporters). Headlamp formats/prints coverage from generated reports.
+
+### Pytest runner (`--runner=pytest`)
+
+- **Python 3**: required.
+- **pytest**: must be on `PATH` (`pytest` / `pytest.exe`).
+- **Coverage** (`--coverage`): requires `pytest-cov` (Headlamp enables coverage and passes `--cov` flags; branch coverage uses `--cov-branch`).
+
+### Headlamp (native Rust runner) (`--runner=headlamp`)
+
+- **Rust toolchain**: `cargo` + `rustc`.
+- **Per-test timings**: requires a preinstalled nightly toolchain (Headlamp enables libtest JSON + `--report-time` only when nightly is available).
+  - Install via: `rustup toolchain install nightly`
+
+### Cargo test runner (`--runner=cargo-test`)
+
+- **Rust toolchain**: `cargo` + `rustc`.
+- **Coverage** (`--coverage`): collected via LLVM tools from `rustup` (**no `cargo-llvm-cov` dependency**).
+  - Install via: `rustup component add llvm-tools-preview`
+
+### Cargo nextest runner (`--runner=cargo-nextest`)
+
+- **Rust toolchain**: `cargo` + `rustc`.
+- **nextest**: requires **`cargo-nextest`** (`cargo install cargo-nextest`).
+- **Coverage** (`--coverage`): collected via LLVM tools from `rustup` (**no `cargo-llvm-cov` dependency**).
+  - Install via: `rustup component add llvm-tools-preview`
+
+## Quickstart
+
+### Jest
+
+```bash
+npx headlamp --runner=jest
+```
+
+Forward runner args after `--` (unknown args are forwarded):
+
+```bash
+npx headlamp --runner=jest -- --runInBand
+```
+
+### Cargo nextest / cargo test
+
+```bash
+headlamp --runner=cargo-nextest
+headlamp --runner=cargo-test
+```
+
+Requirements:
+
+- `--runner=cargo-nextest`: requires `cargo-nextest` to be installed.
+  - Install via: `cargo install cargo-nextest` (or your preferred installer)
+
+## CLI
+
+Run `headlamp --help` to see the up-to-date flags list.
+
+Highlights:
+
+- **runners**: `--runner=headlamp|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.
+- **artifacts** (default: none): `--keep-artifacts` to keep runner artifacts on disk
+
+Legacy aliases (still accepted, but not recommended):
+
+- `--keepArtifacts`
+- `--coverage.detail`
+
+## Configuration
+
+Headlamp discovers config from your repo root. Supported file names:
+
+- `headlamp.toml` (highest precedence)
+- `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`)
+
+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:
+
+- Must have a **default export**
+- Only **relative imports** are supported inside the config file (`./` and `../`)
+
+```ts
+export default {
+  // Runner defaults
+  jestArgs: ["--runInBand"],
+
+  // Run once before tests (npm script name or a shell command)
+  bootstrapCommand: "test:jest:bootstrap",
+
+  // Global toggles
+  ci: false,
+  verbose: false,
+  noCache: false,
+  keepArtifacts: false,
+
+  // Coverage defaults
+  coverage: true,
+  coverageUi: "both",
+  coverage: {
+    abortOnFailure: true,
+    mode: "auto",
+    pageFit: true,
+  },
+
+  // Changed selection defaults
+  changed: { depth: 2 },
+};
+```
+
+## 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
+
+- Bug reports and feature requests: GitHub Issues
+
+## License
+
+MIT — see `LICENSE`.

headlamp-0.1.60.dist-info/RECORD

@@ -0,0 +1,9 @@
+headlamp-0.1.60.dist-info/RECORD,,
+headlamp-0.1.60.dist-info/WHEEL,sha256=0wJZkrMXhHamlhyeyzwHZC6TVoCduvm5-sXAkwO3M0I,133
+headlamp-0.1.60.dist-info/entry_points.txt,sha256=LGS3na55nE6Ut1Es24pTJn6KNgz3UOiNTYZRE2urwgU,48
+headlamp-0.1.60.dist-info/top_level.txt,sha256=eRZTjDhtIwmMCPa_qwcrLUl5OgT0gNtzjq58QS569K0,9
+headlamp-0.1.60.dist-info/METADATA,sha256=36AzlYrRL-TTYNJMPbdWqsk5ccsUYQ-BSFY8wZfqElU,6843
+headlamp/_cli.py,sha256=q9ihu8IP0E5aNjgS4l4TRaP7GNhzpkiRPn8E-Ye9iQM,580
+headlamp/__init__.py,sha256=it3ellGUCNveQ94VrupKnDtN-5KiThF3eIhCO27V14U,181
+headlamp/_bin.py,sha256=IaqveR8dNiphXcQcsR5DeS0h4O8X-8TN_062qNZIo_o,2045
+headlamp/bin/headlamp,sha256=hHdDgMRSHc-xi9cP-v1FEOU1SLlLyEt5711gGBGwbYM,5082672

headlamp-0.1.60.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: py3-none-macosx_11_0_arm64
+Generator: delocate 0.13.0
+

headlamp-0.1.60.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+headlamp = headlamp._cli:main

headlamp-0.1.60.dist-info/top_level.txt

@@ -0,0 +1 @@
+headlamp