mirror of
https://github.com/pewdiepie-archdaemon/odysseus.git
synced 2026-10-06 23:12:22 +02:00
Léo
10cb8fc669
`lab` and the public `dev` line share only the repository's first commit as a merge base, so `git log lab..dev` lists two thousand commits that are almost all already present on both sides under different SHAs. Nothing in that output says which public fixes never reached `lab`, which is the only question that matters before `lab` becomes a release. `scripts/ref_parity_audit.py` samples the most distinctive added lines from each commit in the range and searches the other tree for them with `git grep -F`, then reports the file-level presence diff. The two complement each other: a commit whose probes are all found while one of the files it added is missing from the target is a fix whose production change was reproduced without its test, which the line sampling alone cannot see. Probes are stripped of indentation and searched for anywhere in the tree, so a port that moved or was re-indented still reads as present. Verdicts are absent / partial / present / no-probe, and the report says outright that the commit verdicts are a heuristic while the two file lists are exact. Read-only by construction: `git log`, `show`, `diff`, `grep`, `ls-tree` and `merge-base` only, no remote access, and it does not import the app package.
90 lines
4.4 KiB
Markdown
90 lines
4.4 KiB
Markdown
# Ref parity audit
|
|
|
|
`scripts/ref_parity_audit.py` reports which commits on one git ref left no trace
|
|
in another, and which files exist on one and not the other. It is read-only: it
|
|
runs `git log`, `git show`, `git diff`, `git grep`, `git ls-tree` and
|
|
`git merge-base`, writes nothing to the repository, touches no remote, and does
|
|
not import the application package.
|
|
|
|
## Why it exists
|
|
|
|
`lab` and the public `dev` line share only the repository's first commit as a
|
|
merge base, so `git log lab..dev` lists thousands of commits — nearly all of
|
|
which are in fact present on both sides, having arrived under different SHAs. A
|
|
plain log tells you nothing about what is actually missing.
|
|
|
|
The question that matters before `lab` becomes a release is narrower: is there a
|
|
fix on the public line that never reached `lab`? This script answers that by
|
|
sampling distinctive added lines from each commit and searching the other tree
|
|
for them.
|
|
|
|
## Running it
|
|
|
|
```bash
|
|
git remote add public https://github.com/odysseus-dev/odysseus.git # once
|
|
git fetch public dev --no-tags
|
|
|
|
scripts/ref_parity_audit.py --source public/dev --target lab --since 2026-08-10
|
|
```
|
|
|
|
Roughly 30 seconds for a 100-commit window; it grows linearly, so bound a wide
|
|
audit with `--since`. Add `--format json` for a machine-readable report and
|
|
`--output PATH` to write it to a file.
|
|
|
|
| Flag | Effect |
|
|
|---|---|
|
|
| `--source REF` | The ref whose commits are audited. Required. |
|
|
| `--target REF` | The ref searched for traces of them. Required. |
|
|
| `--since` / `--until` | Bound the commit range. Both filter **committer** date, which is also the date the report prints. |
|
|
| `--traversal linear` | Default. Individual authored commits, merges dropped. Finds a fix that arrived on a side branch. |
|
|
| `--traversal first-parent` | One row per merge into the source branch, which reads as one row per merged pull request. |
|
|
| `--probes N` | Probe lines sampled per commit, default 4. |
|
|
| `--exclude GLOB` | Extra path glob whose lines are not used as probes. Repeatable. |
|
|
| `--no-default-excludes` | Drop the built-in vendored / lockfile / binary exclusions. |
|
|
| `--top N` | Rows shown per file list, default 50. |
|
|
| `--repo PATH` | Repository to run in. Defaults to this checkout. |
|
|
|
|
## How a verdict is reached
|
|
|
|
For each commit in `target..source`, the script takes the patch with no context
|
|
lines, collects the added lines, drops the ones from vendored code, committed
|
|
build output, lockfiles and binaries, and keeps those that are at least 24
|
|
characters long and name at least two distinct identifiers. It ranks what is
|
|
left by how many distinct identifiers each line carries (length breaks ties),
|
|
takes the top `--probes`, and searches the whole target tree for each one with
|
|
`git grep --fixed-strings`.
|
|
|
|
Probes are stripped of leading and trailing whitespace, so a change that was
|
|
re-indented on the target still counts as present. The whole target tree is
|
|
searched, not the same file, because a ported fix routinely moves.
|
|
|
|
| Verdict | Meaning |
|
|
|---|---|
|
|
| **absent** | No probe found anywhere in the target. Treat as a real gap and read the diff. |
|
|
| **partial** | Some probes found. **Inconclusive.** A line can be rewritten by a refactor on the target and still be the same change. |
|
|
| **present** | Every probe found. The change is almost certainly there in some form. |
|
|
| **no-probe** | Nothing to sample: a deletion-only commit, or one touching only excluded paths. No verdict. |
|
|
|
|
## What is exact and what is a heuristic
|
|
|
|
**Exact:** the two file-presence lists. They come from `git ls-tree` on both
|
|
refs, so a file in "on the source and not the target" is definitely not there.
|
|
|
|
**Heuristic:** every commit verdict. It samples at most four lines out of a
|
|
diff that may be hundreds, and a probe can be absent because the area was
|
|
refactored rather than because the change was never made.
|
|
|
|
The two complement each other in a specific and useful way. A commit that reads
|
|
**present** while one of the files it added shows up in the source-only list is
|
|
almost always a fix whose production change was reproduced on the target without
|
|
its test. The line sampling cannot see that; the presence diff can.
|
|
|
|
Read the diff before porting anything. The verdicts say where to look, not what
|
|
to do.
|
|
|
|
## Tests
|
|
|
|
`tests/test_ref_parity_audit.py`. The end-to-end cases build a throwaway
|
|
repository with two branches off one root, so the verdicts come from git's own
|
|
`grep` and `diff` rather than from a fake.
|