Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

fix(cla): the gate now sees Co-authored-by trailers (issue #269)

xerj-org90f9305be052
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1b34dd732..a0d55144b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,6 +23,9 @@ jobs:
cla-config:
name: CLA gate config
runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: read
steps:
- uses: actions/checkout@v4
@@ -34,6 +37,20 @@ jobs:
jq -e 'type == "array" and all(.[]; type == "string")' .contributors
jq -e 'index("dependabot[bot]") != null' .contributors
+ # cla-bot matches commit AUTHORS only, so a maintainer re-land whose
+ # commits carry the fork contributor's Co-authored-by trailer goes green
+ # without that contributor ever signing (issue #269; live instance
+ # PR #248 re-landing #166). Check the trailers too.
+ - name: Co-author CLA check unit tests
+ run: python3 scripts/test_cla_coauthors.py
+
+ - name: Co-authored-by trailers resolve to signed contributors
+ if: github.event_name == 'pull_request'
+ env:
+ GH_TOKEN: ${{ github.token }}
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ run: python3 scripts/check_cla_coauthors.py --pr "$PR_NUMBER"
+
lint:
name: Format + Clippy
runs-on: ubuntu-latest
diff --git a/scripts/check_cla_coauthors.py b/scripts/check_cla_coauthors.py
new file mode 100755
index 000000000..a76c3bd37
--- /dev/null
+++ b/scripts/check_cla_coauthors.py
@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""CLA check for Co-authored-by trailers (issue #269).
+
+cla-bot resolves signatures by matching commit *authors* against
+.contributors. When a maintainer re-lands a fork PR — squashing the
+contributor's commits onto an xerj-org branch and crediting them with a
+Co-authored-by trailer — every commit author is xerj-org, so the gate goes
+green even though the person whose work it is has never signed (live
+instance: PR #248, the re-land of buger's #166). This check closes that
+hole: every Co-authored-by trailer on a PR must resolve to a login listed
+in .contributors.
+
+An email resolves to a login by, in order:
+
+ 1. GitHub noreply address — ``[id+][email protected]``.
+ 2. This repo's own commit history — ``GET /repos/{repo}/commits?author=<email>``
+ returns the login GitHub itself attributes that email to. The CLA
+ signature flow ("open a PR adding your username to .contributors from
+ your own account") lands a commit authored with the signer's email, so
+ signing makes the signer resolvable as a side effect.
+
+Anything unresolvable FAILS the gate, deliberately: an identity the gate
+cannot attribute is exactly what it exists to flag.
+
+Usage (CI): check_cla_coauthors.py --pr <number>
+ Needs `gh` and GH_TOKEN; repo comes from GITHUB_REPOSITORY or --repo.
+
+Tests: scripts/test_cla_coauthors.py
+"""
+
+import argparse
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+import urllib.parse
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+# git trailer keys are case-insensitive; GitHub emits "Co-authored-by".
+_COAUTHOR_RE = re.compile(
+ r"^\s*co-authored-by:\s*(?P<name>[^<]*?)\s*<(?P<email>[^>]+)>\s*$",
+ re.IGNORECASE | re.MULTILINE,
+)
+
+_NOREPLY_RE = re.compile(
+ r"^(?:\d+\+)?(?P<login>[^@+]+)@users\.noreply\.github\.com$", re.IGNORECASE
+)
+
+
+def parse_coauthors(message):
+ """All Co-authored-by trailers in a commit message as (name, email)."""
+ return [
+ (m.group("name"), m.group("email").strip())
+ for m in _COAUTHOR_RE.finditer(message)
+ ]
+
+
+def noreply_login(email):
+ """Login embedded in a GitHub noreply address, or None."""
+ m = _NOREPLY_RE.match(email.strip())
+ return m.group("login") if m else None
+
+
+def check_commits(commits, contributors, resolve):
+ """Return a list of problem strings; empty means the gate passes.
+
+ commits: [{"sha": ..., "message": ...}]
+ contributors: logins from .contributors
+ resolve: email -> login-or-None (network lookup; injectable for tests)
+ """
+ signed = {c.lower() for c in contributors}
+ resolved = {} # email -> login or None, so each email is looked up once
+ problems = []
+ for commit in commits:
+ sha = commit["sha"][:8]
+ for name, email in parse_coauthors(commit["message"]):
+ if email not in resolved:
+ resolved[email] = noreply_login(email) or resolve(email)
+ login = resolved[email]
+ if login is None:
+ problems.append(
+ f"{sha}: cannot attribute Co-authored-by '{name} <{email}>' "
+ "to any GitHub login (not a noreply address, and no commit "
+ "in this repo is authored with it). Ask them to sign per "
+ "CLA.md — the signature PR itself makes their email "
+ "resolvable — or use their @users.noreply.github.com "
+ "address in the trailer."
+ )
+ elif login.lower() not in signed:
+ problems.append(
+ f"{sha}: Co-authored-by '{name} <{email}>' is GitHub user "
+ f"'{login}', who has not signed the CLA (not in "
+ ".contributors). See CLA.md for the one-time signature "
+ "flow."
+ )
+ return problems
+
+
+def _gh_api(path):
+ out = subprocess.run(
+ ["gh", "api", "--paginate", path],
+ check=True,
+ capture_output=True,
+ text=True,
+ ).stdout
+ # --paginate concatenates JSON arrays; parse them all.
+ items = []
+ dec = json.JSONDecoder()
+ i = 0
+ while i < len(out):
+ chunk, end = dec.raw_decode(out, i)
+ items.extend(chunk if isinstance(chunk, list) else [chunk])
+ i = end
+ while i < len(out) and out[i].isspace():
+ i += 1
+ return items
+
+
+def make_repo_resolver(repo):
+ """email -> login via the repo's own commit history."""
+
+ def resolve(email):
+ q = urllib.parse.quote(email)
+ commits = _gh_api(f"repos/{repo}/commits?author={q}&per_page=1")
+ for c in commits:
+ author = c.get("author") or {}
+ if author.get("login"):
+ return author["login"]
+ return None
+
+ return resolve
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ ap.add_argument("--pr", required=True, type=int, help="pull request number")
+ ap.add_argument(
+ "--repo",
+ default=os.environ.get("GITHUB_REPOSITORY", "xerj-org/xerj"),
+ help="owner/name (default: $GITHUB_REPOSITORY or xerj-org/xerj)",
+ )
+ args = ap.parse_args()
+
+ contributors = json.loads((REPO_ROOT / ".contributors").read_text())
+ raw = _gh_api(f"repos/{args.repo}/pulls/{args.pr}/commits?per_page=100")
+ commits = [{"sha": c["sha"], "message": c["commit"]["message"]} for c in raw]
+
+ problems = check_commits(commits, contributors, make_repo_resolver(args.repo))
+ if problems:
+ print(f"CLA co-author check FAILED for PR #{args.pr}:", file=sys.stderr)
+ for p in problems:
+ print(f" - {p}", file=sys.stderr)
+ return 1
+ trailers = sum(len(parse_coauthors(c["message"])) for c in commits)
+ print(
+ f"CLA co-author check passed for PR #{args.pr}: "
+ f"{len(commits)} commit(s), {trailers} Co-authored-by trailer(s), "
+ "all attributable to signed contributors."
+ )
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/test_cla_coauthors.py b/scripts/test_cla_coauthors.py
new file mode 100755
index 000000000..d4e08b686
--- /dev/null
+++ b/scripts/test_cla_coauthors.py
@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Regression tests for the Co-authored-by CLA check (issue #269).
+
+Before this check existed, cla-bot matched only commit *authors* against
+.contributors, so a maintainer re-land of a fork PR — commits authored
+xerj-org, contributor credited via a Co-authored-by trailer — went green
+without the contributor ever signing (live instance: PR #248 re-landing
+buger's #166). These tests pin the trailer-aware behaviour.
+
+Run: python3 scripts/test_cla_coauthors.py
+"""
+
+import pathlib
+import re
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+
+from check_cla_coauthors import check_commits, noreply_login, parse_coauthors
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+# The shape of PR #248: maintainer-authored re-land, real attribution
+# carried only by the trailer.
+RELAND_COMMITS = [
+ {
+ "sha": "c337eb8f",
+ "message": "perf(autoindex): reuse the phase-A PDF extraction\n\n"
+ "Body text.\n\nCo-authored-by: Leonid Bugaev <[email protected]>",
+ },
+ {
+ "sha": "81c64883",
+ "message": "docs(changelog): record the change\n\n"
+ "Co-authored-by: Leonid Bugaev <[email protected]>",
+ },
+]
+
+
+def no_network(email):
+ raise AssertionError(f"unexpected network resolution for {email!r}")
+
+
+class ParseTests(unittest.TestCase):
+ def test_extracts_name_and_email(self):
+ got = parse_coauthors(RELAND_COMMITS[0]["message"])
+ self.assertEqual(got, [("Leonid Bugaev", "[email protected]")])
+
+ def test_trailer_key_is_case_insensitive(self):
+ # git trailers are case-insensitive; GitHub emits "Co-authored-by".
+ msg = "subject\n\nCO-AUTHORED-BY: A B <[email protected]>\nco-authored-by: C D <[email protected]>"
+ self.assertEqual(
+ parse_coauthors(msg), [("A B", "[email protected]"), ("C D", "[email protected]")]
+ )
+
+ def test_no_trailers(self):
+ self.assertEqual(parse_coauthors("fix: something\n\nplain body"), [])
+
+
+class NoreplyTests(unittest.TestCase):
+ def test_modern_noreply(self):
+ self.assertEqual(
+ noreply_login("[email protected]"), "buger"
+ )
+
+ def test_legacy_noreply(self):
+ self.assertEqual(noreply_login("[email protected]"), "buger")
+
+ def test_bot_noreply(self):
+ self.assertEqual(
+ noreply_login("49699333+dependabot[bot]@users.noreply.github.com"),
+ "dependabot[bot]",
+ )
+
+ def test_ordinary_email_is_not_a_login(self):
+ self.assertIsNone(noreply_login("[email protected]"))
+
+
+class GateTests(unittest.TestCase):
+ def test_unsigned_coauthor_fails_the_gate(self):
+ # THE regression for issue #269: every commit author is signed, the
+ # co-author is not — the old gate said green here.
+ problems = check_commits(
+ RELAND_COMMITS,
+ contributors=["xerj-org", "dependabot[bot]"],
+ resolve=lambda email: "buger",
+ )
+ self.assertTrue(problems, "gate passed a re-land with an unsigned co-author")
+ self.assertTrue(any("buger" in p for p in problems), problems)
+
+ def test_unresolvable_coauthor_fails_the_gate(self):
+ # An identity the gate cannot attribute is exactly what it exists to
+ # flag — unresolvable must fail, not silently pass.
+ problems = check_commits(
+ RELAND_COMMITS,
+ contributors=["xerj-org", "dependabot[bot]"],
+ resolve=lambda email: None,
+ )
+ self.assertTrue(problems, "gate passed an unresolvable co-author")
+
+ def test_signed_coauthor_passes(self):
+ problems = check_commits(
+ RELAND_COMMITS,
+ contributors=["xerj-org", "dependabot[bot]", "buger"],
+ resolve=lambda email: "buger",
+ )
+ self.assertEqual(problems, [])
+
+ def test_login_match_is_case_insensitive(self):
+ # GitHub logins are case-insensitive; a case mismatch between the
+ # resolved login and the .contributors entry must not flag a signer.
+ problems = check_commits(
+ RELAND_COMMITS,
+ contributors=["xerj-org", "Buger"],
+ resolve=lambda email: "buger",
+ )
+ self.assertEqual(problems, [])
+
+ def test_noreply_coauthor_needs_no_network(self):
+ commits = [
+ {
+ "sha": "abc12345",
+ "message": "subject\n\n"
+ "Co-authored-by: B <[email protected]>",
+ }
+ ]
+ problems = check_commits(
+ commits, contributors=["buger"], resolve=no_network
+ )
+ self.assertEqual(problems, [])
+
+ def test_no_trailers_needs_no_network(self):
+ commits = [{"sha": "abc12345", "message": "fix: plain commit"}]
+ self.assertEqual(
+ check_commits(commits, contributors=["xerj-org"], resolve=no_network), []
+ )
+
+ def test_duplicate_emails_resolved_once(self):
+ calls = []
+
+ def counting(email):
+ calls.append(email)
+ return "buger"
+
+ check_commits(RELAND_COMMITS, contributors=["buger"], resolve=counting)
+ self.assertEqual(calls, ["[email protected]"])
+
+
+class WiringTests(unittest.TestCase):
+ """A checker CI never runs is not a gate (cf. the #207 lesson)."""
+
+ def _cla_job(self):
+ ci = (REPO_ROOT / ".github" / "workflows" / "ci.yml").read_text()
+ m = re.search(r"\n cla-config:\n(.*?)(?=\n \S)", ci, re.S)
+ self.assertIsNotNone(m, "cla-config job missing from ci.yml")
+ return m.group(1)
+
+ def test_ci_runs_the_coauthor_check(self):
+ self.assertIn("check_cla_coauthors.py", self._cla_job())
+
+ def test_ci_runs_these_tests(self):
+ self.assertIn("test_cla_coauthors.py", self._cla_job())
+
+
+if __name__ == "__main__":
+ unittest.main()