closure_drift

closure_drift

Does v1.4.2 mean one thing in your repository?

$ git clone -q https://github.com/psf/requests && cd requests
$ closure-drift --compare v2.16.0 v2.16.1
A  v2.16.0  (commit bcd0e170ac20)
   label    2.16.0
   closure  3d2886b87c2a7b94   17 file(s)
B  v2.16.1  (commit f687e9f3d8b0)
   label    2.16.0
   closure  696b71ed6023f563   18 file(s)
   changed    requests/__init__.py
   only in B  requests/packages.py

==============================================================
DIFFERS UNDER ONE LABEL: both declare 2.16.0, and the code differs
in 2 path(s). If both were published, that label names two things.

Check it without this tool: git show v2.16.1:requests/__version__.py says 2.16.0. closure_drift reads the git history, not a package index: it shows what the tags contain, not which commit a published package was built from.

A version is a string a human edits. When two releases share a version and differ in code, one address names two artefacts — and nothing notices, because the version is all that was recorded.

One command checks it. Read-only, one file, no dependencies, no network.

Run it

curl -sO https://raw.githubusercontent.com/luizfnsilva/closure_drift/v1.2.0/closure_drift.py
python3 closure_drift.py            # inside any git repository

That measures your repository. ./reproduce.sh is something else: it validates closure_drift itself (its test suites, a long run) and does not look at your repository.

or pipx run --spec git+https://github.com/luizfnsilva/closure_drift@v1.2.0 closure-drift. Needs Python 3.9+ and git. To see the three possible answers first: python3 examples/demo.py, or read docs/DEMOS.md.

Check before you tag

--would-tag answers: if I tag this commit now, does its version already name different code?

# GitHub Actions
- uses: actions/checkout@v4
  with: { fetch-depth: 0 }
- uses: luizfnsilva/closure_drift@v1.2.0

Push the workflow before the first tag: a tag pushed together with the workflow that should run on it may not start it (then run it by hand, with workflow_dispatch: in its on:). mode: measure concludes only from two distinct labels; on the first release it is inconclusive, exit 2, so gate with would-tag from the first tag.

# pre-commit, on git push
- repo: https://github.com/luizfnsilva/closure_drift
  rev: v1.2.0
  hooks: [{ id: closure-drift-would-tag }]

Other pipelines: docs/CI.md.

For AI agents

An agent that tags and publishes can ask the same question first, through a Model Context Protocol (MCP) server, standard library only, with a would_tag tool:

claude mcp add closure-drift -- uvx --from git+https://github.com/luizfnsilva/closure_drift closure-drift-mcp

Codex CLI, Gemini CLI, Cursor, VS Code, Windsurf, and a rule to paste into AGENTS.md, CLAUDE.md or .cursorrules: integrations/. The server makes the check available; the agent has to call it and respect the answer. The barrier is CI.

The answer

Exit 0 means clean and nothing else. No input we tried produces a traceback, and no failure exits 1.

• label — the version your project declares at each tag: in its build files, in the module they point to, or the tag itself when the version is derived from it
• closure — SHA-256 over (path, git object id) of the files that determine your output

The report also says how many tags it could not compare.

Options

Settings can be committed in .closure-drift.json. Flags override it, except beside components, where they need --component; a broken file is refused.

A monorepo declares its components, and gets one verdict each:

{"components": {
  "python": {"tags": ["py-*"], "version_file": "py/pyproject.toml", "closure": ["py/**"]},
  "rust":   {"tags": ["rs-*"], "version_file": "rs/Cargo.toml",     "closure": ["rs/**"]}
}}

The answer is drift if any component is in drift, clean if all are clean, otherwise incomplete. Components are declared, never guessed. A gate in such a repository passes --component NAME to --would-tag.

What it found

The 100 most-downloaded PyPI projects with a public repository, at the defaults, measured with a build of 0.10.0 that prints the same reports as the release — rule and method fixed before the first run; no repository tuned (full table and every collision):

A version label names two different code states in 29 of the 88 decided, 29 of all 100. Each of the 87 labels is in collisions.tsv, one line per tag involved, reproducible by hand:

$ closure-drift --compare v2.16.0 v2.16.1        # in psf/requests
DIFFERS UNDER ONE LABEL: both declare 2.16.0, and the code differs in 2 path(s).

A collision is not a verdict on a project. The usual causes are a tag created without bumping the version, branch markers such as 7.x, and tag families in a monorepo. A first run, kept in the repository, decided only 63 of 100 — it read the version from one file chosen at HEAD — and that is why this release finds the label where each project keeps it.

Six reference repositories, measured with 1.0.0 at every tag (tools/reference/):

Two causes: a release tagged without bumping the version (impress.js), and tag families sharing one version file (lodash). Neither project is badly run. --would-tag addresses the first, --tags or components the second.

Limits

• It never runs your code and attests nothing. clean is about addressing, not reproducibility.
• A change of file mode alone is not seen, unless --modes.
• Never in the closure: folders test/, tests/, spec/, docs/, vendor/, node_modules/, .git/; files named *_test.*, *.test.*, *.md.
• The default closure globs are a guess. Pass --closure.
• Labels are compared as written: 1.0 and 1.0.0 are two labels, unless --label-equality version.
• It reads git, not a package index: a tag never released counts, unless --published lists what was. A tag left off the list is left out of the analysis, not shown unpublished.
• How the label is found is a set of rules, not a build: docs/LABELS.md.
• In a gate, pass --version-file, or --published: the rules can still read the wrong file when one tag happens to agree with it.

Every failure found so far: docs/FAILURES.md. More: SCOPE.md, docs/WHY.md.

Safety

It starts git and, for a version pattern you supply, itself; nothing else. It never writes to the repository, and does not run commands named in that repository's git config. What is defended and what is not: THREAT_MODEL.md. Reporting: SECURITY.md.

Tests

Four suites, each pre-registered before the code. Scores are never added together.

CI runs the same four on Linux (Python 3.9 to 3.14), macOS and Windows; what each platform could not run is in tests/RECORD.md. These scores describe the cases executed, not inputs nobody tried. ./reproduce.sh runs all of it. The 100 projects of the study are also a regression corpus, pinned to recorded commits: 1.2.0 gives the recorded answer on all 100, as predicted before it ran (tools/regression/).

Ten large repositories (the Linux kernel, LLVM, CPython and seven more), protocol written first. Every tag of the kernel: 6.5 GB for the whole process tree with 0.9.1, 900 MB with 1.0.0. 0.9.1 gave three wrong or near-empty answers there; 1.0.0 gives none of them. With a declared version file (docs/LABELS.md) every tag of the kernel is compared: clean, 947 of 947, in four minutes. tools/benchmark/READING.md.

Send a result

RESULTS.md is for measurements made by someone other than the author. It is still empty. closure-drift --json > result.json, then open an issue or write to lfnsilva.invest@gmail.com. A result showing the tool is wrong is the most useful kind.

Version

1.2.0 names a version file one level down, says whether a dirty tree touches the closure, and writes UTF-8 when the output is not a terminal (from issue #12). 1.1.3 says when to use --explain or --compare, and --tags or --published; the detector is unchanged. 1.1.2 installs the MCP server in one line (closure-drift-mcp); the detector is unchanged. 1.1.1 fixes O11: a version file over the size limit (1 MB) is named and the answer is incomplete, never clean. It adds integrations/ for AI agents. 1.1.0 (script sha256 e2a67a5a9148fe273d2c95ad4bcce9bc589a43711fc34443a4a9491fde575913) adds --published, three version sources, an earlier refusal and two opt-in comparisons; with no new option, results change only under --at commits (CHANGELOG.md). What it had to meet was written first (tests/PREREGISTRATION.md §16), and a reviewer who did not write it found 13 problems before the tag (docs/REVIEW-1.1.0.md). SCOPE.md says what stays stable until 2.0.

Apache-2.0. Cite the version DOI, under concept DOI 10.5281/zenodo.21763931 (CITATION.cff). Planned next: ROADMAP.md.