factory-framework 0.3.1__py3-none-any.whl

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.
ff/export.py ADDED
@@ -0,0 +1,234 @@
1
+ """Stakeholder proof exports (`html`, `csv`, `md`, `jsonl`) with optional `--summary`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import csv
6
+ import html
7
+ import io
8
+ import re
9
+ from pathlib import Path
10
+ from typing import Any
11
+ from urllib.parse import urlsplit
12
+ from xml.etree.ElementTree import Element
13
+
14
+ import markdown
15
+ from markdown.treeprocessors import Treeprocessor
16
+ from markdown.util import AMP_SUBSTITUTE
17
+
18
+ from ff import proofs, query
19
+ from ff.models import CheckRecord, Factory, InputError, Spec, encode_compact
20
+
21
+ _FORMULA_CHARS = ("=", "+", "-", "@", "|", "\uff1d", "\uff0b", "\uff0d", "\uff20")
22
+ _CTRL_WS_RE = re.compile(r"[\x00-\x20]+")
23
+ _LINK_SCHEMES = frozenset({"", "http", "https", "mailto"})
24
+ _IMG_SCHEMES = frozenset({"", "http", "https"})
25
+ _CSS = (
26
+ ":root{color-scheme:light;--bg:#FFFFFF;--panel:#F1F3F4;--ink:#202124;--muted:#595D62;--line:#9AA0A6;--primary:#174EA6;--focus:#4285F4;--sel:#D2E3FC;--ok:#0D652D;--ok-bg:#CEEAD6;--bad:#A50E0E;--bad-bg:#FAD2CF;--warn:#934900;--warn-bg:#FEEFC3}"
27
+ '*{box-sizing:border-box}::selection{background:var(--sel);color:var(--ink)}body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.625 "Google Sans",system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}'
28
+ "main{max-width:1152px;margin:0 auto;padding:32px 24px 64px}a[href]{color:var(--primary)}a:focus-visible{outline:2px solid var(--focus);outline-offset:2px;border-radius:4px}p{margin:8px 0}header{display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:16px;margin-bottom:24px}"
29
+ "h1{font-size:28px;line-height:1.25;color:var(--primary);margin:0}h3{font-size:16px;line-height:1.375;font-weight:600;margin:0}h2{font-size:20px;line-height:1.375;font-weight:600;margin:32px 0 12px;border-bottom:1px solid var(--line);padding-bottom:8px}"
30
+ 'code,pre{font:14px/1.6 "Google Sans Code",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}code{background:var(--panel);color:var(--primary);padding:1px 6px;border-radius:8px}pre{background:var(--panel);color:var(--ink);padding:16px;border-radius:12px;overflow-x:auto;overflow-wrap:normal}pre code{background:none;color:inherit;padding:0}'
31
+ ".tbl{overflow-x:auto;margin:12px 0}table{width:100%;border-collapse:collapse;font-size:14px}th,td{text-align:left;padding:8px 12px;border-bottom:1px solid var(--line);overflow-wrap:normal}.kpis{display:grid;grid-template-columns:repeat(auto-fit,minmax(200px,1fr));gap:16px;margin-bottom:24px}.kpi{background:var(--panel);border-radius:16px;padding:16px 20px}.kpi-val{font-size:24px;font-weight:700;line-height:1.375;font-variant-numeric:tabular-nums}"
32
+ ".card{background:var(--bg);border:1px solid var(--line);border-radius:16px;padding:20px;margin-bottom:16px;overflow-wrap:anywhere}.card h2:first-child{margin-top:0}.muted{color:var(--muted);font-size:14px;line-height:1.5}.badge{display:inline-block;padding:2px 10px;border-radius:9999px;font-size:12px;font-weight:600;line-height:1.5}.st-PROVEN,.st-PASS,.st-PASSED{background:var(--ok-bg);color:var(--ok)}.st-FAILING,.st-FAIL,.st-ERROR,.st-FAILED{background:var(--bad-bg);color:var(--bad)}.st-PARTIAL,.st-UNPROVEN,.st-UNCLEAR,.st-UNCOVERED,.st-UNRUN{background:var(--warn-bg);color:var(--warn)}.spec{border-top:1px solid var(--line);margin-top:16px;padding-top:16px}.checks{margin:8px 0 0;padding-left:20px;font-size:14px;line-height:1.5}.checks li{margin:4px 0}.row{display:flex;justify-content:space-between;align-items:baseline;flex-wrap:wrap;gap:8px 12px}@media print{main{padding:0}.kpi,.card{break-inside:avoid}}"
33
+ )
34
+
35
+
36
+ def neutralize_csv_cell(value: object) -> str:
37
+ """Escape spreadsheet formula prefixes per OWASP CSV Injection guidance."""
38
+ text = str(value)
39
+ if text[:1] in ("\t", "\r", "\n") or text.lstrip()[:1] in _FORMULA_CHARS:
40
+ return f"'{text}"
41
+ return text
42
+
43
+
44
+ def _clean_url(raw: str, *, allow_mailto: bool) -> str | None:
45
+ compact = _CTRL_WS_RE.sub("", html.unescape(raw.replace(AMP_SUBSTITUTE, "&")))
46
+ if "\\" in compact or compact.startswith("//"):
47
+ return None
48
+ try:
49
+ scheme = urlsplit(compact).scheme.lower()
50
+ except ValueError:
51
+ return None
52
+ first_seg = compact.split("/", 1)[0].split("#", 1)[0].split("?", 1)[0]
53
+ allowed = _LINK_SCHEMES if allow_mailto else _IMG_SCHEMES
54
+ return None if (scheme not in allowed or (not scheme and ":" in first_seg)) else raw.strip()
55
+
56
+
57
+ class _SanitizeTree(Treeprocessor):
58
+ def run(self, root: Element) -> Element:
59
+ for el in root.iter():
60
+ for attr, allow_m in (("href", True), ("src", False)):
61
+ if attr in el.attrib:
62
+ if (safe := _clean_url(el.attrib[attr], allow_mailto=allow_m)) is None:
63
+ del el.attrib[attr]
64
+ else:
65
+ el.attrib[attr] = safe
66
+ if attr == "href":
67
+ el.attrib["rel"] = "noopener noreferrer"
68
+ return root
69
+
70
+
71
+ def _safe_md(md_text: str) -> str:
72
+ engine = markdown.Markdown(extensions=["tables", "fenced_code"])
73
+ for mod, key in ((engine.preprocessors, "html_block"), (engine.inlinePatterns, "html")):
74
+ if key in mod:
75
+ mod.deregister(key)
76
+ engine.treeprocessors.register(_SanitizeTree(engine), "ff_sanitize", -10)
77
+ return engine.convert(md_text).replace("<table>", "<div class='tbl'><table>").replace("</table>", "</table></div>")
78
+
79
+
80
+ def _fmt_metrics(metrics_map: dict[str, Any]) -> str:
81
+ parts = [
82
+ f"{n}={m.get('value')}{f' {m["unit"]}' if m.get('unit') else ''}"
83
+ f"{f' ({", ".join(b)})' if (b := [f'{k} {m[k]}' for k in ('min', 'max') if m.get(k) is not None]) else ''}"
84
+ for n, m in sorted(metrics_map.items())
85
+ ]
86
+ return "; ".join(parts)
87
+
88
+
89
+ def _stats(
90
+ fac: Factory, recs: dict[str, CheckRecord], prfs: dict[str, dict[str, Any]], gate: dict[str, Any], domain: str
91
+ ) -> tuple[str, list[str], int, int, int, int, int, int]:
92
+ doms = [d for d in fac.domains if domain in ("", d)]
93
+ tot_i, tot_s = sum(len(prfs[d]["intents"]) for d in doms), sum(len(prfs[d]["specs"]) for d in doms)
94
+ prv_i = sum(iv["status"] == "PROVEN" for d in doms for iv in prfs[d]["intents"].values())
95
+ prv_s = sum(sv["status"] == "PROVEN" for d in doms for sv in prfs[d]["specs"].values())
96
+ d_cks = [c for c, ck in fac.checks.items() if ck.domain in doms]
97
+ pas_c = sum(c in recs and recs[c].status == "pass" for c in d_cks)
98
+ return ("PASSED" if gate["passed"] else "FAILED"), doms, prv_i, tot_i, prv_s, tot_s, pas_c, len(d_cks)
99
+
100
+
101
+ def _collect_rows(
102
+ factory: Factory, records: dict[str, CheckRecord], dom_proofs: dict[str, dict[str, Any]], *, domain: str = ""
103
+ ) -> list[dict[str, Any]]:
104
+ rows: list[dict[str, Any]] = []
105
+ for dom in (d for d in factory.domains if not domain or d == domain):
106
+ for sid, sv in sorted(dom_proofs.get(dom, {}).get("specs", {}).items()):
107
+ sp = factory.specs[sid]
108
+ summ = " | ".join(records[c].summary for c in sp.checks if c in records)
109
+ evid = [ev for c in sp.checks if c in records for ev in records[c].evidence]
110
+ head = {"domain": dom, "intents": list(sp.serves), "spec": sid, "spec_title": sp.title}
111
+ tail = {"status": sv["status"], "checks": list(sp.checks), "metrics": sv.get("metrics", {})}
112
+ rows.append(head | tail | {"summary": summ, "evidence": evid})
113
+ return rows
114
+
115
+
116
+ def _render_csv(rows: list[dict[str, Any]]) -> bytes:
117
+ buf = io.StringIO()
118
+ writer = csv.writer(buf, lineterminator="\r\n")
119
+ writer.writerow(["domain", "intents", "spec", "title", "status", "checks", "metrics", "summary", "evidence"])
120
+ for r in rows:
121
+ c1 = (r["domain"], ", ".join(r["intents"]), r["spec"], r["spec_title"], r["status"])
122
+ c2 = (", ".join(r["checks"]), _fmt_metrics(r["metrics"]), r["summary"], "; ".join(r["evidence"]))
123
+ writer.writerow([neutralize_csv_cell(c) for c in (*c1, *c2)])
124
+ return ("\ufeff" + buf.getvalue()).encode("utf-8")
125
+
126
+
127
+ def _md_spec_lines(fac: Factory, sp: Spec, sv: dict[str, Any], recs: dict[str, CheckRecord]) -> list[str]:
128
+ m_txt = _fmt_metrics(sv.get("metrics", {}))
129
+ out = [f"- **{sp.title}** (`{sp.id}`): `{sv['status']}`{f' — `{m_txt}`' if m_txt else ''}"]
130
+ for cid in sp.checks:
131
+ rec = recs.get(cid)
132
+ ev = f" [{', '.join(rec.evidence)}]" if rec and rec.evidence else ""
133
+ st, sm = (rec.status.upper(), rec.summary) if rec else ("UNRUN", fac.checks[cid].target)
134
+ out.append(f" - `{cid}` (`{st}`): {sm}{ev}")
135
+ return out
136
+
137
+
138
+ def _render_markdown(
139
+ fac: Factory, recs: dict[str, CheckRecord], prfs: dict[str, Any], gate: dict[str, Any], dom: str, summ: str
140
+ ) -> bytes:
141
+ verdict, domains, prv_i, tot_i, prv_s, tot_s, _, _ = _stats(fac, recs, prfs, gate, dom)
142
+ lines = [
143
+ f"# Proof Report — {fac.name}",
144
+ "",
145
+ f"**Gate**: `{verdict}` · **Intents**: `{prv_i}/{tot_i}` proven · **Specs**: `{prv_s}/{tot_s}` proven",
146
+ ]
147
+ if summ.strip():
148
+ lines.extend(["", "## Executive Summary", "", summ.strip()])
149
+ for d in domains:
150
+ doc, shown = prfs[d], set()
151
+ lines.extend(["", f"## Domain: `{d}` (`{doc['status']}`)"])
152
+ for iid, iv in sorted(doc["intents"].items()):
153
+ it = fac.intents[iid]
154
+ lines.extend(["", f"### {it.title} (`{iid}`) — `{iv['status']}`", "", it.body])
155
+ for sid in it.specs:
156
+ shown.add(sid)
157
+ sp = fac.specs[sid]
158
+ lines.extend(_md_spec_lines(fac, sp, doc["specs"].get(sid) or prfs[sp.domain]["specs"][sid], recs))
159
+ if extra := [sid for sid in sorted(doc["specs"]) if sid not in shown]:
160
+ lines.extend(["", "### Cross-Domain & Unlinked Specs"])
161
+ lines.extend(ln for sid in extra for ln in _md_spec_lines(fac, fac.specs[sid], doc["specs"][sid], recs))
162
+ return ("\n".join(lines).rstrip() + "\n").encode("utf-8")
163
+
164
+
165
+ def _badge(st: str) -> str:
166
+ return f"<span class='badge st-{html.escape(st)}'>{html.escape(st)}</span>"
167
+
168
+
169
+ def _html_spec(fac: Factory, sp: Spec, sv: dict[str, Any], recs: dict[str, CheckRecord]) -> list[str]:
170
+ esc, m_txt = html.escape, _fmt_metrics(sv.get("metrics", {}))
171
+ out = [
172
+ f"<div class='spec'><div class='row'><strong>{esc(sp.title)} <code>{esc(sp.id)}</code></strong>{_badge(sv['status'])}</div>{_safe_md(sp.body)}"
173
+ ]
174
+ if m_txt:
175
+ out.append(f"<div class='muted'>Metrics: <code>{esc(m_txt)}</code></div>")
176
+ if sp.checks:
177
+ out.append("<ul class='checks'>")
178
+ for cid in sp.checks:
179
+ c_st, c_sum = (r.status.upper(), r.summary) if (r := recs.get(cid)) else ("UNRUN", fac.checks[cid].target)
180
+ ev_h = f" <span class='muted'>({esc(', '.join(r.evidence))})</span>" if r and r.evidence else ""
181
+ out.append(f"<li>{_badge(c_st)} <code>{esc(cid)}</code> — {esc(c_sum)}{ev_h}</li>")
182
+ out.append("</ul>")
183
+ return [*out, "</div>"]
184
+
185
+
186
+ def _render_html(
187
+ fac: Factory, recs: dict[str, CheckRecord], prfs: dict[str, Any], gate: dict[str, Any], dom: str, summ: str
188
+ ) -> bytes:
189
+ esc, (verdict, domains, prv_i, tot_i, prv_s, tot_s, pas_c, tot_c) = html.escape, _stats(fac, recs, prfs, gate, dom)
190
+ head_meta = f"<meta charset='utf-8'><meta name='viewport' content='width=device-width,initial-scale=1'><meta name='description' content='Deterministic verification proof report for {esc(fac.name)}.'><link rel='icon' href='data:,'>"
191
+ out = [
192
+ f"<!doctype html><html lang='en'><head>{head_meta}<title>Proof Report — {esc(fac.name)}</title><style>{_CSS}</style></head><body><main>",
193
+ f"<header><div><h1>{esc(fac.name)} — Proof Report</h1><div class='muted'>Deterministic verification from executed checks</div></div><span class='badge st-{verdict}'>Gate: {verdict}</span></header>",
194
+ f"<section class='kpis'><div class='kpi'><div class='muted'>Intents Proven</div><div class='kpi-val'>{prv_i} / {tot_i}</div></div><div class='kpi'><div class='muted'>Specs Proven</div><div class='kpi-val'>{prv_s} / {tot_s}</div></div><div class='kpi'><div class='muted'>Checks Passing</div><div class='kpi-val'>{pas_c} / {tot_c}</div></div></section>",
195
+ ]
196
+ if summ.strip():
197
+ out.append(f"<section class='card'><h2>Executive Summary</h2>{_safe_md(summ)}</section>")
198
+ for d in domains:
199
+ doc, shown = prfs[d], set()
200
+ out.append(f"<h2>Domain: {esc(d)} {_badge(doc['status'])}</h2>")
201
+ for iid, iv in sorted(doc["intents"].items()):
202
+ it = fac.intents[iid]
203
+ hdr = f"<div class='row'><h3>{esc(it.title)} <code>{esc(iid)}</code></h3>{_badge(iv['status'])}</div>"
204
+ out.append(f"<article class='card'>{hdr}{_safe_md(it.body)}")
205
+ for sid in it.specs:
206
+ shown.add(sid)
207
+ sp = fac.specs[sid]
208
+ out.extend(_html_spec(fac, sp, doc["specs"].get(sid) or prfs[sp.domain]["specs"][sid], recs))
209
+ out.append("</article>")
210
+ if extra := [sid for sid in sorted(doc["specs"]) if sid not in shown]:
211
+ out.append("<article class='card'><h3>Cross-Domain &amp; Unlinked Specs</h3>")
212
+ out.extend(el for sid in extra for el in _html_spec(fac, fac.specs[sid], doc["specs"][sid], recs))
213
+ out.append("</article>")
214
+ return ("".join(out) + "</main></body></html>\n").encode("utf-8")
215
+
216
+
217
+ def export_proofs(factory: Factory, *, fmt: str = "md", domain: str = "", summary_path: Path | None = None) -> bytes:
218
+ """Render deterministic proof exports in `html`, `csv`, `md`, or `jsonl`."""
219
+ kind = fmt.strip().lower()
220
+ if kind not in {"html", "csv", "md", "jsonl"}:
221
+ raise InputError(f"unsupported export format '{fmt}'; choose html, csv, md, or jsonl")
222
+ if domain and domain not in factory.domains:
223
+ raise InputError(f"unknown domain '{domain}'")
224
+ if summary_path is not None and not summary_path.is_file():
225
+ raise InputError(f"summary file not found: '{summary_path}'")
226
+ summary_md = summary_path.read_text(encoding="utf-8") if summary_path is not None else ""
227
+ records, dom_proofs, _, _ = query.load_saved_state(factory)
228
+ gate = proofs.evaluate_gate(factory, {domain: dom_proofs[domain]} if domain else dom_proofs)
229
+ rows = _collect_rows(factory, records, dom_proofs, domain=domain)
230
+ if kind in {"csv", "jsonl"}:
231
+ return _render_csv(rows) if kind == "csv" else b"".join(encode_compact(r) for r in rows)
232
+ return (_render_html if kind == "html" else _render_markdown)(
233
+ factory, records, dom_proofs, gate, domain, summary_md
234
+ )
ff/gitio.py ADDED
@@ -0,0 +1,229 @@
1
+ """Safe literal-argv Git and GitHub CLI helpers for `--base` snapshots, issues, and pollution checks."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import io
6
+ import json
7
+ import os
8
+ import re
9
+ import shutil
10
+ import subprocess
11
+ import tarfile
12
+ import tempfile
13
+ from collections.abc import Generator
14
+ from contextlib import contextmanager
15
+ from pathlib import Path
16
+
17
+ import yaml
18
+
19
+ from ff import models as m
20
+
21
+ _GH_FIELDS = "number,title,body,state,url"
22
+ _GH_HEADER_RE = re.compile(r"^\s*(?:[-*]\s+)?([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*?)\s*$")
23
+ _FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")
24
+ _ISSUE_REF_RE = re.compile(r"(?<![A-Za-z0-9_])#([1-9][0-9]*)\b")
25
+ _SECTIONS_MAP = {"why": "motivation", "motivation": "motivation", "what": "changes", "changes": "changes"}
26
+ _ID_RXS = (m.INTENT_ID_RE, m.SPEC_ID_RE, m.CHECK_ID_RE)
27
+
28
+
29
+ def _git_bin() -> str:
30
+ if (git_path := shutil.which("git")) is None:
31
+ raise m.Error("git executable not found on PATH")
32
+ return git_path
33
+
34
+
35
+ def _run_git(root: Path, args: list[str], *, check: bool = True) -> subprocess.CompletedProcess[bytes]:
36
+ proc = subprocess.run([_git_bin(), *args], cwd=root, capture_output=True, check=False, shell=False) # noqa: S603
37
+ if check and proc.returncode != 0:
38
+ lines = proc.stderr.decode("utf-8", errors="replace").strip().splitlines()
39
+ raise m.Error(lines[0] if lines else f"git {' '.join(args)} failed")
40
+ return proc
41
+
42
+
43
+ def is_git_repo(root: Path) -> bool:
44
+ """Return True if `root` is inside a Git work tree."""
45
+ return shutil.which("git") is not None and (
46
+ (p := _run_git(root, ["rev-parse", "--is-inside-work-tree"], check=False)).returncode == 0
47
+ and p.stdout.strip() == b"true"
48
+ )
49
+
50
+
51
+ def merge_base(root: Path, ref: str) -> str:
52
+ """Resolve `git merge-base <ref> HEAD` safely."""
53
+ if not (cleaned := ref.strip()) or cleaned.startswith("-"):
54
+ raise m.InputError(f"invalid Git ref '{ref}'")
55
+ if not is_git_repo(root):
56
+ raise m.Error(f"--base '{cleaned}' requires a Git repository")
57
+ ver = _run_git(root, ["rev-parse", "--verify", "--quiet", "--end-of-options", f"{cleaned}^{{commit}}"], check=False)
58
+ if ver.returncode != 0:
59
+ raise m.Error(f"cannot resolve Git ref '{cleaned}'")
60
+ if (mb := _run_git(root, ["merge-base", ver.stdout.decode("utf-8").strip(), "HEAD"], check=False)).returncode != 0:
61
+ raise m.Error(f"no merge-base between '{cleaned}' and HEAD")
62
+ return mb.stdout.decode("utf-8").strip()
63
+
64
+
65
+ @contextmanager
66
+ def checkout_factory_at_ref(root: Path, factory_dir: Path, ref: str) -> Generator[Path | None]:
67
+ """Extract `factory/` at `merge-base(ref, HEAD)` into a temporary directory (or `None` if absent)."""
68
+ commit = merge_base(root, ref)
69
+ repo_top = Path(_run_git(root, ["rev-parse", "--show-toplevel"]).stdout.decode("utf-8").strip()).resolve()
70
+ try:
71
+ rel_factory = factory_dir.resolve().relative_to(repo_top).as_posix()
72
+ except ValueError as exc:
73
+ raise m.Error("factory directory must reside inside the Git repository for --base") from exc
74
+ if _run_git(repo_top, ["cat-file", "-e", f"{commit}:{rel_factory}"], check=False).returncode != 0:
75
+ yield None
76
+ return
77
+ archive = _run_git(repo_top, ["archive", "--format=tar", commit, rel_factory])
78
+ with tempfile.TemporaryDirectory(prefix="ff-base-") as tmp:
79
+ with tarfile.open(fileobj=io.BytesIO(archive.stdout), mode="r:") as tar:
80
+ tar.extractall(path=(tmp_root := Path(tmp)), filter="data")
81
+ yield ext if (ext := tmp_root / rel_factory).joinpath("ff.yaml").is_file() else None
82
+
83
+
84
+ def workspace_status_paths(root: Path) -> set[str] | None:
85
+ """Return modified/untracked paths from `git status --porcelain=v1 -z -uall`, or `None` outside Git."""
86
+ if not is_git_repo(root):
87
+ return None
88
+ proc = _run_git(root, ["status", "--porcelain=v1", "-z", "-uall"], check=False)
89
+ if proc.returncode != 0:
90
+ return None
91
+ entries, paths, idx = proc.stdout.split(b"\x00"), set(), 0
92
+ while idx < len(entries):
93
+ raw, idx = entries[idx], idx + 1
94
+ if len(raw) >= 4:
95
+ st = raw[:2].decode("utf-8", errors="replace")
96
+ paths.add(raw[3:].decode("utf-8", errors="replace"))
97
+ if ("R" in st or "C" in st) and idx < len(entries) and entries[idx]:
98
+ paths.add(entries[idx].decode("utf-8", errors="replace"))
99
+ idx += 1
100
+ return paths
101
+
102
+
103
+ def commit_issue_refs(root: Path, base_ref: str) -> set[int]:
104
+ """Extract `#<number>` issue references from `merge-base(base_ref, HEAD)..HEAD` commits and `$GH_PR_BODY`."""
105
+ raw = _run_git(root, ["log", "--format=%B", f"{merge_base(root, base_ref)}..HEAD"]).stdout
106
+ texts = (raw.decode("utf-8", errors="replace"), os.environ.get("GH_PR_BODY", ""))
107
+ return {int(match.group(1)) for txt in texts for match in _ISSUE_REF_RE.finditer(txt)}
108
+
109
+
110
+ def _is_touch_id(tok: str) -> bool:
111
+ return tok == "gate" or any(rx.fullmatch(tok) for rx in _ID_RXS)
112
+
113
+
114
+ def _parse_change_md(lines: list[str], *, gh: bool = False) -> tuple[str, dict[str, str], dict[str, str]]:
115
+ headers: dict[str, str] = {}
116
+ secs: dict[str, list[str]] = {"motivation": [], "changes": [], "impact": []}
117
+ title, cur, fence = "", "", ""
118
+ for raw in lines:
119
+ line = raw.rstrip("\r")
120
+ if fence:
121
+ if (fm := _FENCE_RE.match(line)) and fm.group(1)[0] == fence[0] and len(fm.group(1)) >= len(fence):
122
+ fence = ""
123
+ if cur in secs:
124
+ secs[cur].append(line)
125
+ continue
126
+ if fm := _FENCE_RE.match(line):
127
+ fence = fm.group(1)
128
+ elif not gh and line.startswith("# "):
129
+ title = line[2:].strip() or title
130
+ continue
131
+ elif line.startswith("## "):
132
+ key = line[3:].strip().lower()
133
+ cur = _SECTIONS_MAP.get(key, "impact" if key == "impact" else "-") if gh else key
134
+ continue
135
+ elif gh and not cur and (kv := _GH_HEADER_RE.match(line)):
136
+ k, v = kv.group(1).strip().lower().replace("-", "_"), kv.group(2).strip()
137
+ headers[k] = f"{headers[k]}, {v}" if k == "touches" and k in headers else v
138
+ if cur in secs:
139
+ secs[cur].append(line)
140
+ return title, headers, {k: "\n".join(v).strip() for k, v in secs.items()}
141
+
142
+
143
+ def parse_file_changes(factory_dir: Path, diags: list[m.Diagnostic]) -> dict[str, m.Change]:
144
+ """Parse and validate `factory/changes/YYYY-MM-DD_<slug>.md` change notes."""
145
+ cdir, out = factory_dir / "changes", {}
146
+
147
+ def _err(msg: str, rel: str, line: int = 0, item: str = "") -> None:
148
+ diags.append(m.Diagnostic("FF008", "error", msg, rel, line, item))
149
+
150
+ for path in sorted(p for p in cdir.glob("*.md") if not p.name.startswith(".")) if cdir.is_dir() else ():
151
+ rel = path.relative_to(factory_dir).as_posix()
152
+ text = m.read_safe_bytes(path, rel).decode("utf-8")
153
+ end = text.find("\n---\n", 4) if text.startswith("---\n") else -1
154
+ if end == -1:
155
+ _err(f"{rel}: missing or unterminated YAML frontmatter", rel, 1)
156
+ continue
157
+ try:
158
+ fm = yaml.safe_load(text[4:end])
159
+ except yaml.YAMLError as exc:
160
+ _err(f"{rel}: invalid frontmatter YAML ({exc})", rel, 1)
161
+ continue
162
+ if not isinstance(fm, dict):
163
+ _err(f"{rel}: frontmatter must be a mapping", rel, 1)
164
+ continue
165
+ cid, ctype, cstate = path.stem, str(fm.get("type") or ""), str(fm.get("state") or "open")
166
+ id_ok = bool(m.CHANGE_FILE_ID_RE.fullmatch(cid))
167
+ if not id_ok:
168
+ _err(f"{rel}: filename must match YYYY-MM-DD_<slug>.md", rel, 1, cid)
169
+ if fm.get("id") is not None and str(fm["id"]) != cid:
170
+ _err(f"{rel}: frontmatter id '{fm['id']}' must match '{cid}'", rel, 1, cid)
171
+ id_ok = False
172
+ if ctype not in m.CHANGE_TYPES:
173
+ _err(f"{rel}: invalid type '{ctype}'", rel, item=cid)
174
+ if cstate not in m.CHANGE_STATES:
175
+ _err(f"{rel}: invalid state '{cstate}'", rel, item=cid)
176
+ touches: list[str] = []
177
+ if not isinstance(tr := fm.get("touches"), list) or not tr:
178
+ _err(f"{rel}: 'touches' must be a non-empty list", rel, item=cid)
179
+ else:
180
+ for tid in map(str, tr):
181
+ if not _is_touch_id(tid):
182
+ _err(f"{rel}: invalid touched ID '{tid}'", rel, item=cid)
183
+ elif tid not in touches:
184
+ touches.append(tid)
185
+ title, _, secs = _parse_change_md(text[end + 5 :].splitlines(), gh=False)
186
+ if not secs["motivation"] or not secs["changes"]:
187
+ _err(f"{rel}: requires non-empty '## Motivation' and '## Changes'", rel, item=cid)
188
+ if id_ok and ctype in m.CHANGE_TYPES and cstate in m.CHANGE_STATES and touches:
189
+ args = (secs["motivation"], secs["changes"], secs["impact"])
190
+ out[cid] = m.Change(cid, ctype, tuple(touches), cstate, rel, title or cid, *args)
191
+ return dict(sorted(out.items()))
192
+
193
+
194
+ def fetch_github_changes(root: Path, label: str = "ff-change") -> dict[str, m.Change]:
195
+ """Load changes from labeled GitHub issues via `gh issue list` (fail-closed)."""
196
+ if not label.strip() or label.startswith("-") or any(c in label for c in ("\0", "\n", "\r")):
197
+ raise m.Error(f"invalid GitHub change label '{label}'")
198
+ if (gh_bin := shutil.which("gh")) is None:
199
+ raise m.Error("gh CLI not found on PATH; install GitHub CLI or set changes.source: files")
200
+ argv = [gh_bin, "issue", "list", "--label", label, "--state", "all", "--limit", "200", "--json", _GH_FIELDS]
201
+ try:
202
+ proc = subprocess.run(argv, cwd=root, capture_output=True, text=True, timeout=30, check=False, shell=False) # noqa: S603
203
+ except (OSError, subprocess.TimeoutExpired) as exc:
204
+ raise m.Error(f"failed to execute gh issue list: {exc}") from exc
205
+ if proc.returncode != 0:
206
+ msg = (proc.stderr or proc.stdout).strip().splitlines()
207
+ raise m.Error(f"gh issue list failed: {msg[0] if msg else proc.returncode}")
208
+ try:
209
+ items = json.loads(proc.stdout)
210
+ except json.JSONDecodeError as exc:
211
+ raise m.Error(f"gh issue list returned invalid JSON: {exc}") from exc
212
+ if not isinstance(items, list) or not all(isinstance(x, dict) for x in items):
213
+ raise m.Error("gh issue list response must be a JSON array of objects")
214
+ out: dict[str, m.Change] = {}
215
+ for entry in items:
216
+ if type(num := entry.get("number")) is not int or num <= 0:
217
+ raise m.Error(f"gh issue entry has invalid number: {num!r}")
218
+ cid, url, body = f"gh-{num}", str(entry.get("url") or "").strip(), str(entry.get("body") or "")
219
+ title = str(entry.get("title") or cid).strip() or cid
220
+ _, hdrs, secs = _parse_change_md(body.splitlines(), gh=True)
221
+ raw_t = (hdrs.get("type") or hdrs.get("kind") or "").strip().lower()
222
+ ctype = raw_t if raw_t in m.CHANGE_TYPES else "chore"
223
+ c_open = "open" if str(entry.get("state") or "").strip().upper() == "OPEN" else "done"
224
+ cstate = "dropped" if hdrs.get("state", "").strip().lower() == "dropped" else c_open
225
+ raw_tc = (t for r in hdrs.get("touches", "").split(",") if (t := r.strip().strip("[]\"' ")) and _is_touch_id(t))
226
+ tchs = tuple(dict.fromkeys(raw_tc))
227
+ args = (secs["motivation"] or body.strip() or title, secs["changes"] or title, secs["impact"], url)
228
+ out[cid] = m.Change(cid, ctype, tchs, cstate, url or f"github:#{num}", title, *args)
229
+ return dict(sorted(out.items()))