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.

Three ways in

Try it now (recommended first). See the three answers on tiny repositories it builds and deletes, then measure yours:

git clone -q https://github.com/luizfnsilva/closure_drift && python3 closure_drift/examples/demo.py

python3 closure_drift/closure_drift.py /path/to/your/repo

Or without cloning: curl -sO https://raw.githubusercontent.com/luizfnsilva/closure_drift/v1.5.0/closure_drift.py then python3 closure_drift.py inside any git repository. Needs Python 3.9+ and git. The last lines say what to do next. (./reproduce.sh is something else: it validates closure_drift itself, a long run, and does not look at your repository.)

With your agent. Install the skill (skills/closure-drift/), which tells the agent when to check before a tag and how to read the answer: gh skill install luizfnsilva/closure_drift closure-drift --agent claude-code (or codex, cursor, gemini-cli, github-copilot, …). In Claude Code, skill and MCP server together: /plugin marketplace add luizfnsilva/closure_drift. Other clients: integrations/.

In CI, the barrier that holds when nobody remembers to check: docs/CI.md. Exit 0 pass, 1 drift, 2 nothing decided (a failure by default).

Check before you tag

--would-tag answers: *if I tag this commit now, does its version already name different code?* After tagging, --tag NAME answers: *does this tag name the version its commit declares?* A tag pushed before the version was bumped fails there; in the study it is how 79 of the 87 labels in drift came about. On a tag push the Action runs --tag; on any other push, --would-tag.

# GitHub Actions

• uses: actions/checkout@v4 with: { fetch-depth: 0 }
• uses: luizfnsilva/closure_drift@v1.5.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 the default mode from the first tag.

# pre-commit, on git push

• repo: https://github.com/luizfnsilva/closure_drift rev: v1.5.0 hooks: [{ id: closure-drift-would-tag }]

Other pipelines: docs/CI.md.

For AI agents

An agent needs two things: to know when to check (before it creates a tag, bumps a version or publishes), and a way to run the check. The skill gives the first; the MCP server, the second.

1. The skill, in any agent that reads skills: gh skill install luizfnsilva/closure_drift closure-drift --agent claude-code (or codex, cursor, gemini-cli, github-copilot, …).
2. In Claude Code, both at once, as a plugin: /plugin marketplace add luizfnsilva/closure_drift, then /plugin install closure-drift@closure-drift.
3. The MCP server alone (standard library only, a would_tag tool), for other clients:

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/. An agent can still skip the check; 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. A --closure glob that names one of these folders brings it in (--closure 'vendor/**'); .git/ and the file patterns never.
• 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.5.0 gives the recorded answer on all 99 still checkable (one tag of apache/arrow moved upstream), 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 o