bug-age 2.0.0__tar.gz → 2.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. bug_age-2.1.0/PKG-INFO +99 -0
  2. bug_age-2.1.0/README.md +82 -0
  3. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/__init__.py +1 -1
  4. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/bundle.py +64 -20
  5. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/cli.py +43 -9
  6. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/data/bundle.schema.json +5 -4
  7. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/data/explorer.html +8 -6
  8. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/mcp.py +4 -4
  9. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/pipeline.py +63 -4
  10. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/runner.py +137 -14
  11. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/sweep.py +54 -15
  12. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/szz.py +3 -2
  13. bug_age-2.1.0/bug_age.egg-info/PKG-INFO +99 -0
  14. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age.egg-info/SOURCES.txt +3 -0
  15. {bug_age-2.0.0 → bug_age-2.1.0}/pyproject.toml +2 -2
  16. {bug_age-2.0.0 → bug_age-2.1.0}/tests/test_bundle.py +84 -2
  17. {bug_age-2.0.0 → bug_age-2.1.0}/tests/test_explorer_cli_mcp.py +39 -0
  18. {bug_age-2.0.0 → bug_age-2.1.0}/tests/test_method_a.py +31 -1
  19. {bug_age-2.0.0 → bug_age-2.1.0}/tests/test_oracle.py +36 -0
  20. bug_age-2.1.0/tests/test_pipeline.py +87 -0
  21. bug_age-2.1.0/tests/test_runner_limits.py +79 -0
  22. bug_age-2.1.0/tests/test_staging.py +124 -0
  23. {bug_age-2.0.0 → bug_age-2.1.0}/tests/test_sweep.py +9 -9
  24. {bug_age-2.0.0 → bug_age-2.1.0}/tests/test_sweep_scenarios.py +28 -7
  25. bug_age-2.0.0/PKG-INFO +0 -301
  26. bug_age-2.0.0/README.md +0 -284
  27. bug_age-2.0.0/bug_age.egg-info/PKG-INFO +0 -301
  28. {bug_age-2.0.0 → bug_age-2.1.0}/LICENSE-APACHE +0 -0
  29. {bug_age-2.0.0 → bug_age-2.1.0}/LICENSE-MIT +0 -0
  30. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/__main__.py +0 -0
  31. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/_compat.py +0 -0
  32. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/catalog.py +0 -0
  33. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/data/Dockerfile +0 -0
  34. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/explorer.py +0 -0
  35. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/feasibility.py +0 -0
  36. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/git.py +0 -0
  37. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/repros.py +0 -0
  38. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/schema.py +0 -0
  39. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age/timetravel.py +0 -0
  40. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age.egg-info/dependency_links.txt +0 -0
  41. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age.egg-info/entry_points.txt +0 -0
  42. {bug_age-2.0.0 → bug_age-2.1.0}/bug_age.egg-info/top_level.txt +0 -0
  43. {bug_age-2.0.0 → bug_age-2.1.0}/setup.cfg +0 -0
bug_age-2.1.0/PKG-INFO ADDED
@@ -0,0 +1,99 @@
1
+ Metadata-Version: 2.4
2
+ Name: bug-age
3
+ Version: 2.1.0
4
+ Summary: Measure how long bugs lived in a git repository, counting only bugs whose fix commit message says fix, bug or hotfix.
5
+ License: MIT OR Apache-2.0
6
+ Project-URL: Source, https://github.com/jacob-adm/bug-age
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Environment :: Console
9
+ Classifier: Topic :: Software Development :: Quality Assurance
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: License :: OSI Approved :: Apache Software License
12
+ Requires-Python: >=3.11
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE-APACHE
15
+ License-File: LICENSE-MIT
16
+ Dynamic: license-file
17
+
18
+ # bug-age
19
+
20
+ Measures how long fixed bugs lived in a git repository, using only its history. A bug counts only when the commit that fixed it says so in its message (*fix*, *bug*, *hotfix*); a bug fixed under any other message, or never fixed, is not counted. For each counted bug it reports commits elapsed, calendar days, releases shipped, and churn between the commit that introduced it and the fix.
21
+
22
+ It uses two independent methods and compares them:
23
+
24
+ - **Method A, blame-based (SZZ-style).** Runs `git blame` on the lines a fix changed and names the commit that last touched them as the likely introducer. This is fast and needs only git, but it can be wrong. Known failure cases: ghost commits, formatting-only changes, and introducers that were not the latest toucher.
25
+ - **Method B, behavioral sweep.** Takes a regression test that fails before the fix and passes after it, then replays that test across history in a hermetic per-commit Docker environment. The result is the first failing commit, the last passing commit, and every untestable commit with a reason.
26
+
27
+ Every number comes from scripts. AI helped write the code, the Method B regression tests and the article prose, but no model produces or changes a number. See [What is deterministic and what uses AI](https://github.com/jacob-adm/bug-age/blob/main/docs/method.md#what-is-deterministic-and-what-uses-ai). bug-age supports Rust crates today.
28
+
29
+ What you get, and the three names the documentation uses for it:
30
+
31
+ - **Report.** What a run produces: the result files in `results/<name>/` and one bundle, `dist/<name>/bundle.json`, which holds every number. Each repository you run gets its own report.
32
+ - **Explorer.** A viewer. It is a static HTML page you build from one or more bundles to browse their reports. It holds no results of its own and runs no analysis.
33
+ - **Live example.** One explorer, built from the reports of the two [example runs](https://github.com/jacob-adm/bug-age/blob/main/docs/example-runs.md) and published online. It is a snapshot: running bug-age on other repositories does not change it.
34
+
35
+ To see the output first, [open the live example](https://claude.ai/artifact/UDw6jyeA4zMDGhnzL7Typb).
36
+
37
+ ## Requirements
38
+
39
+ - Python 3.11 or later, standard library only.
40
+ - git.
41
+ - Docker, only for the feasibility check and Method B.
42
+ - Linux or macOS, both tested in CI.
43
+ - It measures Rust crates today; other languages are planned.
44
+
45
+ ## How it works
46
+
47
+ 1. **Find the fixes.** bug-age reads the commit history and lists every commit whose message says it fixes a bug (*fix*, *bug*, *hotfix*). A fix whose message doesn't say so is not counted.
48
+ 2. **Find where each bug came from.** For each fix, git shows which earlier commit last wrote the lines the fix changed. That commit is the likely cause (Method A).
49
+ 3. **Count how long it lived.** From that commit to the fix, bug-age counts the days, the commits and the releases that shipped with the bug.
50
+ 4. **Check with a test, if you want.** Write a test that fails before the fix and passes after it. bug-age runs it at older commits, in Docker, to see where it starts failing (Method B).
51
+ 5. **Write one report.** Everything goes into one file, `bundle.json`, with every name and email removed.
52
+
53
+ ## Commands
54
+
55
+ ```
56
+ bug-age catalog --repo DIR --path CRATE [--head REV] [--out FILE]
57
+ bug-age szz --repo DIR --catalog FILE [--window-start YYYY-MM-DD] [--release-tags GLOB] [--out FILE]
58
+ bug-age sweep --repo DIR --path CRATE --fix SHA --overlay DIR --test CMD
59
+ [--build CMD] [--start SHA] [--runner docker|local] [--repeats N] [--image IMG]
60
+ [--time-travel-script FILE|none] [--scratch DIR] [--logs DIR] [--out FILE]
61
+ [--namespace NAME] [--bucket N (toolchain minor rounding, default 4; 0 = exact)]
62
+ [--step-timeout SECONDS (per fetch, build or test step; default 3600)]
63
+ [--search bisection|exhaustive (exhaustive tests every commit; only it can report located)]
64
+ bug-age probe --repo DIR --path CRATE --commits SHA,SHA,... --overlay DIR --test CMD [same options]
65
+ bug-age bundle --repo DIR --results DIR --repo-url URL --out DIR [--spike DIR] [--out-of-scope 'STAGE|EVIDENCE|DOES_NOT_PROVE']
66
+ bug-age explorer [--page FILE] --targets NAME=DIR,NAME=DIR --out DIR (DIR = a bundle output dir)
67
+ bug-age mcp --bundles NAME=FILE,NAME=FILE (read-only MCP server on stdio over bundle.json files)
68
+ bug-age pipeline TARGET.toml [--fresh] [--skip-feasibility] (every stage for one target)
69
+ bug-age dockerfile (print the Method B image's Dockerfile: bug-age dockerfile | docker build -t bug-age-spike:4 -)
70
+ ```
71
+
72
+ Every command accepts only its own options; see [Commands](https://github.com/jacob-adm/bug-age/blob/main/docs/commands.md) for what each one does.
73
+
74
+ ## Quick start
75
+
76
+ ```sh
77
+ pip install bug-age
78
+ mkdir -p targets && curl -so targets/myrepo.toml https://raw.githubusercontent.com/jacob-adm/bug-age/main/targets/rust-sdk.toml
79
+ # edit targets/myrepo.toml: name, repo_url, head, crate_path (see Getting started)
80
+ bug-age pipeline targets/myrepo.toml --skip-feasibility # Method A only, no Docker
81
+ ```
82
+
83
+ The report is `results/myrepo/PIPELINE.md`, and every number is in `dist/myrepo/bundle.json`.
84
+ [Getting started](https://github.com/jacob-adm/bug-age/blob/main/docs/getting-started.md) walks through each step, Method B included.
85
+
86
+ ## Documentation
87
+
88
+ - [Getting started](https://github.com/jacob-adm/bug-age/blob/main/docs/getting-started.md): install, describe your repository in a config file, run every stage, read the report and browse it.
89
+ - [Commands](https://github.com/jacob-adm/bug-age/blob/main/docs/commands.md): what each command does, the pipeline and its config file, and unattended sweeps.
90
+ - [Example runs](https://github.com/jacob-adm/bug-age/blob/main/docs/example-runs.md): the tokenizers and rust-sdk runs, what the explorer shows, and how to read Method B verdicts.
91
+ - [Method](https://github.com/jacob-adm/bug-age/blob/main/docs/method.md): how bugs are found, what is deterministic and what uses AI, and the rigor rules.
92
+ - [Timings](https://github.com/jacob-adm/bug-age/blob/main/docs/timings.md): how long each stage takes on the example runs.
93
+ - [Security](https://github.com/jacob-adm/bug-age/blob/main/SECURITY.md): what the local and Docker runners isolate and what they do not.
94
+ - [Versions](https://github.com/jacob-adm/bug-age/blob/main/docs/versions.md): 1.0.2, the last Rust version; 2.x, the Python package.
95
+ - [Contributing](https://github.com/jacob-adm/bug-age/blob/main/CONTRIBUTING.md): tests and how changes reach `main`.
96
+
97
+ ## License
98
+
99
+ Licensed under either of [Apache License, Version 2.0](https://github.com/jacob-adm/bug-age/blob/main/LICENSE-APACHE) or [MIT License](https://github.com/jacob-adm/bug-age/blob/main/LICENSE-MIT), at your option, as declared in `pyproject.toml`.
@@ -0,0 +1,82 @@
1
+ # bug-age
2
+
3
+ Measures how long fixed bugs lived in a git repository, using only its history. A bug counts only when the commit that fixed it says so in its message (*fix*, *bug*, *hotfix*); a bug fixed under any other message, or never fixed, is not counted. For each counted bug it reports commits elapsed, calendar days, releases shipped, and churn between the commit that introduced it and the fix.
4
+
5
+ It uses two independent methods and compares them:
6
+
7
+ - **Method A, blame-based (SZZ-style).** Runs `git blame` on the lines a fix changed and names the commit that last touched them as the likely introducer. This is fast and needs only git, but it can be wrong. Known failure cases: ghost commits, formatting-only changes, and introducers that were not the latest toucher.
8
+ - **Method B, behavioral sweep.** Takes a regression test that fails before the fix and passes after it, then replays that test across history in a hermetic per-commit Docker environment. The result is the first failing commit, the last passing commit, and every untestable commit with a reason.
9
+
10
+ Every number comes from scripts. AI helped write the code, the Method B regression tests and the article prose, but no model produces or changes a number. See [What is deterministic and what uses AI](https://github.com/jacob-adm/bug-age/blob/main/docs/method.md#what-is-deterministic-and-what-uses-ai). bug-age supports Rust crates today.
11
+
12
+ What you get, and the three names the documentation uses for it:
13
+
14
+ - **Report.** What a run produces: the result files in `results/<name>/` and one bundle, `dist/<name>/bundle.json`, which holds every number. Each repository you run gets its own report.
15
+ - **Explorer.** A viewer. It is a static HTML page you build from one or more bundles to browse their reports. It holds no results of its own and runs no analysis.
16
+ - **Live example.** One explorer, built from the reports of the two [example runs](https://github.com/jacob-adm/bug-age/blob/main/docs/example-runs.md) and published online. It is a snapshot: running bug-age on other repositories does not change it.
17
+
18
+ To see the output first, [open the live example](https://claude.ai/artifact/UDw6jyeA4zMDGhnzL7Typb).
19
+
20
+ ## Requirements
21
+
22
+ - Python 3.11 or later, standard library only.
23
+ - git.
24
+ - Docker, only for the feasibility check and Method B.
25
+ - Linux or macOS, both tested in CI.
26
+ - It measures Rust crates today; other languages are planned.
27
+
28
+ ## How it works
29
+
30
+ 1. **Find the fixes.** bug-age reads the commit history and lists every commit whose message says it fixes a bug (*fix*, *bug*, *hotfix*). A fix whose message doesn't say so is not counted.
31
+ 2. **Find where each bug came from.** For each fix, git shows which earlier commit last wrote the lines the fix changed. That commit is the likely cause (Method A).
32
+ 3. **Count how long it lived.** From that commit to the fix, bug-age counts the days, the commits and the releases that shipped with the bug.
33
+ 4. **Check with a test, if you want.** Write a test that fails before the fix and passes after it. bug-age runs it at older commits, in Docker, to see where it starts failing (Method B).
34
+ 5. **Write one report.** Everything goes into one file, `bundle.json`, with every name and email removed.
35
+
36
+ ## Commands
37
+
38
+ ```
39
+ bug-age catalog --repo DIR --path CRATE [--head REV] [--out FILE]
40
+ bug-age szz --repo DIR --catalog FILE [--window-start YYYY-MM-DD] [--release-tags GLOB] [--out FILE]
41
+ bug-age sweep --repo DIR --path CRATE --fix SHA --overlay DIR --test CMD
42
+ [--build CMD] [--start SHA] [--runner docker|local] [--repeats N] [--image IMG]
43
+ [--time-travel-script FILE|none] [--scratch DIR] [--logs DIR] [--out FILE]
44
+ [--namespace NAME] [--bucket N (toolchain minor rounding, default 4; 0 = exact)]
45
+ [--step-timeout SECONDS (per fetch, build or test step; default 3600)]
46
+ [--search bisection|exhaustive (exhaustive tests every commit; only it can report located)]
47
+ bug-age probe --repo DIR --path CRATE --commits SHA,SHA,... --overlay DIR --test CMD [same options]
48
+ bug-age bundle --repo DIR --results DIR --repo-url URL --out DIR [--spike DIR] [--out-of-scope 'STAGE|EVIDENCE|DOES_NOT_PROVE']
49
+ bug-age explorer [--page FILE] --targets NAME=DIR,NAME=DIR --out DIR (DIR = a bundle output dir)
50
+ bug-age mcp --bundles NAME=FILE,NAME=FILE (read-only MCP server on stdio over bundle.json files)
51
+ bug-age pipeline TARGET.toml [--fresh] [--skip-feasibility] (every stage for one target)
52
+ bug-age dockerfile (print the Method B image's Dockerfile: bug-age dockerfile | docker build -t bug-age-spike:4 -)
53
+ ```
54
+
55
+ Every command accepts only its own options; see [Commands](https://github.com/jacob-adm/bug-age/blob/main/docs/commands.md) for what each one does.
56
+
57
+ ## Quick start
58
+
59
+ ```sh
60
+ pip install bug-age
61
+ mkdir -p targets && curl -so targets/myrepo.toml https://raw.githubusercontent.com/jacob-adm/bug-age/main/targets/rust-sdk.toml
62
+ # edit targets/myrepo.toml: name, repo_url, head, crate_path (see Getting started)
63
+ bug-age pipeline targets/myrepo.toml --skip-feasibility # Method A only, no Docker
64
+ ```
65
+
66
+ The report is `results/myrepo/PIPELINE.md`, and every number is in `dist/myrepo/bundle.json`.
67
+ [Getting started](https://github.com/jacob-adm/bug-age/blob/main/docs/getting-started.md) walks through each step, Method B included.
68
+
69
+ ## Documentation
70
+
71
+ - [Getting started](https://github.com/jacob-adm/bug-age/blob/main/docs/getting-started.md): install, describe your repository in a config file, run every stage, read the report and browse it.
72
+ - [Commands](https://github.com/jacob-adm/bug-age/blob/main/docs/commands.md): what each command does, the pipeline and its config file, and unattended sweeps.
73
+ - [Example runs](https://github.com/jacob-adm/bug-age/blob/main/docs/example-runs.md): the tokenizers and rust-sdk runs, what the explorer shows, and how to read Method B verdicts.
74
+ - [Method](https://github.com/jacob-adm/bug-age/blob/main/docs/method.md): how bugs are found, what is deterministic and what uses AI, and the rigor rules.
75
+ - [Timings](https://github.com/jacob-adm/bug-age/blob/main/docs/timings.md): how long each stage takes on the example runs.
76
+ - [Security](https://github.com/jacob-adm/bug-age/blob/main/SECURITY.md): what the local and Docker runners isolate and what they do not.
77
+ - [Versions](https://github.com/jacob-adm/bug-age/blob/main/docs/versions.md): 1.0.2, the last Rust version; 2.x, the Python package.
78
+ - [Contributing](https://github.com/jacob-adm/bug-age/blob/main/CONTRIBUTING.md): tests and how changes reach `main`.
79
+
80
+ ## License
81
+
82
+ Licensed under either of [Apache License, Version 2.0](https://github.com/jacob-adm/bug-age/blob/main/LICENSE-APACHE) or [MIT License](https://github.com/jacob-adm/bug-age/blob/main/LICENSE-MIT), at your option, as declared in `pyproject.toml`.
@@ -10,4 +10,4 @@ bug-age does not discover new bugs. It starts from bugs the project already fixe
10
10
  commit where the bug's behaviour appears.
11
11
  4. `bundle` assembles everything into one blameless, schema-checked JSON file.
12
12
  """
13
- __version__ = "2.0.0"
13
+ __version__ = "2.1.0"
@@ -17,7 +17,7 @@ from ._compat import as_f64, dumps, get, lines, loads, round1, total_order, trim
17
17
  from .catalog import sanitize_subject
18
18
  from .git import commit_time, git, is_ancestor
19
19
 
20
- SCHEMA_VERSION = "1.1.0"
20
+ SCHEMA_VERSION = "1.2.0"
21
21
  REDACTED = "[redacted]"
22
22
  _PLAIN = re.compile(r"[A-Za-z0-9_./:=,@+\-~]+")
23
23
 
@@ -48,15 +48,17 @@ def public_command(args, cwd, home):
48
48
  return " ".join(out)
49
49
 
50
50
 
51
- def people(repo):
52
- """Every author/committer name and email in the history, lowercased, longest first."""
51
+ def people_and_user_names(repo):
52
+ """Every author/committer name and email in the history, lowercased, longest first; and the
53
+ subset that are only the user part of an email address (`hello` from hello@example.org)."""
53
54
  log = git(repo, ["log", "--all", "--format=%an%n%ae%n%cn%n%ce"])
54
- found = set()
55
+ found, full = set(), set()
55
56
  for line in (trim(l) for l in lines(log)):
56
57
  # Lengths are UTF-8 bytes, as Rust measures them.
57
58
  if len(line.encode()) < 3:
58
59
  continue
59
60
  found.add(line.lower())
61
+ full.add(line.lower())
60
62
  local, at, _ = line.partition("@")
61
63
  if at:
62
64
  user = local.rsplit("+", 1)[-1]
@@ -66,37 +68,65 @@ def people(repo):
66
68
  found.discard(generic)
67
69
  # Byte order first (as a BTreeSet), then longest first, so full names win over their parts.
68
70
  ordered = sorted(found, key=lambda s: s.encode())
69
- return sorted(ordered, key=lambda s: -len(s.encode()))
71
+ return sorted(ordered, key=lambda s: -len(s.encode())), found - full
72
+
73
+
74
+ def people(repo):
75
+ """Every author/committer name, email and email user name in the history, longest first."""
76
+ return people_and_user_names(repo)[0]
70
77
 
71
78
 
72
79
  class Identities:
73
80
  """Name, email and @handle patterns for redaction and for the blameless gate."""
74
81
 
75
- def __init__(self, names):
76
- # Rust's `$` matches only at the very end; Python's also before a final newline, hence \Z.
82
+ def __init__(self, names, user_names=()):
83
+ user_names = set(user_names)
84
+ # Redaction keeps 1.x's pattern, which consumes the character on each side of a name, so
85
+ # adjacent names take more than one pass (see redact). Rust's `$` matches only at the very
86
+ # end; Python's also before a final newline, hence \Z.
77
87
  alternation = [re.escape(p) for p in names]
78
88
  self.names = re.compile(r"(?i)(^|[^\w])(" + "|".join(alternation) + r")(\Z|[^\w])") if alternation else None
89
+
90
+ # Gate patterns only search, so zero-width boundaries suffice.
91
+ def pattern(words):
92
+ words = [re.escape(w) for w in words]
93
+ return re.compile(r"(?i)(?<!\w)(" + "|".join(words) + r")(?!\w)") if words else None
94
+ # Gate: full names fail it; email user names (often ordinary words) are reported for review.
95
+ self.strong = pattern([n for n in names if n not in user_names])
96
+ self.weak = pattern([n for n in names if n in user_names])
79
97
  self.email = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
80
98
  self.handle = re.compile(r"(^|\s)@[A-Za-z0-9][A-Za-z0-9_-]+")
81
99
 
82
100
  def redact(self, text):
83
- """Replace every known name in `text`, repeating until none is left (matches can overlap)."""
101
+ """Replace every known name in `text`, exactly as 1.x did, but always terminating.
102
+
103
+ Passes repeat until no name matches, as in 1.x. During the passes a match is replaced by NUL,
104
+ which no git identity can contain, so a replacement can never match again and each pass
105
+ removes name text: the loop ends. 1.x wrote "[redacted]" at once and never ended when a
106
+ contributor's name occurred in it. Where 1.x ended, the result is the same.
107
+ """
84
108
  if self.names is None:
85
109
  return text
86
110
  while self.names.search(text):
87
- text = self.names.sub(lambda m: m.group(1) + REDACTED + m.group(3), text)
88
- return text
111
+ text = self.names.sub(lambda m: m.group(1) + "\0" + m.group(3), text)
112
+ return text.replace("\0", REDACTED)
89
113
 
90
114
  def hit(self, s):
91
- """A description of the first identity found in `s`, or None."""
115
+ """A description of the first identity that fails the gate in `s`, or None."""
92
116
  if self.email.search(s) or self.handle.search(s):
93
117
  return f"email/handle in {s!r}"
94
- m = self.names.search(s) if self.names else None
95
- return f"person {m.group(2)!r} in {s!r}" if m else None
118
+ # The placeholder is not a name, even when a contributor is called "redacted".
119
+ m = self.strong.search(s.replace(REDACTED, " ")) if self.strong else None
120
+ return f"person {m.group(1)!r} in {s!r}" if m else None
121
+
122
+ def user_name(self, s):
123
+ """The first email user name found in `s` (a warning, not a gate failure), or None."""
124
+ m = self.weak.search(s.replace(REDACTED, " ")) if self.weak else None
125
+ return m.group(1).lower() if m else None
96
126
 
97
127
 
98
- def scan(value, ids):
99
- """Every identity hit in every string of `value`."""
128
+ def scan(value, ids, warnings=None):
129
+ """Every identity hit in every string of `value`; email user names found go to `warnings`."""
100
130
  hits, stack = [], [value]
101
131
  while stack:
102
132
  x = stack.pop()
@@ -104,6 +134,9 @@ def scan(value, ids):
104
134
  h = ids.hit(x)
105
135
  if h:
106
136
  hits.append(h)
137
+ u = ids.user_name(x) if warnings is not None else None
138
+ if u and u not in warnings:
139
+ warnings.append(u)
107
140
  elif isinstance(x, list):
108
141
  stack.extend(x)
109
142
  elif isinstance(x, dict):
@@ -206,6 +239,10 @@ def method_b(repo, d, szz):
206
239
  nominee = get(a_bug, "nominees", 0, "sha") if a_bug is not None else None
207
240
  nominee = nominee if isinstance(nominee, str) else None
208
241
  verdict = get(s, "verdict") if isinstance(get(s, "verdict"), str) else ""
242
+ # Sweeps recorded before the search was recorded were bisections: their "located" is a boundary.
243
+ search = get(s, "search") if get(s, "search") in ("bisection", "exhaustive") else "bisection"
244
+ if verdict == "located" and search != "exhaustive":
245
+ verdict = "boundary"
209
246
  first = get(s, "first_failing") if isinstance(get(s, "first_failing"), str) else None
210
247
  b_days = _days_between(repo, first, fix) if first is not None else None
211
248
  if (entry / "acheck.json").is_file():
@@ -232,7 +269,10 @@ def method_b(repo, d, szz):
232
269
  "id": name,
233
270
  "fix": fix,
234
271
  "verdict": verdict,
235
- "reason": get(s, "reason"),
272
+ "search": search,
273
+ "reason": get(s, "reason") if verdict == get(s, "verdict") else
274
+ "adjacent last PASS and first FAIL among the commits tested; bisection does not rule out an earlier "
275
+ "failure, so the age is a lower bound",
236
276
  "first_failing": first,
237
277
  "last_passing": get(s, "last_passing"),
238
278
  "days": b_days,
@@ -323,11 +363,13 @@ def build(repo, results, spike, repo_url, out_of_scope):
323
363
  tt = feasibility(spike / "results-timetravel" / "report.json")
324
364
  a_summary = method_a_summary(szz)
325
365
  b = method_b(repo, results / "repros", szz)
326
- ids = Identities(people(repo))
366
+ names, user_names = people_and_user_names(repo)
367
+ ids = Identities(names, user_names)
327
368
  shas = set()
328
369
 
329
370
  def add(v):
330
- if isinstance(v, str) and len(v.encode()) == 40:
371
+ # Full commit ids only: 40 hex digits (SHA-1) or 64 (SHA-256).
372
+ if isinstance(v, str) and len(v.encode()) in (40, 64):
331
373
  shas.add(v)
332
374
  for bug in _items(get(szz, "bugs")):
333
375
  add(get(bug, "fix"))
@@ -375,7 +417,9 @@ def build(repo, results, spike, repo_url, out_of_scope):
375
417
  "coverage": coverage(a_summary, b, feas, tt, out_of_scope),
376
418
  "commits": commits,
377
419
  }
378
- hits = scan(bundle, ids)
420
+ found = []
421
+ hits = scan(bundle, ids, found)
379
422
  if hits:
380
423
  raise BundleError(f"blameless gate failed ({len(hits)} hits), first: {hits[0]}")
381
- return bundle
424
+ # Email user names left in the bundle (e.g. an ordinary word in a repro test) are listed for review.
425
+ return bundle, [f"email user name {u!r} appears in the bundle; review it" for u in sorted(found)]
@@ -11,7 +11,7 @@ import subprocess
11
11
  import sys
12
12
  from pathlib import Path
13
13
 
14
- from . import __version__, bundle, catalog, explorer, mcp, szz
14
+ from . import __version__, bundle, catalog, explorer, mcp, schema, szz
15
15
  from ._compat import dumps, get, lines, loads
16
16
 
17
17
  USAGE = """usage: bug-age [--version | --help]
@@ -21,6 +21,8 @@ USAGE = """usage: bug-age [--version | --help]
21
21
  [--build CMD] [--start SHA] [--runner docker|local] [--repeats N] [--image IMG]
22
22
  [--time-travel-script FILE|none] [--scratch DIR] [--logs DIR] [--out FILE]
23
23
  [--namespace NAME] [--bucket N (toolchain minor rounding, default 4; 0 = exact)]
24
+ [--step-timeout SECONDS (per fetch, build or test step; default 3600)]
25
+ [--search bisection|exhaustive (exhaustive tests every commit; only it can report located)]
24
26
  bug-age probe --repo DIR --path CRATE --commits SHA,SHA,... --overlay DIR --test CMD [same options]
25
27
  bug-age bundle --repo DIR --results DIR --repo-url URL --out DIR [--spike DIR] [--out-of-scope 'STAGE|EVIDENCE|DOES_NOT_PROVE']
26
28
  bug-age explorer [--page FILE] --targets NAME=DIR,NAME=DIR --out DIR (DIR = a bundle output dir)
@@ -36,16 +38,40 @@ class Failure(Exception):
36
38
  """A runtime error: printed as `bug-age: <message>`, exit status 1."""
37
39
 
38
40
 
39
- def flags(args):
40
- """`--key value` pairs as a dict; anything else is an error."""
41
+ class UsageError(Exception):
42
+ """A malformed command line: printed with the usage text, exit status 2."""
43
+
44
+
45
+ # The options each subcommand accepts. Anything else is a usage error, so a typo such as --hed can
46
+ # never fall back to a default and silently change what is measured.
47
+ _SWEEP = {"repo", "path", "overlay", "test", "build", "runner", "repeats", "image", "time-travel-script",
48
+ "scratch", "logs", "out", "namespace", "bucket", "step-timeout"}
49
+ OPTIONS = {
50
+ "catalog": {"repo", "path", "head", "out"},
51
+ "szz": {"repo", "catalog", "window-start", "release-tags", "out"},
52
+ "sweep": _SWEEP | {"fix", "start", "search"},
53
+ "probe": _SWEEP | {"commits"},
54
+ "bundle": {"repo", "results", "repo-url", "out", "spike", "out-of-scope"},
55
+ "explorer": {"page", "targets", "out"},
56
+ "mcp": {"bundles"},
57
+ }
58
+
59
+
60
+ def flags(args, allowed=None):
61
+ """`--key value` pairs as a dict; unknown, repeated or valueless options are usage errors."""
41
62
  out, it = {}, iter(args)
42
63
  for k in it:
43
64
  if not k.startswith("--"):
44
- raise Failure(f"unexpected argument '{k}'")
65
+ raise UsageError(f"unexpected argument '{k}'")
66
+ key = k[2:]
67
+ if allowed is not None and key not in allowed:
68
+ raise UsageError(f"unknown option '{k}'")
69
+ if key in out:
70
+ raise UsageError(f"option '{k}' given twice")
45
71
  try:
46
- out[k[2:]] = next(it)
72
+ out[key] = next(it)
47
73
  except StopIteration:
48
- raise Failure(f"missing value for '{k}'") from None
74
+ raise UsageError(f"missing value for '{k}'") from None
49
75
  return out
50
76
 
51
77
 
@@ -151,9 +177,13 @@ def cmd_bundle(f):
151
177
  raise Failure("--out-of-scope must be 'STAGE|EVIDENCE|DOES_NOT_PROVE'")
152
178
  oos = tuple(parts)
153
179
  try:
154
- built = bundle.build(repo, Path(need(f, "results")), spike, need(f, "repo-url"), oos)
180
+ built, warnings = bundle.build(repo, Path(need(f, "results")), spike, need(f, "repo-url"), oos)
155
181
  except bundle.BundleError as exc:
156
182
  raise Failure(str(exc)) from exc
183
+ # Nothing is written unless the bundle satisfies the schema shipped with this package.
184
+ problems = schema.errors(built, loads((Path(__file__).parent / "data" / "bundle.schema.json").read_text(encoding="utf-8")))
185
+ if problems:
186
+ raise Failure(f"bundle fails its schema ({len(problems)} errors), first: {'; '.join(problems[:3])}")
157
187
  text = dumps(built)
158
188
  js = f"window.BUG_AGE_BUNDLE = {text};\n"
159
189
  if len(js.encode()) > MAX_BYTES:
@@ -165,11 +195,12 @@ def cmd_bundle(f):
165
195
  "command": command_line(),
166
196
  "schema_version": bundle.SCHEMA_VERSION,
167
197
  "blameless_gate": "PASS",
198
+ "schema_check": "PASS",
168
199
  "size": {"bundle_json_bytes": len(text.encode()), "bundle_js_bytes": len(js.encode()),
169
200
  "warn_over_8mb": len(js.encode()) > WARN_BYTES},
170
201
  "outputs": {"bundle.json": sha256(text), "bundle.js": sha256(js)},
171
202
  "versions": {"bug-age": __version__, "git": tool_version("git", ["--version"])},
172
- "warnings": [],
203
+ "warnings": warnings,
173
204
  }
174
205
  print(f"bundle: {len(text.encode())} bytes, sha256 {sha256(text)}, blameless gate PASS", file=sys.stderr)
175
206
  emit(receipt, out / "receipt.json")
@@ -258,7 +289,10 @@ def main(argv=None):
258
289
  print(f"bug-age: unknown argument '{first}'\n{USAGE}", file=sys.stderr)
259
290
  return 2
260
291
  try:
261
- COMMANDS[first](flags(args[1:]))
292
+ COMMANDS[first](flags(args[1:], OPTIONS.get(first)))
293
+ except UsageError as exc:
294
+ print(f"bug-age: {exc}\n{USAGE}", file=sys.stderr)
295
+ return 2
262
296
  except (Failure, RuntimeError) as exc:
263
297
  print(f"bug-age: {exc}", file=sys.stderr)
264
298
  return 1
@@ -7,7 +7,7 @@
7
7
  "required": ["schema_version", "generator", "subject", "summary", "catalog", "method_a", "method_b", "feasibility", "coverage", "commits"],
8
8
  "additionalProperties": false,
9
9
  "$defs": {
10
- "sha": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
10
+ "sha": {"type": "string", "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$"},
11
11
  "sha_or_null": {"anyOf": [{"$ref": "#/$defs/sha"}, {"type": "null"}]},
12
12
  "stat": {
13
13
  "description": "Distribution over bugs: median, 90th percentile, maximum, sample size.",
@@ -29,7 +29,7 @@
29
29
  }
30
30
  },
31
31
  "properties": {
32
- "schema_version": {"const": "1.1.0"},
32
+ "schema_version": {"const": "1.2.0"},
33
33
  "generator": {"type": "string", "description": "bug-age version that built the bundle"},
34
34
  "subject": {"type": "object", "required": ["repo_url", "crate_path", "head"],
35
35
  "properties": {"repo_url": {"type": "string"}, "crate_path": {"type": "string"}, "head": {"$ref": "#/$defs/sha"}}},
@@ -63,7 +63,8 @@
63
63
  "required": ["id", "fix", "verdict", "first_failing", "last_passing", "days", "days_is_lower_bound", "method_a_nominee", "a_check", "results", "repro_test"],
64
64
  "properties": {
65
65
  "fix": {"$ref": "#/$defs/sha"},
66
- "verdict": {"enum": ["located", "interval", "censored-by-testability", "left-censored", "repro-invalid"]},
66
+ "verdict": {"enum": ["located", "boundary", "interval", "censored-by-testability", "left-censored", "repro-invalid"]},
67
+ "search": {"enum": ["bisection", "exhaustive"], "description": "located only with exhaustive; a bisected boundary is a lower bound"},
67
68
  "first_failing": {"$ref": "#/$defs/sha_or_null"},
68
69
  "last_passing": {"$ref": "#/$defs/sha_or_null"},
69
70
  "days_is_lower_bound": {"type": "boolean"},
@@ -81,7 +82,7 @@
81
82
  "commits": {
82
83
  "description": "Every SHA referenced anywhere in the bundle: committer date and a short, redacted subject. No author or committer identity.",
83
84
  "type": "object",
84
- "propertyNames": {"pattern": "^[0-9a-f]{40}$"},
85
+ "propertyNames": {"pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$"},
85
86
  "additionalProperties": {"type": "object", "required": ["date", "subject"], "additionalProperties": false,
86
87
  "properties": {"date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}, "subject": {"type": "string", "maxLength": 100}}}
87
88
  }
@@ -440,7 +440,7 @@ function renderOverview() {
440
440
  ["Median releases shipped", a.releases_shipped_bug ? fmt(a.releases_shipped_bug.median) : "—", st(a.releases_shipped_bug), "method_a.releases_shipped_bug"],
441
441
  ["Fixes traced", `${a.with_introducer} / ${a.fixes}`, "with a nominated introducer", "method_a.with_introducer"],
442
442
  ["Old commits that build", f.baseline_share == null ? "NOT TESTED" : Math.round(f.baseline_share * 100) + "%", f.time_travel_share == null ? "time-travel: not run" : `with dated deps: ${Math.round(f.time_travel_share * 100)}%`, "feasibility.baseline_share"],
443
- ["Behavioural sweeps", b.swept ? `${b.located} / ${b.swept}` : "NOT TESTED", b.swept ? "located exactly" : "no regression tests yet", "method_b.swept"],
443
+ ["Behavioural sweeps", b.swept ? `${b.located} / ${b.swept}` : "NOT TESTED", b.swept ? "located exactly (all commits tested)" : "no regression tests yet", "method_b.swept"],
444
444
  ];
445
445
  $("tiles").replaceChildren(...tiles.map(([k, v, sub, path]) => el("button", { class: "tile", type: "button", onclick: () => openDrawer(k, evidenceForCheck(path)) },
446
446
  el("span", { class: "k" }, k), el("span", { class: "v" }, v), el("span", { class: "s" }, sub))));
@@ -570,7 +570,8 @@ function renderHeatmap() {
570
570
  const LOCKS = {
571
571
  rule: "tests/test_method_a.py · test_classify_rules, test_catalog_admits_fix_and_records_exclusion_rule",
572
572
  nominate: "tests/test_method_a.py · test_szz_nominates_planting_commit_with_scripted_lifetime",
573
- located: "tests/test_sweep.py · test_locates_exact_introducing_commit",
573
+ located: "tests/test_sweep_scenarios.py · test_exhaustive_scenarios",
574
+ boundary: "tests/test_sweep.py · test_bisection_reports_a_boundary",
574
575
  "censored-by-testability": "tests/test_sweep.py · test_censored_by_testability_when_bug_predates_compilable_test",
575
576
  "left-censored": "tests/test_sweep.py · test_left_censored_when_range_starts_inside_the_bug",
576
577
  "repro-invalid": "tests/test_sweep.py · test_rejects_a_repro_that_does_not_fail_before_the_fix",
@@ -582,7 +583,8 @@ const FLAG_TEXT = {
582
583
  "committer-dates-compressed": "A rebase squeezed committer dates together, so author dates are used for the age.",
583
584
  };
584
585
  const VERDICT_TEXT = {
585
- located: "The sweep found the exact commit where the regression test starts failing.",
586
+ located: "Every commit in the range was tested: this is the exact commit where the regression test starts failing.",
587
+ boundary: "Bisection found where the test goes from passing to failing among the commits it tested; an earlier failure is not ruled out, so the age is a lower bound.",
586
588
  interval: "The bug started somewhere in a range of commits that could not be narrowed further.",
587
589
  "censored-by-testability": "The test already fails at the oldest commit where it compiles; the true age is at least this long.",
588
590
  "left-censored": "The test fails at the start of the swept range; the bug is older than the range.",
@@ -653,7 +655,7 @@ function search(q) {
653
655
  if (q === ":longest") return rows.filter(r => aDays(r) != null).sort((a, b) => aDays(b) - aDays(a)).slice(0, 15);
654
656
  if (q === ":releases") return rows.sort((a, b) => rel(b) - rel(a)).slice(0, 15);
655
657
  if (q === ":recent") return [...B.method_a].sort((a, b) => b.fix_date.localeCompare(a.fix_date)).slice(0, 15);
656
- const terms = words(q), hex = (q.match(/\b[0-9a-f]{4,40}\b/g) || []);
658
+ const terms = words(q), hex = (q.match(/\b[0-9a-f]{4,64}\b/g) || []);
657
659
  return B.method_a.map(r => {
658
660
  const s = subj(r.fix).toLowerCase(); let score = 0;
659
661
  for (const t of terms) if (s.includes(t)) score += 2;
@@ -688,7 +690,7 @@ function sliceFor(rows) {
688
690
  releases_shipped: r.lifetime && r.lifetime.releases_spanned ? r.lifetime.releases_spanned.length : null, nominees: r.nominees.map(n => n.sha), flags: r.flags })),
689
691
  };
690
692
  }
691
- const HEX = /\b[0-9a-f]{7,40}\b/g;
693
+ const HEX = /\b[0-9a-f]{7,64}\b/g;
692
694
  /** Every number in a string, normalized (e.g. "07" -> "7"). */
693
695
  function numbersIn(s) { return (s.match(/\d+(?:\.\d+)?/g) || []).map(x => String(Number(x))); }
694
696
  // Mechanical checks; returns a list of problems (empty = accepted).
@@ -699,7 +701,7 @@ function verifyAnswer(ans, slice, question) {
699
701
  const shas = slice.rows.flatMap(r => [r.fix, ...r.nominees]).concat(slice.head);
700
702
  const known = h => shas.some(s => s.startsWith(h));
701
703
  if (!ans.citations.length) problems.push("The answer cites no SHA.");
702
- for (const c of ans.citations) if (typeof c !== "string" || !/^[0-9a-f]{7,40}$/.test(c) || !known(c)) problems.push(`Cited SHA ${String(c).slice(0, 40)} is not in the rows that were sent.`);
704
+ for (const c of ans.citations) if (typeof c !== "string" || !/^[0-9a-f]{7,64}$/.test(c) || !known(c)) problems.push(`Cited SHA ${String(c).slice(0, 40)} is not in the rows that were sent.`);
703
705
  for (const h of ans.answer.match(HEX) || []) if (/[a-f]/.test(h) && !known(h)) problems.push(`The answer mentions ${h}, which is not in the rows that were sent.`);
704
706
  const allowed = new Set([...numbersIn(JSON.stringify(slice)), ...numbersIn(question || "")]);
705
707
  for (const n of numbersIn(ans.answer.replace(HEX, m => /[a-f]/.test(m) ? " " : m))) if (!allowed.has(n)) problems.push(`The number ${n} does not appear in the rows that were sent.`);
@@ -52,8 +52,8 @@ def tools():
52
52
  "inputSchema": {"type": "object", "properties": {"target": _target_arg(), "query": {"type": "string"},
53
53
  "limit": {"type": "integer", "minimum": 1, "maximum": 200, "default": 20}}, "required": ["target"]},
54
54
  "annotations": ro},
55
- {"name": "get_fix", "description": "One fix by full SHA or unique prefix (7+ hex chars): its Method A row, its Method B sweep if any (else null), and the subject/date of every SHA referenced.",
56
- "inputSchema": {"type": "object", "properties": {"target": _target_arg(), "sha": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}}, "required": ["target", "sha"]},
55
+ {"name": "get_fix", "description": "One fix by full SHA (40 or 64 hex chars) or unique prefix (7+ hex chars): its Method A row, its Method B sweep if any (else null), and the subject/date of every SHA referenced.",
56
+ "inputSchema": {"type": "object", "properties": {"target": _target_arg(), "sha": {"type": "string", "pattern": "^[0-9a-f]{7,64}$"}}, "required": ["target", "sha"]},
57
57
  "annotations": ro},
58
58
  ]
59
59
 
@@ -120,8 +120,8 @@ def _get_fix(t, args):
120
120
  sha = get(args, "sha")
121
121
  if not isinstance(sha, str):
122
122
  raise ToolError("missing argument: sha")
123
- if not 7 <= len(sha.encode()) <= 40 or not all(c in "0123456789abcdef" for c in sha):
124
- raise ToolError("sha must be 7 to 40 lowercase hex characters")
123
+ if not 7 <= len(sha.encode()) <= 64 or not all(c in "0123456789abcdef" for c in sha):
124
+ raise ToolError("sha must be 7 to 64 lowercase hex characters")
125
125
  rows = get(t.bundle, "method_a")
126
126
  if not isinstance(rows, list):
127
127
  raise ToolError("bundle has no method_a array")