repocast 0.1.0__py3-none-any.whl

repocast/__init__.py

@@ -0,0 +1,2 @@
+"""repocast: turn a repository's changes into accurate, ready-to-post X posts, and post them safely."""
+__version__ = "0.1.0"

repocast/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+import sys
+sys.exit(main())

repocast/backends.py

@@ -0,0 +1,178 @@
+"""Posting backends.
+
+  x        X API v2: POST /2/tweets (OAuth 1.0a user context), threads chained with reply.in_reply_to_tweet_id.
+           Before the first post of a run it calls GET /2/users/me and refuses to post unless the token belongs to the
+           configured account.
+  outbox   Never posts: appends to an outbox (JSON Lines + a JSON Feed + plain text) for a human or another tool.
+  dry-run  Never posts: prints what would be posted.
+  plugin   "package.module:ClassName" implementing the Backend interface below.
+
+Every backend's post_thread() returns the list of post ids, or raises PostError(definite=..., ids=[...]).
+definite=True means the server clearly refused (nothing was created for the failing post); definite=False means the
+outcome is unknown (timeout, connection reset, 5xx) and the runner will NEVER retry it automatically.
+"""
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+
+from . import __version__, oauth
+from .weight import weighted_len
+
+API_BASE = "https://api.x.com/2"
+CRED_ENV = ("X_API_KEY", "X_API_SECRET", "X_ACCESS_TOKEN", "X_ACCESS_TOKEN_SECRET")
+USER_AGENT = f"repocast/{__version__}"
+
+
+class PostError(Exception):
+    def __init__(self, msg: str, definite: bool, ids: list[str] | None = None):
+        super().__init__(msg)
+        self.definite, self.ids = definite, list(ids or [])
+
+
+class AccountMismatch(Exception):
+    """The credentials do not belong to the configured account (or it could not be verified). Nothing is posted."""
+
+
+class Backend:
+    name = "base"
+    live = False  # True only for backends that publish somewhere public
+
+    def verify(self) -> str:
+        """Check the backend may post; return a description. Raise AccountMismatch to abort the run."""
+        return self.name
+
+    def post_thread(self, posts: list[str], item: dict) -> list[str]:
+        raise NotImplementedError
+
+
+class DryRunBackend(Backend):
+    name = "dry-run"
+
+    def __init__(self, log=print, **_):
+        self.log = log
+
+    def post_thread(self, posts, item):
+        for i, p in enumerate(posts, 1):
+            self.log(f"--- {item['short']} post {i}/{len(posts)} ({weighted_len(p)}/280) ---\n{p}")
+        return [f"dry-run-{item['short']}-{i}" for i in range(1, len(posts) + 1)]
+
+
+class OutboxBackend(Backend):
+    """Writes <dir>/outbox.jsonl (append), <dir>/outbox.json (JSON Feed 1.1 of the last 100) and <dir>/outbox.txt."""
+    name = "outbox"
+
+    def __init__(self, path: str = "outbox", **_):
+        self.dir = path
+
+    def post_thread(self, posts, item):
+        os.makedirs(self.dir, exist_ok=True)
+        now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        rec = {"id": item["id"], "short": item["short"], "date": item["date"], "commit_url": item.get("commit_url"),
+               "queued_at": now, "posts": posts, "weighted_lengths": [weighted_len(p) for p in posts]}
+        with open(os.path.join(self.dir, "outbox.jsonl"), "a", encoding="utf-8") as f:
+            f.write(json.dumps(rec, ensure_ascii=False) + "\n")
+        with open(os.path.join(self.dir, "outbox.jsonl"), encoding="utf-8") as f:
+            recs = [json.loads(ln) for ln in f if ln.strip()][-100:]
+        feed = {"version": "https://jsonfeed.org/version/1.1", "title": "repocast outbox",
+                "items": [{"id": r["id"], "url": r.get("commit_url"), "date_published": r["queued_at"],
+                           "content_text": "\n\n---\n\n".join(r["posts"]), "_repocast": {"posts": r["posts"]}}
+                          for r in reversed(recs)]}
+        tmp = os.path.join(self.dir, "outbox.json.tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(feed, f, indent=1, ensure_ascii=False)
+        os.replace(tmp, os.path.join(self.dir, "outbox.json"))
+        with open(os.path.join(self.dir, "outbox.txt"), "a", encoding="utf-8") as f:
+            f.write(f"=== {item['short']} ({item['date']}) ===\n" + "\n--- reply ---\n".join(posts) + "\n\n")
+        return [f"outbox-{item['short']}-{i}" for i in range(1, len(posts) + 1)]
+
+
+def _http_json(req: urllib.request.Request, timeout: int) -> dict:
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.load(resp)
+
+
+class XApiBackend(Backend):
+    name = "x"
+    live = True
+
+    def __init__(self, creds: dict, account: str | None = None, account_id: str | None = None,
+                 api_base: str = API_BASE, timeout: int = 30, http=_http_json, **_):
+        missing = [k for k in CRED_ENV if not (creds.get(k) or "").strip()]
+        if missing:
+            raise ValueError("missing credentials: " + ", ".join(missing))
+        if not account and not account_id:
+            raise ValueError("the x backend needs account (username) or account_id so it can refuse to post elsewhere")
+        self.creds, self.account, self.account_id = creds, (account or "").lstrip("@"), account_id
+        self.api, self.timeout, self.http = api_base.rstrip("/"), timeout, http
+        self.verified: dict | None = None
+
+    def _auth(self, method: str, url: str) -> str:
+        c = self.creds
+        return oauth.header(method, url, c["X_API_KEY"], c["X_API_SECRET"], c["X_ACCESS_TOKEN"], c["X_ACCESS_TOKEN_SECRET"])
+
+    def verify(self) -> str:
+        url = f"{self.api}/users/me"
+        req = urllib.request.Request(url, method="GET", headers={"Authorization": self._auth("GET", url), "User-Agent": USER_AGENT})
+        try:
+            data = self.http(req, self.timeout)["data"]
+        except Exception as e:  # noqa: BLE001 - any failure means we cannot prove who we are
+            raise AccountMismatch(f"could not verify the account via GET /2/users/me: {type(e).__name__}: {e}")
+        uname, uid = str(data.get("username", "")), str(data.get("id", ""))
+        if self.account and uname.lower() != self.account.lower():
+            raise AccountMismatch(f"credentials belong to @{uname}, but the configured account is @{self.account}")
+        if self.account_id and uid != str(self.account_id):
+            raise AccountMismatch(f"credentials belong to user id {uid}, but the configured account_id is {self.account_id}")
+        self.verified = {"username": uname, "id": uid}
+        return f"@{uname} ({uid})"
+
+    def create_post(self, text: str, reply_to: str | None) -> str:
+        if self.verified is None:
+            raise AccountMismatch("refusing to post: account not verified (call verify() first)")
+        url = f"{self.api}/tweets"
+        body = {"text": text}
+        if reply_to:
+            body["reply"] = {"in_reply_to_tweet_id": reply_to}
+        req = urllib.request.Request(url, data=json.dumps(body).encode(), method="POST", headers={
+            "Authorization": self._auth("POST", url), "Content-Type": "application/json", "User-Agent": USER_AGENT})
+        return str(self.http(req, self.timeout)["data"]["id"])
+
+    def post_thread(self, posts, item):
+        ids: list[str] = []
+        for text in posts:
+            try:
+                ids.append(self.create_post(text, ids[-1] if ids else None))
+            except AccountMismatch:
+                raise
+            except urllib.error.HTTPError as e:
+                detail = ""
+                try:
+                    detail = e.read().decode("utf-8", "replace")[:300]
+                except Exception:  # noqa: BLE001
+                    pass
+                # 4xx: the API refused, nothing was created. 5xx: a gateway error can hide a created post -> unknown.
+                raise PostError(f"HTTP {e.code}: {detail}", definite=e.code < 500, ids=ids)
+            except Exception as e:  # noqa: BLE001 - timeout / reset / bad response: the post may exist
+                raise PostError(f"{type(e).__name__}: {e}", definite=False, ids=ids)
+        return ids
+
+
+def make(kind: str, opts: dict, env: dict, log=print) -> Backend:
+    if kind == "dry-run":
+        return DryRunBackend(log=log)
+    if kind == "outbox":
+        return OutboxBackend(path=opts.get("outbox", "outbox"))
+    if kind == "x":
+        return XApiBackend({k: env.get(k, "") for k in CRED_ENV}, account=opts.get("account"),
+                           account_id=opts.get("account_id"), api_base=opts.get("api_base", API_BASE))
+    if ":" in kind:
+        mod, cls = kind.split(":", 1)
+        obj = getattr(importlib.import_module(mod), cls)(**opts, env=env, log=log)
+        if not isinstance(obj, Backend) and not hasattr(obj, "post_thread"):
+            raise TypeError(f"{kind} does not implement post_thread()")
+        return obj
+    raise ValueError(f"unknown backend {kind!r} (x, outbox, dry-run or module:Class)")

repocast/cli.py

@@ -0,0 +1,212 @@
+"""repocast command line."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+from . import __version__, backends, config, model, runner
+from .weight import weighted_len
+
+
+def _cfg(a) -> dict:
+    over = {"input": {"path": getattr(a, "input", None), "kind": getattr(a, "kind", None), "posts": getattr(a, "posts", None)},
+            "post": {"backend": "dry-run" if getattr(a, "dry_run", False) else getattr(a, "backend", None),
+                     "state": getattr(a, "state", None), "outbox": getattr(a, "outbox", None),
+                     "account": getattr(a, "account", None)}}
+    if getattr(a, "mode", None):
+        over["format"] = {"mode": a.mode}
+    cfg = config.load(a.config if a.config else (("repocast.toml" if os.path.exists("repocast.toml") else None)), over)
+    if not cfg["input"]["path"]:
+        raise config.ConfigError("no input: pass --input or set [input].path")
+    return cfg
+
+
+def _items(cfg) -> list[dict]:
+    return model.load(cfg["input"]["path"], cfg["input"]["kind"], cfg["input"]["posts"] or None)
+
+
+def cmd_preview(a) -> int:
+    cfg = _cfg(a)
+    res = runner.preview(_items(cfg), cfg)
+    if a.last:
+        res = res[-a.last:]
+    if a.json:
+        print(json.dumps(res, indent=1, ensure_ascii=False))
+        return 0
+    ready = 0
+    for r in res:
+        if "posts" in r:
+            ready += 1
+            print(f"=== {r['short']} {r['date']} [{r['mode']}] READY ({', '.join(f'{n}/280' for n in r['weighted_lengths'])})")
+            print("\n--- reply ---\n".join(r["posts"]))
+        else:
+            print(f"=== {r['short']} {r['date']} SKIP: {r['skip']}")
+        print()
+    print(f"{ready} ready, {len(res) - ready} skipped")
+    return 0
+
+
+def _summary(actions: list[dict]) -> None:
+    path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if not path:
+        return
+    with open(path, "a", encoding="utf-8") as f:
+        f.write("### repocast\n\n")
+        for x in actions:
+            f.write(f"- **{x['action']}** {x.get('id', '')[:7]} {x.get('reason', '') or x.get('error', '')}\n")
+            for p in x.get("posts", []):
+                f.write("\n  ```\n  " + p.replace("\n", "\n  ") + "\n  ```\n")
+
+
+def _gh_output(**kv) -> None:
+    path = os.environ.get("GITHUB_OUTPUT")
+    if path:
+        with open(path, "a", encoding="utf-8") as f:
+            for k, v in kv.items():
+                f.write(f"{k}={v}\n")
+
+
+def cmd_run(a) -> int:
+    cfg = _cfg(a)
+    p = cfg["post"]
+    items = _items(cfg)
+    env = dict(os.environ)
+    try:
+        be = backends.make(p["backend"], p, env)
+    except ValueError as e:
+        if p["backend"] == "x" and "missing credentials" in str(e):
+            print(f"[repocast] {e}: DRY RUN", file=sys.stderr)
+            be = backends.DryRunBackend()
+        else:
+            raise
+    now = datetime.fromisoformat(a.now.replace("Z", "+00:00")) if a.now else datetime.now(timezone.utc)
+    state, actions, changed = runner.run(items, cfg, runner.load_state(p["state"]), env, now, be)
+    if changed and state is not None:
+        runner.save_state(p["state"], state)
+        print(f"[repocast] state saved: {p['state']}")
+    _summary(actions)
+    count = lambda k: sum(1 for x in actions if x["action"] == k)  # noqa: E731
+    _gh_output(posted=count("posted"), would_post=count("would_post"), skipped=count("skip"), deferred=count("defer"),
+               state_changed=str(changed).lower())
+    if any(x["action"] == "abort" for x in actions):
+        return 3
+    if any(x["action"] in ("failed", "uncertain", "partial") for x in actions):
+        return 1
+    return 0
+
+
+def cmd_count(a) -> int:
+    text = sys.stdin.read() if a.text == "-" else a.text
+    n = weighted_len(text)
+    print(f"{n}/280{'' if n <= 280 else '  TOO LONG'}")
+    return 0 if n <= 280 else 1
+
+
+def cmd_diff(a) -> int:
+    from .diff import diff_repo
+    data = diff_repo(a.repo, a.range, a.path or None, a.commit_url)
+    s = json.dumps(data, indent=1, ensure_ascii=False)
+    if a.out:
+        with open(a.out, "w", encoding="utf-8") as f:
+            f.write(s + "\n")
+        print(f"{len(data['items'])} commits with changes -> {a.out}")
+    else:
+        print(s)
+    return 0
+
+
+def cmd_verify(a) -> int:
+    cfg = _cfg(a) if (a.config or os.path.exists("repocast.toml")) else {"post": {"account": a.account, "account_id": None, "api_base": backends.API_BASE}}
+    acct = a.account or cfg["post"]["account"]
+    be = backends.XApiBackend({k: os.environ.get(k, "") for k in backends.CRED_ENV}, account=acct,
+                              account_id=cfg["post"].get("account_id"), api_base=cfg["post"]["api_base"])
+    try:
+        print(f"OK: credentials belong to {be.verify()}")
+        return 0
+    except backends.AccountMismatch as e:
+        print(f"MISMATCH: {e}", file=sys.stderr)
+        return 3
+
+
+def cmd_forget(a) -> int:
+    st = runner.load_state(a.state)
+    if not st:
+        print("no state file", file=sys.stderr)
+        return 1
+    hits = [k for k in st["items"] if k.startswith(a.id)]
+    if len(hits) != 1:
+        print(f"{len(hits)} items match {a.id!r}", file=sys.stderr)
+        return 1
+    rec = st["items"].pop(hits[0])
+    if rec["status"] in ("posted", "partial", "uncertain") and not a.force:
+        print(f"{hits[0][:7]} is {rec['status']}: it may be public already. Check the account, then use --force.", file=sys.stderr)
+        return 1
+    runner.save_state(a.state, st)
+    print(f"forgot {hits[0][:7]} ({rec['status']}); it will be considered again on the next run")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="repocast", description="Turn a repo's changes into accurate X posts, and post them safely.")
+    ap.add_argument("--version", action="version", version=f"repocast {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def common(sp):
+        sp.add_argument("--config", "-c", help="repocast.toml (default: ./repocast.toml if present)")
+        sp.add_argument("--input", "-i", help="knoblog feed.json / changes.json, or repocast items JSON")
+        sp.add_argument("--kind", choices=["auto", "knoblog-feed", "knoblog-changes", "items"])
+        sp.add_argument("--posts", help="knoblog posts.json (with --kind knoblog-changes)")
+        sp.add_argument("--mode", choices=config.MODES, help="prebuilt (knoblog's text), template, or auto")
+
+    sp = sub.add_parser("preview", help="compose + gate every item; ignores state and caps; posts nothing")
+    common(sp)
+    sp.add_argument("--json", action="store_true")
+    sp.add_argument("--last", type=int, help="only the newest N items")
+    sp.set_defaults(fn=cmd_preview)
+
+    sp = sub.add_parser("run", help="one bot run: dedup, caps, quiet hours, kill switch, then the backend")
+    common(sp)
+    sp.add_argument("--backend", help="x | outbox | dry-run | module:Class")
+    sp.add_argument("--dry-run", action="store_true", help="force the dry-run backend (records nothing)")
+    sp.add_argument("--state", help="state file (dedup)")
+    sp.add_argument("--outbox", help="outbox directory")
+    sp.add_argument("--account", help="X username the credentials must belong to")
+    sp.add_argument("--now", help=argparse.SUPPRESS)
+    sp.set_defaults(fn=cmd_run)
+
+    sp = sub.add_parser("count", help="X weighted length of a text ('-' = stdin)")
+    sp.add_argument("text")
+    sp.set_defaults(fn=cmd_count)
+
+    sp = sub.add_parser("diff", help="built-in simple diff: KEY = VALUE changes per commit -> items JSON")
+    sp.add_argument("--repo", default=".")
+    sp.add_argument("--range", required=True, help="e.g. HEAD~20..HEAD or v1.0..main")
+    sp.add_argument("--path", action="append", help="limit to these paths (repeatable)")
+    sp.add_argument("--commit-url", help="e.g. https://github.com/o/r/commit/{sha} (default: from origin)")
+    sp.add_argument("--out", "-o")
+    sp.set_defaults(fn=cmd_diff)
+
+    sp = sub.add_parser("verify-account", help="GET /2/users/me with the X_* credentials and compare to the account")
+    sp.add_argument("--config", "-c")
+    sp.add_argument("--account")
+    sp.set_defaults(fn=cmd_verify, input=None)
+
+    sp = sub.add_parser("forget", help="remove an item from the state file so it is considered again")
+    sp.add_argument("id")
+    sp.add_argument("--state", default=".repocast/state.json")
+    sp.add_argument("--force", action="store_true")
+    sp.set_defaults(fn=cmd_forget)
+
+    a = ap.parse_args(argv)
+    try:
+        return a.fn(a)
+    except (config.ConfigError, model.InputError, ValueError) as e:
+        print(f"repocast: error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

repocast/config.py

@@ -0,0 +1,100 @@
+"""repocast.toml loading and validation (stdlib tomllib)."""
+from __future__ import annotations
+
+import os
+import re
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib  # type: ignore
+
+from .fmt import TemplateError, validate_templates
+
+DEFAULTS = {
+    "input": {"path": "", "kind": "auto", "posts": ""},
+    "format": {"mode": "auto", "project": "", "date_format": "%b %-d", "disclaimer": "", "max_lines": 3,
+               "max_posts": 4, "max_line_weight": 140, "highlight": [], "name_style": "safe", "display_names": {}, "templates": {},
+               "trusted_text": [], "allow_mentions": False, "allow_hashtags": False, "honor_skips": True},
+    "filter": {"kinds": ["changed", "added", "removed"], "include": "", "exclude": "", "files": "",
+               "exclude_files": "", "min_pct": 0.0},
+    "post": {"backend": "dry-run", "account": "", "account_id": "", "outbox": "outbox",
+             "state": ".repocast/state.json", "max_per_run": 1, "max_per_day": 3, "stale_after_hours": 72,
+             "max_attempts": 2, "quiet_hours": "", "timezone": "UTC", "live_env": "REPOCAST_LIVE",
+             "kill_switch_env": "REPOCAST_KILL_SWITCH", "api_base": "https://api.x.com/2"},
+}
+MODES = ("auto", "prebuilt", "template")
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def _merge(base: dict, over: dict, where: str) -> dict:
+    out = {}
+    for sec, vals in base.items():
+        given = over.get(sec, {})
+        if not isinstance(given, dict):
+            raise ConfigError(f"[{sec}] must be a table")
+        unknown = set(given) - set(vals)
+        if unknown:
+            raise ConfigError(f"{where}: unknown key [{sec}].{sorted(unknown)[0]} (known: {', '.join(sorted(vals))})")
+        out[sec] = {**vals, **given}
+    unknown = set(over) - set(base)
+    if unknown:
+        raise ConfigError(f"{where}: unknown section [{sorted(unknown)[0]}]")
+    return out
+
+
+def validate(cfg: dict) -> dict:
+    f, p, flt = cfg["format"], cfg["post"], cfg["filter"]
+    if f["mode"] not in MODES:
+        raise ConfigError(f"[format].mode must be one of {MODES}")
+    try:
+        validate_templates(f["templates"])
+    except TemplateError as e:
+        raise ConfigError(str(e))
+    for k in ("max_lines", "max_posts", "max_per_run", "max_per_day", "max_attempts"):
+        sec = f if k in f else p
+        if not isinstance(sec[k], int) or sec[k] < 0:
+            raise ConfigError(f"{k} must be a non-negative integer")
+    if not 1 <= f["max_posts"] <= 25:
+        raise ConfigError("max_posts must be between 1 and 25")
+    for k in ("include", "exclude", "files", "exclude_files"):
+        try:
+            re.compile(flt[k])
+        except re.error as e:
+            raise ConfigError(f"[filter].{k}: bad regex ({e})")
+    if p["quiet_hours"] and not re.fullmatch(r"\d{1,2}:\d{2}-\d{1,2}:\d{2}", p["quiet_hours"]):
+        raise ConfigError("[post].quiet_hours must look like '22:00-07:00'")
+    try:
+        from zoneinfo import ZoneInfo
+        ZoneInfo(p["timezone"])
+    except Exception:  # noqa: BLE001
+        raise ConfigError(f"[post].timezone: unknown time zone {p['timezone']!r}")
+    if p["backend"] == "x" and not (p["account"] or p["account_id"]):
+        raise ConfigError("[post].backend = 'x' needs account (the @username to post as) or account_id")
+    return cfg
+
+
+def load(path: str | None, overrides: dict | None = None) -> dict:
+    raw: dict = {}
+    base_dir = os.getcwd()
+    if path:
+        try:
+            with open(path, "rb") as fh:
+                raw = tomllib.load(fh)
+        except FileNotFoundError:
+            raise ConfigError(f"config not found: {path}")
+        except tomllib.TOMLDecodeError as e:
+            raise ConfigError(f"{path}: {e}")
+        base_dir = os.path.dirname(os.path.abspath(path))
+    cfg = _merge(DEFAULTS, raw, path or "config")
+    for sec, vals in (overrides or {}).items():
+        cfg[sec].update({k: v for k, v in vals.items() if v is not None})
+    # relative paths in a config file are relative to that file
+    for sec, key in (("input", "path"), ("input", "posts"), ("post", "state"), ("post", "outbox")):
+        v = cfg[sec][key]
+        if v and path and not os.path.isabs(v) and not (overrides or {}).get(sec, {}).get(key):
+            cfg[sec][key] = os.path.normpath(os.path.join(base_dir, v))
+    return validate(cfg)

repocast/diff.py

@@ -0,0 +1,90 @@
+"""A deliberately simple built-in repo diff, for repos without knoblog.
+
+For each commit in a range it pairs removed/added lines that look like `KEY = VALUE` / `KEY: VALUE` /
+`#define KEY VALUE` / `const KEY: T = VALUE;` in the same file. A key that appears more than once among a file's
+removed or added lines is ambiguous and dropped (no guessing). For nested YAML/JSON, Python/C++ expressions,
+macros or parameter files with structure, use knoblog, which understands them.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+
+VALUE = r'(?P<v>[-+]?(?:\d[\d_\']*\.?\d*|\.\d+)(?:[eE][-+]?\d+)?(?:_?[a-zA-Z]\w{0,4})?|true|false|True|False|"[^"\n]{0,80}"|\'[^\'\n]{0,80}\')'
+KV = re.compile(
+    r'^\s*(?:#define\s+)?(?:(?:export|pub(?:\(crate\))?|const|static|let|var|final|constexpr|readonly|private|public|protected|inline)\s+)*'
+    r'(?:[\w:<>\[\]]+\s+)??["\']?(?P<k>[A-Za-z_][\w.\-]*)["\']?\s*(?::\s*[\w:<>\[\]]+\s*)?(?:=|:|\s)\s*' + VALUE +
+    r'\s*[,;]?\s*(?:(?://|#|--).*)?$')
+TYPES = {"int", "float", "double", "bool", "auto", "uint8_t", "uint16_t", "uint32_t", "int32_t", "size_t", "string"}
+
+
+def parse_line(line: str) -> tuple[str, str] | None:
+    m = KV.match(line)
+    if not m or m.group("k") in TYPES:
+        return None
+    return m.group("k"), m.group("v").strip("'\"") if m.group("v")[0] in "'\"" else m.group("v")
+
+
+def _git(repo: str, *args: str) -> str:
+    return subprocess.run(["git", "-C", repo, *args], check=True, capture_output=True, text=True).stdout
+
+
+def file_changes(lines: list[str]) -> list[dict]:
+    """lines = one file's unified diff body (lines starting with + / -)."""
+    rem: dict[str, list[str]] = {}
+    add: dict[str, list[str]] = {}
+    for ln in lines:
+        if ln.startswith(("+++", "---")) or not ln[:1] in "+-":
+            continue
+        kv = parse_line(ln[1:])
+        if kv:
+            (add if ln[0] == "+" else rem).setdefault(kv[0], []).append(kv[1])
+    out = []
+    for k in sorted(set(rem) | set(add)):
+        r, a = rem.get(k, []), add.get(k, [])
+        if len(r) > 1 or len(a) > 1:
+            continue  # ambiguous
+        if r and a:
+            if r[0] != a[0]:
+                out.append({"name": k, "kind": "changed", "old": r[0], "new": a[0]})
+        elif a:
+            out.append({"name": k, "kind": "added", "old": None, "new": a[0]})
+        else:
+            out.append({"name": k, "kind": "removed", "old": r[0], "new": None})
+    return out
+
+
+def remote_commit_url(repo: str) -> str | None:
+    try:
+        url = _git(repo, "remote", "get-url", "origin").strip()
+    except subprocess.CalledProcessError:
+        return None
+    m = re.match(r"(?:https://|git@)github\.com[:/](.+?)(?:\.git)?$", url)
+    return f"https://github.com/{m.group(1)}/commit/{{sha}}" if m else None
+
+
+def diff_repo(repo: str, rev_range: str, paths: list[str] | None = None, commit_url: str | None = None) -> dict:
+    """{'generator': 'repocast diff', 'items': [...]} for every commit in `rev_range` with at least one change."""
+    commit_url = commit_url or remote_commit_url(repo)
+    shas = _git(repo, "rev-list", "--reverse", "--no-merges", rev_range).split()
+    items = []
+    for sha in shas:
+        meta = _git(repo, "show", "-s", "--format=%cI%x00%s", sha).strip().split("\x00")
+        out = _git(repo, "show", "--format=", "-U0", "--no-color", "--no-ext-diff", sha, "--", *(paths or []))
+        changes, cur, buf = [], None, []
+
+        def flush():
+            if cur:
+                for c in file_changes(buf):
+                    changes.append({**c, "file": cur, "commit": sha})
+        for ln in out.splitlines():
+            if ln.startswith("diff --git "):
+                flush()
+                cur, buf = ln.split(" b/", 1)[-1], []
+            else:
+                buf.append(ln)
+        flush()
+        if changes:
+            items.append({"id": sha, "short": sha[:7], "date": meta[0], "title": meta[1] if len(meta) > 1 else None,
+                          "commit_url": commit_url.format(sha=sha) if commit_url else None, "changes": changes})
+    return {"generator": "repocast diff", "repo": repo, "range": rev_range, "items": items}