runprov 0.1.0__tar.gz

runprov-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# A provenance tool whose own repository tracks a stale coverage database is a poor
+# advertisement. `.coverage` was committed until 2026-08-11.
+__pycache__/
+*.py[cod]
+.coverage
+.coverage.*
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+
+# Written by running `examples/summarise.py` from the repository. The example configures
+# the root as this repository, so its history lands here — which is the correct behaviour
+# and not something to commit.
+/provenance/
+examples/results/
+
+# THE TWO INTERNAL DRAFTS, untracked 2026-09-08 when the repository went public.
+#
+# L-08 had already kept `PUBLISHING.md` and `LICENSING.md` out of the sdist and off the
+# README, on the grounds that they address one person and keep superseded reasoning on
+# purpose. A private repository made that enough. A public one does not: below their
+# "SUPERSEDED IN PART" banners they still recommend MIT with the CHU as holder, which is
+# neither the licence nor the rights holder the source headers assert — and the DRCI has
+# not yet answered which is correct. A reader following the repository link from the letter
+# that asks that question would find the project appearing to answer it two ways.
+#
+# They stay on disk because the reasoning in them is worth having; they are simply not the
+# project's public position. Untracking is not deleting, and it does not remove them from
+# history — that would need a rewrite.
+/LICENSING.md
+/PUBLISHING.md
+
+# AGENT WORKING STATE. `.claude/` is a tool's scratch directory, and it was NOT ignored — it
+# happens to be empty, so nothing has leaked, but a `git add -A` would have committed whatever
+# it contained into a public repository. That is the shape of the incident this file's first
+# rule records: a swap file committed by the initial `git add -A`, holding text that had been
+# written and deliberately cut.
+#
+# Worse here than a swap file, because the repository is public and the directory can hold
+# session transcripts, worktrees and prompts. Nothing belongs in the project's history that
+# nobody chose to put there.
+/.claude/

runprov-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+# Same checks as CI, run locally. `pre-commit install` once, then a failing push is
+# something you find in a second rather than in a queue.
+repos:
+  # PINNED TO THE VERSION THE GATE ENFORCES, and it has to stay that way. This said v0.6.9
+  # against a gate on 0.16.2 -- ten minor versions apart -- and with `--fix` that is worse
+  # than a version skew: the hook REWRITES code to satisfy an old ruff, then CI rejects it
+  # with the new one, so the tool that exists to catch a failure early creates one. There is
+  # a test asserting these two agree.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      # This package has no data files. Anything large is a mistake, and a provenance
+      # tool that ships someone's parquet by accident would be a poor advertisement.
+        args: [--maxkb=200]
+      - id: check-merge-conflict

runprov-0.1.0/.ruff.toml

@@ -0,0 +1,79 @@
+# Ruff config for the runprov package, kept beside the code so it travels with it into the
+# standalone repository. Ruff replaces black + isort + flake8: `ruff format` is
+# black-compatible byte for byte, and the `I` rules ARE isort.
+#
+# target-version is py310, NOT the repository's py311. Without it, UP017 rewrites
+# `dt.timezone.utc` to `dt.UTC` — an alias added in 3.11 — and the package silently stops
+# importing on the oldest interpreter it claims to support. A linter that breaks your
+# declared support floor is worse than no linter.
+line-length = 100
+target-version = "py310"
+
+[lint]
+select = ["E", "F", "I", "N", "UP", "ANN", "S", "B", "C4", "PT", "RUF"]
+
+# RUF003 flags an "ambiguous" EN DASH in a comment and suggests a hyphen. The comment is
+# the copyright notice, and the en dash is part of "Assistance Publique – Hôpitaux de
+# Paris" -- the institution's registered name. A linter does not get to respell a legal
+# entity, and a copyright line that names the holder inexactly is worse than a lint
+# warning. Ignored deliberately, everywhere, for that reason.
+ignore = ["RUF003"]
+
+[lint.per-file-ignores]
+# project.py holds the ONE subprocess call in the package: `git`, resolved from PATH.
+#   S603  the argv is a literal program name plus the caller's own arguments, no shell.
+#   S607  `git` is deliberately taken from PATH. Pinning an absolute path would break
+#         every environment whose git is not where this machine's is, which is most.
+# Scoped to the file rather than inline because `ruff format` moves which physical line a
+# multi-line call reports on, and an inline noqa silently stops applying when it does.
+"project.py" = ["S603", "S607"]
+# `"__main__.py" = ["ANN401"]` used to sit here and suppressed NOTHING: that file has
+# no `Any` annotation, and its stated reason ("main returns an int exit code and its
+# locals are obvious") describes ANN201/ANN001, a different rule family. A per-file
+# ignore that ignores nothing is the ADR-015 shape inside the linter's own config --
+# a rule declared and not in effect. Removed rather than corrected: there was nothing
+# to correct.
+
+# Tests are not library code and linting them as if they were produces 198 findings that
+# all say the same thing. What is switched off and why:
+#   S101   `assert` IS the test. Flagging it is the rule misapplied.
+#   ANN    a test's arguments are fixtures and its return is None; annotating them adds
+#          nothing a reader did not already know.
+#   S108   /tmp paths in fixtures are the point.
+#   PT011  pytest.raises(Exception) is deliberate where the type IS the assertion.
+#   PT018  a compound assert is often the clearest statement of one fact.
+#   PT012  the crash tests need a `with Run(...)` INSIDE pytest.raises; that nesting is
+#          the behaviour under test, not sloppiness.
+#   RUF012 test doubles declare class attributes to imitate a real object's shape. The
+#          rule guards against shared mutable state across instances; a stub built and
+#          discarded inside one test has no instances to share anything with.
+#   S603/S607  the tests shell out to `git` to build a real repository to detect. That is
+#          the subject under test, not an injection risk.
+# ci.py exists to run other tools; S603 is the rule describing its entire job. Scoped to
+# the file, with the reason here, for the same reason as project.py: an inline directive
+# detaches the next time the formatter moves the line it sits on.
+# `run.py` and `__main__.py` each execute a program the CALLER named: `run.tool("samtools")`
+# asks a binary for its version, and `runprov exec -- <cmd>` exists to run the command in
+# front of it. S603 describes exactly what those two do on purpose, and there is no
+# untrusted input to check -- the argv came from the person typing it. Scoped to the files
+# rather than inline, for the reason given above project.py: `ruff format` moves which
+# physical line a multi-line call reports on, and a detached noqa is a coincidence.
+"run.py" = ["S603", "S607"]
+"__main__.py" = ["S603"]
+"ci.py" = ["S603"]
+
+# `examples/` is teaching code that a reader copies, and it is linted as such. What is
+# switched off and why:
+#   ANN    an example annotated to library standards reads like library code, which is
+#          exactly the wrong signal for a file whose job is to show the shortest honest
+#          version of a call. `summarise.py` keeps its annotations; the format matrix is a
+#          table of lambdas where they would be noise.
+#   S301   `pickle.loads` IS the format under test in format_compatibility.py. The rule is
+#          about untrusted input; this input was written two lines earlier by the same file.
+#   S314   likewise `ElementTree.parse`, which is how you check an SVG is still well-formed.
+#   N802   `CASE(...)` is a table constructor, and shouting it is what makes the table
+#          readable as data rather than as calls.
+"examples/*" = ["ANN", "S301", "S314", "N802"]
+
+"tests/*" = ["S101", "S105", "S106", "S108", "ANN", "PT011", "PT012", "PT018", "RUF012", "S603", "S607",
+             "N802"]