lintle 0.1.1__tar.gz

lintle-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish
+
+# Manually triggered. Pick the target from the input dropdown (defaults to
+# the TestPyPI sandbox), and click Run workflow. Trusted Publishing (OIDC)
+# handles authentication for both PyPI and TestPyPI — no API tokens stored.
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: testpypi
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: ${{ inputs.target == 'pypi' && 'https://pypi.org/project/lintle/' || 'https://test.pypi.org/project/lintle/' }}
+    permissions:
+      id-token: write # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.11"
+
+      - name: Verify before publishing
+        run: |
+          uv sync
+          uv run pytest
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish to TestPyPI
+        if: inputs.target == 'testpypi'
+        run: uv publish --index testpypi --trusted-publishing always
+
+      - name: Publish to PyPI
+        if: inputs.target == 'pypi'
+        run: uv publish --trusted-publishing always

lintle-0.1.1/.gitignore

@@ -0,0 +1,29 @@
+# TLE corpus data — multi-gigabyte inputs and cleaner output, not version-controlled.
+# data/source/ holds the raw tle*.txt files and TLEs.zip; data/output/ is where
+# the cleaner writes <name>.cleaned.txt / <name>.broken.txt.
+/data/
+
+# Legacy / alternate locations (in case files are placed at the repo root)
+/tle*.txt
+/*.zip
+/cleaned/
+/output/
+
+# Claude Code session state
+/.claude/
+
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/

lintle-0.1.1/.python-version

@@ -0,0 +1 @@
+3.11

lintle-0.1.1/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.1] - 2026-05-22
+
+### Fixed
+
+- `lintle clean` (and `validate`) no longer crash with a `FileNotFoundError`
+  traceback when the default input directory `data/source` does not exist on the
+  host. A new input-validation step in `cli.main()` catches the situation
+  upfront and prints a friendly hint that points the user at `--help` and
+  explains how to pass paths or create the directory.
+- `discover_paths` no longer silently treats a nonexistent path as a file;
+  missing entries are dropped (and the new `check_paths` helper rejects them at
+  the boundary with a clear `no such file or directory` message instead of a
+  crash deeper in the pipeline).
+- `--jobs 0` is rejected upfront instead of silently spinning up a zero-worker
+  pool that hangs.
+
+### Added
+
+- `--version` / `-V` on the top-level `lintle` command.
+- Top-level and per-subcommand help now include an `Examples:` block and an
+  `Exit codes:` reference. Subcommands carry richer descriptions and metavars
+  (`PATH`, `DIR`, `N`) so `lintle --help` and `lintle clean --help` are
+  self-explanatory.
+- `check_paths(paths, using_default)` — a small public helper in `cli.py` that
+  returns a user-facing error string for missing or unreadable inputs, or
+  `None` if everything is fine.
+
+### Changed
+
+- The `paths` positional argument's argparse default is now `None` (resolved to
+  `data/source` inside `main()`) so the CLI can tell "user passed nothing" apart
+  from "user explicitly passed `data/source`" and tailor the error wording.
+- The version string is now tracked in **one place**: `pyproject.toml`. The
+  `__version__` attribute in `src/lintle/__init__.py` is resolved at runtime via
+  `importlib.metadata.version("lintle")` (falling back to `0.0.0+local` for
+  uninstalled source checkouts). Future releases need only a single bump in
+  `pyproject.toml` — see `CONTRIBUTING.md` for the release flow.
+
+## [0.1.0] - 2026-05-22
+
+### Added
+
+- `lintle` console script with two modes: `validate` (read-only audit) and `clean`
+  (writes corrected files plus quarantine sidecars).
+- `tle.py` — the single TLE validator: column layout, mod-10 checksum, semantic range
+  checks, and paired-record validation.
+- `repair.py` — speculative, validated repairs: trailing-`\` stripping, CRLF
+  normalisation, whitespace trimming, and deterministic checksum reconstruction.
+- `pipeline.py` — constant-memory streaming with prefix-driven `1 `/`2 ` line pairing.
+- `report.py` — per-file statistics, the byte-faithful `.broken.txt` quarantine sidecar,
+  and the Markdown run report.
+- `cli.py` — argument parsing, path globbing, per-file `ProcessPoolExecutor` parallelism,
+  a live single-line progress display, and graceful Ctrl-C shutdown (exit code `130`).
+- Test suite: 92 tests across 7 files, including an `sgp4` oracle cross-check and
+  golden-output / idempotence integration tests; `cli.py` is fully covered.
+- Project tooling: `ruff` for linting and formatting, `pytest-cov` for coverage.
+- Documentation: `README.md`, `CONTRIBUTING.md`, and this changelog.

lintle-0.1.1/CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this
+repository.
+
+`lintle` validates and cleans a ~30 GB corpus of Two-Line Element (TLE)
+satellite-tracking files exported from space-track.org.
+
+## Authoritative spec
+
+The design doc at `docs/superpowers/specs/2026-05-21-tle-corpus-cleaner-design.md` is the
+authoritative specification — read it before changing validation, repair, or pipeline
+behaviour. It carries a revision log in its header; keep that current when the design
+changes.
+
+## Tech Stack
+
+Python 3.11 · uv · standard library only at runtime · `sgp4` (dev-only test oracle) ·
+`pytest` · `pytest-cov` · `ruff`
+
+The runtime is **pure standard library**. `sgp4` and `pytest` are dev-only dependencies;
+`sgp4` is a test oracle and must never be imported at runtime.
+
+## Critical Rules — principles that must not be violated
+
+These are the reason the design exists; an implementation that breaks them is wrong.
+
+1. **Validated transformation.** Never apply a fix and trust it. Apply a candidate fix,
+   re-run *full* validation, and commit the result only if it now passes — otherwise
+   quarantine.
+2. **Correctness over recovery.** Never emit a wrong-but-valid-looking record; when in
+   doubt, quarantine. No reconstruction of missing *data* characters. The one sanctioned
+   reconstruction is a missing *checksum* digit, which is deterministically recomputable —
+   and even that is a distinct, weaker repair tier with its own reporting.
+3. **Constant memory.** Files stream; the pairing state machine holds at most two lines.
+   A 3.2 GB file must never be loaded whole.
+4. **One validator definition.** "Perfect" is defined once, in `tle.py`. Never add a
+   second, divergent validation path.
+
+**Report outcomes faithfully.** If tests fail, say so with the output. If a verification
+step was skipped, say that rather than implying it ran. Never claim "all tests pass" when
+output shows failures.
+
+## The corpus (`data/`, git-ignored)
+
+- `data/source/` — 29 raw `tle*.txt` files (~30 GB) plus `TLEs.zip` (~12 GB). Inputs.
+- `data/output/` — where `clean` writes `cleaned/`, `broken/`, and `report.md`. Outputs.
+- The whole `data/` tree is git-ignored — ~42 GB — and must never be staged or committed.
+- **Never read a corpus file whole** — the largest is 3.2 GB. Sample with `head`, `awk`,
+  or `sed -n`.
+
+## Code Style
+
+- Python 3.11. Concise one-paragraph docstrings on every public module, function, and
+  class — match that established style; do not expand to Args/Returns/Raises blocks.
+- `ruff` for linting and formatting, configured in `pyproject.toml` (rule sets `E`, `F`,
+  `I`, `UP`, `B`, `SIM`; 88-column lines).
+- `src/` layout — all package code lives under `src/lintle/`.
+- Run `uv run ruff check .` and `uv run ruff format --check .` before committing.
+
+## Project Layout
+
+```
+src/lintle/
+├── __main__.py    # python -m lintle entry point
+├── __init__.py    # __version__, stem() filename helper
+├── cli.py         # argparse, globbing, parallel workers, live progress, Ctrl-C handling
+├── pipeline.py    # streams a file in binary, pairs 1/2 lines into records, routes them
+├── repair.py      # speculative fixes, each confirmed by tle.py before commit
+├── report.py      # FileStats, the .broken.txt sidecar writer, the run report
+└── tle.py         # the validator — column layout, checksum, semantic ranges, pairing
+```
+
+Module dependencies point one way only: `cli.py → pipeline.py → repair.py → tle.py`.
+
+→ See [`README.md`](README.md) for the architecture, usage, and data flow.
+→ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, testing, and the git workflow.
+
+## Commands
+
+```bash
+uv sync                            # Install, including dev deps (sgp4, pytest, ruff)
+uv run pytest                      # Full test suite
+uv run pytest tests/test_tle.py::TestComputeChecksum   # A single test class
+uv run pytest --cov=lintle --cov-report=term-missing --cov-branch  # Tests + coverage
+uv run ruff check .                # Lint
+uv run ruff format --check .       # Format check
+uv run lintle validate          # Audit data/source/ (read-only)
+uv run lintle clean             # Clean data/source/ -> data/output/
+```
+
+## Working Style
+
+- **Use agents** for codebase exploration and multi-step research tasks.
+- **Always verify** after a change: run `uv run pytest`, `uv run ruff check .`, and
+  `uv run ruff format --check .`, and report the actual output.
+- Build order, if rebuilding from the spec (§12): `pyproject.toml` → `tle.py` (test-first,
+  it is the correctness oracle) → `repair.py` → `pipeline.py` → `report.py` / `cli.py`.
+
+## Verification
+
+After completing edits, run these before reporting success:
+
+```bash
+uv run pytest                      # Must pass
+uv run ruff check .                # Must pass
+uv run ruff format --check .       # Must pass
+```
+
+If any fail, report the actual output — do not suppress or simplify failures.
+
+## File Guidelines
+
+- Never read a corpus file whole — sample with `head`, `awk`, or `sed -n`.
+- When renaming a function or variable, search for direct calls, string literals
+  containing the name, re-exports, and test references.
+- Prefer files with one clear responsibility; keep functions focused and readable.
+
+## Conventions
+
+- Design docs live in `docs/superpowers/specs/`, named `YYYY-MM-DD-topic.md`. The design
+  doc carries a revision log in its header — keep it current when the design changes.
+- Tests are grouped into `Test*` classes, one per unit or behaviour under test.
+- Git: never commit to `main` directly; branch (`feature/`, `bugfix/`, `chore/`); use
+  conventional commits (`feat:`, `fix:`, `docs:`, `test:`, `style:`, `chore:`).
+- Versioning: `pyproject.toml`'s `[project] version` is the single source of truth;
+  `src/lintle/__init__.py` resolves `__version__` from it at runtime via
+  `importlib.metadata`. Bump it once, add a `CHANGELOG.md` entry — see CONTRIBUTING.md
+  for the release flow.

lintle-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing to lintle
+
+## Prerequisites
+
+- **Python 3.11+**
+- **[uv](https://docs.astral.sh/uv/)** — Python package and project manager
+
+## Setup
+
+```bash
+git clone <repo-url>
+cd TLEs
+uv sync
+```
+
+`uv sync` installs Python 3.11 if needed, creates a `.venv/`, and installs the project
+plus all dev dependencies (`pytest`, `pytest-cov`, `sgp4`, `ruff`) from `uv.lock`.
+
+### Managing dependencies
+
+Dependencies are declared in `pyproject.toml` and pinned in `uv.lock` (committed to git).
+
+```bash
+uv add --group dev <pkg>   # Add a dev-only dependency
+uv sync                    # Reinstall from the lock file (after a pull)
+```
+
+The **runtime has no third-party dependencies** — `lintle` is pure standard library.
+`sgp4` is a dev-only test oracle and must never be imported at runtime.
+
+## Running
+
+```bash
+uv run lintle validate          # Read-only audit of data/source/
+uv run lintle clean             # Write cleaned output to data/output/
+```
+
+`uv run` executes a command inside the project virtual environment — no manual
+activation needed.
+
+## Testing
+
+```bash
+uv run pytest                      # Run all tests
+uv run pytest -x                   # Stop on first failure
+uv run pytest -k "checksum"        # Run tests matching an expression
+uv run pytest tests/test_tle.py    # Run one file
+uv run pytest tests/test_tle.py::TestComputeChecksum   # Run one class
+```
+
+### Coverage
+
+```bash
+uv run pytest --cov=lintle --cov-report=term-missing --cov-branch
+```
+
+This reports line and branch coverage, listing uncovered lines in the `Missing` column.
+
+### Test layout
+
+Tests are grouped into `Test*` classes, one per unit or behaviour under test.
+
+| File | What it covers |
+|------|----------------|
+| `test_tle.py` | The validator: checksum, column layout, semantic ranges, record pairing |
+| `test_repair.py` | Speculative line/record repair and the rejection categories |
+| `test_pipeline.py` | Streaming I/O, line pairing, per-file processing, progress, temp-file safety |
+| `test_report.py` | `FileStats`, the `.broken.txt` sidecar, summaries, the run report |
+| `test_cli.py` | Argument parsing, path discovery, exit codes, elapsed-time formatting |
+| `test_integration.py` | End-to-end: golden output, idempotence, re-validation |
+| `test_oracle.py` | Cross-checks a known-good TLE against the trusted `sgp4` parser |
+
+`conftest.py` holds the shared `line1` / `line2` fixtures — a canonical, known-good TLE.
+
+## Linting & Formatting
+
+[Ruff](https://docs.astral.sh/ruff/) handles both linting and formatting. Its
+configuration lives in `pyproject.toml` under `[tool.ruff]` (rule sets `E`, `F`, `I`,
+`UP`, `B`, `SIM`; 88-column lines).
+
+```bash
+uv run ruff check .                # Lint
+uv run ruff check . --fix          # Lint with auto-fix
+uv run ruff format .               # Format
+uv run ruff format --check .       # Check formatting (no writes)
+```
+
+Run both before committing:
+
+```bash
+uv run ruff check . && uv run ruff format --check .
+```
+
+## Verification
+
+Before reporting any change as done, run — and report the actual output of:
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+Never claim success without the output. If a check fails, report the failure.
+
+## Git Workflow
+
+- **Never commit directly to `main`.** Branch for every change.
+- Branch names: `feature/<desc>`, `bugfix/<desc>`, `chore/<desc>` — lowercase, hyphens.
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`,
+  `docs:`, `test:`, `refactor:`, `style:`, `chore:`.
+- Open a pull request to `main`; run the verification commands above before merging.
+
+## Versioning
+
+Semantic versioning (`MAJOR.MINOR.PATCH`). The version lives in **one place** —
+`pyproject.toml`'s `[project] version` field — and is resolved at runtime from the
+installed distribution metadata by `src/lintle/__init__.py`:
+
+```python
+from importlib.metadata import PackageNotFoundError, version as _dist_version
+
+try:
+    __version__ = _dist_version("lintle")
+except PackageNotFoundError:  # source checkout that was never installed
+    __version__ = "0.0.0+local"
+```
+
+Because the lookup needs the project to be installed (even editable), keep `uv sync`
+current — every dev workflow in this repo already does.
+
+Release flow:
+
+1. Bump `version` in `pyproject.toml`.
+2. Add a new `## [X.Y.Z] - YYYY-MM-DD` section at the top of `CHANGELOG.md` with
+   `### Added` / `### Changed` / `### Fixed` subsections (see Keep a Changelog).
+3. Run the verification commands (`uv run pytest`, `uv run ruff check .`,
+   `uv run ruff format --check .`) and report the actual output.
+4. Commit on a `chore/release-X.Y.Z` branch and open a PR to `main`. Tag and publish
+   after merge.
+
+Nothing else needs to change — `lintle --version`, the `report.py` headers, and any
+downstream `from lintle import __version__` import all pick the new value up from
+`pyproject.toml` automatically.

lintle-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrei Lavrenov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.