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/parse.py ADDED
@@ -0,0 +1,457 @@
1
+ """Load `ff.yaml`, `<domain>` Markdown/check files, tests, and file/GitHub changes."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ast
6
+ import os
7
+ import re
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ import yaml
12
+
13
+ from ff import gitio, schemas
14
+ from ff import models as mdl
15
+ from ff.models import Diagnostic, DomainCheckConfig, Error, Factory, InputError, LinkSource, MetricRule
16
+
17
+ _FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")
18
+ _ATX_RE = re.compile(r"^(#{1,6})\s+(.+?)(?:\s+#+)?\s*$")
19
+ _ANCHOR_RE = re.compile(r"\{(?:#|:[^}]*|\.[a-zA-Z_])[^}]*\}\s*$")
20
+ _ATTR_LINE_RE = re.compile(r"^\s*\{(?:#|:)[^}]+\}\s*$")
21
+ _CHECKBOX_RE = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+\[[ xX]\]\s")
22
+ _HTML_COMMENT_RE = re.compile(r"^\s*<!--.*-->\s*$")
23
+
24
+
25
+ def _err(code: str, msg: str, path: str = "", line: int = 0, item: str = "", hint: str = "") -> Diagnostic:
26
+ return Diagnostic(code, "error", msg, path, line, item, hint)
27
+
28
+
29
+ def resolve_factory_dir(factory_arg: str | Path | None = None, cwd: Path | None = None) -> Path:
30
+ """Locate `factory/` from `--factory`, `FF_FACTORY`, or ancestor search."""
31
+ base = (cwd or Path.cwd()).resolve()
32
+ raw = str(factory_arg).strip() if factory_arg is not None else os.environ.get("FF_FACTORY", "").strip()
33
+ if raw:
34
+ t = Path(raw).expanduser()
35
+ target = t if t.is_absolute() else base / t
36
+ if target.is_symlink():
37
+ raise Error(f"{target}: factory directory must not be a symlink")
38
+ if not target.is_dir() or not (target / "ff.yaml").is_file():
39
+ raise InputError(f"factory not found at '{target}' (missing ff.yaml; hint: run 'ff init')")
40
+ return target.resolve()
41
+ for anc in (base, *base.parents):
42
+ for cand in (anc if anc.name == "factory" else None, anc / "factory"):
43
+ if cand and cand.is_dir() and not cand.is_symlink() and (cand / "ff.yaml").is_file():
44
+ return cand.resolve()
45
+ if (anc / ".git").exists():
46
+ break
47
+ raise InputError("no factory/ff.yaml found; pass --factory PATH or run 'ff init'")
48
+
49
+
50
+ def _read(fdir: Path, rel: str) -> bytes:
51
+ return mdl.read_safe_bytes(fdir / rel, rel)
52
+
53
+
54
+ def _scan_factory_files(factory_dir: Path) -> tuple[Path, dict[str, str]]:
55
+ if factory_dir.is_symlink() or (fdir := factory_dir.resolve()).is_symlink():
56
+ raise Error(f"{factory_dir}: factory directory must not be a symlink")
57
+ files, cdirs = {}, frozenset({"intents", "specs", "checks", "tests", "changes"})
58
+ for root_str, dirnames, filenames in os.walk(fdir, followlinks=False):
59
+ cur = Path(root_str)
60
+ for name in sorted((*dirnames, *filenames)):
61
+ if (cur / name).is_symlink():
62
+ raise Error(f"{(cur / name).relative_to(fdir).as_posix()}: symlinks inside factory/ are forbidden")
63
+ dirnames[:] = sorted(d for d in dirnames if d != "__pycache__" and not d.startswith("."))
64
+ rel_dir = cur.relative_to(fdir)
65
+ if cur == fdir and "ff.yaml" in filenames:
66
+ files["ff.yaml"] = mdl.sha256_hex(_read(fdir, "ff.yaml"))
67
+ elif rel_dir.parts and rel_dir.parts[0] in cdirs:
68
+ for fn in (f for f in filenames if not f.startswith(".") and not f.endswith((".pyc", ".pyo"))):
69
+ r = f"{rel_dir.as_posix()}/{fn}"
70
+ files[r] = mdl.sha256_hex(_read(fdir, r))
71
+ if not (fdir / "ff.yaml").is_file():
72
+ raise InputError(f"missing '{fdir / 'ff.yaml'}'; run 'ff init'")
73
+ return fdir, dict(sorted(files.items()))
74
+
75
+
76
+ def _yaml_fail(rel: str, msg: str, code: str, diags: list[Diagnostic], exc: Exception | None = None) -> None:
77
+ if rel == "ff.yaml":
78
+ raise Error(msg) from exc
79
+ diags.append(_err(code, msg, rel, 1))
80
+
81
+
82
+ def _id_tuple(val: object, rx: re.Pattern[str]) -> tuple[str, ...] | None:
83
+ return tuple(str(x) for x in val if rx.fullmatch(str(x))) if isinstance(val, list) else None
84
+
85
+
86
+ def _load_yaml_doc(fdir: Path, rel: str, sch: Any, code: str, diags: list[Diagnostic]) -> dict[str, Any] | None:
87
+ try:
88
+ raw = yaml.safe_load(_read(fdir, rel).decode("utf-8"))
89
+ except yaml.YAMLError as exc:
90
+ _yaml_fail(rel, f"{rel}: invalid YAML ({exc})", code, diags, exc)
91
+ return None
92
+ if not isinstance(raw, dict) or raw.get("version") != mdl.FORMAT or type(raw.get("version")) is not int:
93
+ m = (
94
+ f"expected 'version: {mdl.FORMAT}'"
95
+ if isinstance(raw, dict)
96
+ else "top-level document must be a YAML mapping"
97
+ )
98
+ _yaml_fail(rel, f"{rel}: {m}", code, diags)
99
+ return None
100
+ for err_msg in schemas.validate(sch, raw, label=rel):
101
+ hint = "specs must serve intents (intent_*), never other specs" if "serves" in err_msg else ""
102
+ diags.append(_err(code, err_msg, rel, 1, hint=hint))
103
+ return raw
104
+
105
+
106
+ def _as_dict(val: object) -> dict[str, Any]:
107
+ return val if isinstance(val, dict) else {}
108
+
109
+
110
+ def _load_config(factory_dir: Path, diags: list[Diagnostic]) -> mdl.Config:
111
+ if (raw := _load_yaml_doc(factory_dir, "ff.yaml", "ff.yaml", "FF001", diags)) is None:
112
+ raise Error("ff.yaml: invalid configuration")
113
+ gr, cr, rr = _as_dict(raw.get("gate")), _as_dict(raw.get("changes")), _as_dict(raw.get("run"))
114
+ fo, py_r = gr.get("fail_on"), rr.get("pytest")
115
+ fail_on = tuple(str(x) for x in fo if str(x) in mdl.GATE_TOKENS) if isinstance(fo, list) else mdl.DEFAULT_FAIL_ON
116
+ chg_src: mdl.ChangesSource = "github" if cr.get("source") == "github" else "files"
117
+ gh_label = str(cr.get("github_label") or "ff-change")
118
+ py_argv = tuple(map(str, py_r)) if isinstance(py_r, list) and py_r else ("pytest",)
119
+ runners = {
120
+ ext: tuple(map(str, cmd))
121
+ for ext, cmd in _as_dict(rr.get("runners")).items()
122
+ if isinstance(ext, str) and mdl.RUNNER_EXT_RE.fullmatch(ext) and isinstance(cmd, list) and cmd
123
+ }
124
+ jobs = rr["jobs"] if type(rr.get("jobs")) is int and rr["jobs"] >= 0 else 0
125
+ timeout = rr["timeout"] if type(rr.get("timeout")) is int and rr["timeout"] >= 1 else 120
126
+ env_raw = [str(e) for e in rr["env"]] if isinstance(rr.get("env"), list) else []
127
+ diags.extend(_err("FF001", f"ff.yaml: run.env forbids '{e}'", "ff.yaml") for e in env_raw if mdl.is_denied_env(e))
128
+ env_ok = tuple(e for e in env_raw if not mdl.is_denied_env(e))
129
+ name = str(raw.get("name") or factory_dir.parent.name or "factory")
130
+ return mdl.Config(mdl.FORMAT, name, fail_on, chg_src, gh_label, py_argv, runners, jobs, timeout, env_ok)
131
+
132
+
133
+ def _parse_metric_rules(raw_m: object, rel: str, owner: str, diags: list[Diagnostic]) -> dict[str, MetricRule]:
134
+ out: dict[str, MetricRule] = {}
135
+ for mn, mc in _as_dict(raw_m).items():
136
+ if isinstance(mc, dict) and mdl.METRIC_RE.fullmatch(str(mn)):
137
+ lo = mc["min"] if mdl.is_finite_number(mc.get("min")) else None
138
+ hi = mc["max"] if mdl.is_finite_number(mc.get("max")) else None
139
+ if lo is not None and hi is not None and lo > hi:
140
+ diags.append(_err("FF001", f"{rel}: metric '{mn}' on '{owner}' has min > max", rel, item=owner))
141
+ pr = mc["precision"] if type(mc.get("precision")) is int else None
142
+ out[str(mn)] = MetricRule(lo, hi, pr, str(mc.get("unit", "")))
143
+ return out
144
+
145
+
146
+ def _load_domain_checks(fdir: Path, intent_doms: set[str], diags: list[Diagnostic]) -> dict[str, DomainCheckConfig]:
147
+ cdir, out = fdir / "checks", {}
148
+ for entry in sorted(cdir.iterdir()) if cdir.is_dir() else ():
149
+ if entry.name.startswith(".") or (entry.is_dir() and entry.name == "__pycache__"):
150
+ continue
151
+ rel = f"checks/{entry.name}"
152
+ if entry.is_dir() or entry.suffix != ".yaml":
153
+ ext_h = f"rename to checks/{entry.stem}.yaml" if entry.suffix == ".yml" else f"move to tests/{entry.name}"
154
+ m = f"{rel}: nested dirs forbidden" if entry.is_dir() else f"{rel}: checks/ allows only '<domain>.yaml'"
155
+ diags.append(_err("FF001", m, rel, 1, hint="use tests/" if entry.is_dir() else ext_h))
156
+ continue
157
+ if not mdl.DOMAIN_RE.fullmatch(dom := entry.stem):
158
+ diags.append(_err("FF001", f"{rel}: domain stem '{dom}' must match [a-z0-9-]+", rel, 1))
159
+ continue
160
+ if (raw := _load_yaml_doc(fdir, rel, "checks", "FF001", diags)) is None:
161
+ continue
162
+ if raw.get("domain") is not None and raw.get("domain") != dom:
163
+ diags.append(_err("FF001", f"{rel}: domain '{raw.get('domain')}' must equal '{dom}'", rel, 1))
164
+ if dom not in intent_doms:
165
+ diags.append(_err("FF006", f"{rel} has no matching intents/{dom}.md", rel, 1, hint=f"add intents/{dom}.md"))
166
+ sp_out: dict[str, mdl.SpecOverride] = {}
167
+ for sid, sd in _as_dict(raw.get("specs")).items():
168
+ if isinstance(sid, str) and mdl.SPEC_ID_RE.fullmatch(sid) and isinstance(sd, dict):
169
+ sp_out[sid] = mdl.SpecOverride(
170
+ _id_tuple(sd.get("serves"), mdl.INTENT_ID_RE),
171
+ _parse_metric_rules(sd.get("metrics"), rel, sid, diags),
172
+ )
173
+ ck_out: dict[str, mdl.CheckOverride] = {}
174
+ for cid, cd in _as_dict(raw.get("checks")).items():
175
+ if isinstance(cid, str) and mdl.CHECK_ID_RE.fullmatch(cid) and isinstance(cd, dict):
176
+ cf, ar, tr = str(cd.get("file") or "").strip(), cd.get("argv"), cd.get("timeout")
177
+ argv = tuple(str(x) for x in ar if str(x)) if isinstance(ar, list) and ar else None
178
+ if cf and argv is not None:
179
+ diags.append(
180
+ _err("FF001", f"{rel}: check '{cid}' cannot set both 'file' and 'argv'", rel, item=cid)
181
+ )
182
+ proves = _id_tuple(cd.get("proves"), mdl.SPEC_ID_RE)
183
+ mr = _parse_metric_rules(cd.get("metrics"), rel, cid, diags)
184
+ t_v = tr if type(tr) is int and 1 <= tr <= 3600 else None
185
+ ck_out[cid] = mdl.CheckOverride(cf, argv, proves, mr, t_v, bool(cd.get("serial", False)))
186
+ out[dom] = DomainCheckConfig(dom, str(raw.get("file") or "").strip(), sp_out, ck_out)
187
+ return out
188
+
189
+
190
+ def _strip_fences(lines: list[str]) -> list[tuple[int, str, bool]]:
191
+ out, fence = [], ""
192
+ for idx, line in enumerate(lines, start=1):
193
+ if m := _FENCE_RE.match(line):
194
+ tok = m.group(1)
195
+ if not fence or (tok[0] == fence[0] and len(tok) >= len(fence)):
196
+ fence = "" if fence else tok
197
+ out.append((idx, line, True))
198
+ continue
199
+ out.append((idx, line, bool(fence)))
200
+ return out
201
+
202
+
203
+ type _MdRow = tuple[str, str, tuple[str, ...], str, str, int, bool]
204
+ type _DCfgs = dict[str, DomainCheckConfig]
205
+ type _Disc = dict[str, tuple[str, str, int, str, str]]
206
+ type _SLinks = dict[str, tuple[tuple[str, ...], LinkSource, dict[str, MetricRule]]]
207
+
208
+
209
+ def _has_prose(seg: list[tuple[int, str, bool]]) -> bool:
210
+ return any(f or (s.strip() and not _HTML_COMMENT_RE.match(s)) for _, s, f in seg)
211
+
212
+
213
+ def _parse_markdown_items(fdir: Path, kind: str, diags: list[Diagnostic]) -> tuple[dict[str, _MdRow], set[str]]:
214
+ folder, items, file_doms = fdir / f"{kind}s", {}, set()
215
+ parents: dict[tuple[str, ...], tuple[str, int]] = {}
216
+ for entry in sorted(folder.iterdir()) if folder.is_dir() else ():
217
+ if entry.name.startswith("."):
218
+ continue
219
+ rel = f"{kind}s/{entry.name}"
220
+ if entry.is_dir() or entry.suffix != ".md":
221
+ msg = f"nested dirs forbidden; use {kind}s/<domain>.md" if entry.is_dir() else "expected '<domain>.md'"
222
+ diags.append(_err("FF002", f"{rel}: {msg}", rel, 1))
223
+ continue
224
+ dom = entry.stem
225
+ if valid_dom := bool(mdl.DOMAIN_RE.fullmatch(dom)):
226
+ file_doms.add(dom)
227
+ else:
228
+ diags.append(_err("FF002", f"{rel}: stem '{dom}' must match [a-z0-9-]+", rel, 1))
229
+ ann = _strip_fences(_read(fdir, rel).decode("utf-8").splitlines())
230
+ headings: list[tuple[int, int, str, int]] = []
231
+ for pos, (ln, line, in_fence) in enumerate(ann):
232
+ if in_fence:
233
+ continue
234
+ if _CHECKBOX_RE.match(line):
235
+ diags.append(_err("FF003", f"checkbox in {rel}:{ln} is forbidden", rel, ln, hint="drop '[ ]'/'[x]'"))
236
+ if m := _ATX_RE.match(line):
237
+ raw_t = m.group(2).strip()
238
+ if _ANCHOR_RE.search(raw_t):
239
+ diags.append(_err("FF003", f"anchor in {rel}:{ln} is forbidden", rel, ln, hint="drop '{...}'"))
240
+ raw_t = _ANCHOR_RE.sub("", raw_t).strip()
241
+ headings.append((pos, len(m.group(1)), raw_t, ln))
242
+ elif _ATTR_LINE_RE.match(line):
243
+ diags.append(_err("FF003", f"attr_list in {rel}:{ln} is forbidden", rel, ln, hint="drop '{...}'"))
244
+ if not headings:
245
+ diags.append(_err("FF002", f"{rel}: file contains no Markdown headings", rel, 1))
246
+ continue
247
+ first_pos, first_lvl, _, first_ln = headings[0]
248
+ if _has_prose(ann[:first_pos]):
249
+ diags.append(_err("FF002", f"{rel}: prose before first '#' heading is forbidden", rel, 1))
250
+ if first_lvl != 1:
251
+ diags.append(_err("FF002", f"{rel}:{first_ln}: file must start with '# {dom}'", rel, first_ln))
252
+ st_titles, st_slugs, prev_lvl = [], [], 0
253
+ for h_idx, (pos, lvl, title, ln) in enumerate(headings):
254
+ if prev_lvl and lvl > prev_lvl + 1:
255
+ diags.append(_err("FF002", f"{rel}:{ln}: heading jumps from H{prev_lvl} to H{lvl}", rel, ln))
256
+ prev_lvl = lvl
257
+ if not (slug := mdl.slugify_heading(title)):
258
+ diags.append(_err("FF002", f"{rel}:{ln}: heading '{title}' has no alphanumeric slug", rel, ln))
259
+ slug = "invalid"
260
+ if lvl == 1 and valid_dom and slug != dom:
261
+ m_t = f"{rel}:{ln}: top heading '# {title}' must match domain '{dom}'"
262
+ diags.append(_err("FF002", m_t, rel, ln))
263
+ st_titles, st_slugs = [*st_titles[: lvl - 1], title], [*st_slugs[: lvl - 1], slug]
264
+ nxt = headings[h_idx + 1][0] if h_idx + 1 < len(headings) else len(ann)
265
+ seg = ann[pos + 1 : nxt]
266
+ if h_idx + 1 < len(headings) and headings[h_idx + 1][1] > lvl:
267
+ parents.setdefault(tuple(st_slugs), (rel, ln))
268
+ if _has_prose(seg):
269
+ diags.append(_err("FF002", f"{rel}:{ln}: parent heading '{title}' has prose", rel, ln))
270
+ continue
271
+ if not (body := "\n".join(s for _, s, _ in seg).strip()):
272
+ diags.append(_err("FF002", f"{rel}:{ln}: leaf heading '{title}' has empty statement", rel, ln))
273
+ iid, unclear = f"{kind}_{'_'.join(st_slugs)}", any("[?]" in s for _, s, f in seg if not f)
274
+ if unclear:
275
+ diags.append(Diagnostic("FF009", "info", f"{iid} contains '[?]'", rel, ln, iid))
276
+ if iid in items:
277
+ m_dup = f"duplicate {kind} ID '{iid}' (first at {items[iid][4]}:{items[iid][5]})"
278
+ diags.append(_err("FF004", m_dup, rel, ln, iid))
279
+ continue
280
+ for depth in range(1, len(st_slugs)):
281
+ parents.setdefault(tuple(st_slugs[:depth]), (rel, ln))
282
+ items[iid] = (st_slugs[0], title, tuple(st_titles), body, rel, ln, unclear)
283
+ for iid, (_, _, _, _, rel, ln, _) in items.items():
284
+ if (k := tuple(iid.removeprefix(f"{kind}_").split("_"))) in parents:
285
+ pr, pl = parents[k]
286
+ diags.append(_err("FF004", f"leaf '{iid}' collides with parent heading at {pr}:{pl}", rel, ln, iid))
287
+ return items, file_doms
288
+
289
+
290
+ def _resolve_fdir_file(fdir: Path, rel_str: str) -> Path | None:
291
+ cand = fdir / rel_str
292
+ return None if cand.is_symlink() else (r if (r := cand.resolve()).is_relative_to(fdir) and r.is_file() else None)
293
+
294
+
295
+ def _discover_pytest_checks(fdir: Path, doms: set[str], dcfgs: _DCfgs, diags: list[Diagnostic]) -> _Disc:
296
+ found: dict[str, tuple[str, str, int, str, str]] = {}
297
+ for dom in sorted(doms):
298
+ dc, chk_p = dcfgs.get(dom), f"checks/{dom}.yaml"
299
+ if dc and dc.file:
300
+ if (res := _resolve_fdir_file(fdir, dc.file)) is None:
301
+ diags.append(_err("FF005", f"{chk_p}: pytest file '{dc.file}' not found", chk_p, 1))
302
+ continue
303
+ rel = res.relative_to(fdir).as_posix()
304
+ elif (fdir / (cand := f"tests/test_{dom.replace('-', '_')}.py")).is_file():
305
+ rel = cand
306
+ else:
307
+ continue
308
+ try:
309
+ tree = ast.parse(_read(fdir, rel).decode("utf-8"), filename=rel)
310
+ except SyntaxError as exc:
311
+ diags.append(_err("FF005", f"{rel}:{exc.lineno or 1}: syntax error ({exc.msg})", rel, exc.lineno or 1))
312
+ continue
313
+ for node in tree.body:
314
+ if not (isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name.startswith("test_")):
315
+ continue
316
+ cid, doc = node.name, (ast.get_docstring(node) or "").strip()
317
+ if not mdl.CHECK_ID_RE.fullmatch(cid):
318
+ diags.append(_err("FF005", f"{rel}:{node.lineno}: invalid check '{cid}'", rel, node.lineno, cid))
319
+ elif cid in found:
320
+ m = f"duplicate check '{cid}' (first at {found[cid][1]}:{found[cid][2]})"
321
+ diags.append(_err("FF004", m, rel, node.lineno, cid))
322
+ else:
323
+ found[cid] = (dom, rel, node.lineno, f"{rel}::{cid}", doc.splitlines()[0].strip() if doc else "")
324
+ return found
325
+
326
+
327
+ def _link_specs(
328
+ raw_int: dict[str, _MdRow], raw_spc: dict[str, _MdRow], dcfgs: _DCfgs, diags: list[Diagnostic]
329
+ ) -> tuple[_SLinks, dict[str, list[str]]]:
330
+ for dom, dc in sorted(dcfgs.items()):
331
+ p, msg = f"checks/{dom}.yaml", f"checks/{dom}.yaml configures unknown spec '{{}}'"
332
+ diags.extend(
333
+ _err("FF006", msg.format(s), p, item=s)
334
+ for s in sorted(dc.specs)
335
+ if s not in raw_spc or raw_spc[s][0] != dom
336
+ )
337
+ int_pfx = {tuple(iid.removeprefix("intent_").split("_")): iid for iid in raw_int}
338
+ spec_links: dict[str, tuple[tuple[str, ...], LinkSource, dict[str, MetricRule]]] = {}
339
+ int_specs: dict[str, list[str]] = {iid: [] for iid in raw_int}
340
+ for sid in sorted(raw_spc):
341
+ s_dom, _, _, _, p_rel, p_ln, _ = raw_spc[sid]
342
+ ov = dcfgs[s_dom].specs.get(sid) if s_dom in dcfgs else None
343
+ metrics = dict(ov.metrics) if ov else {}
344
+ if ov and ov.serves is not None:
345
+ serves_t, p = tuple(iid for iid in ov.serves if iid in raw_int), f"checks/{s_dom}.yaml"
346
+ diags.extend(
347
+ _err("FF006", f"spec '{sid}' serves unknown '{i}'", p, item=sid) for i in ov.serves if i not in raw_int
348
+ )
349
+ src: LinkSource = "override"
350
+ else:
351
+ segs = tuple(sid.removeprefix("spec_").split("_"))
352
+ matches = [iid for pfx, iid in int_pfx.items() if len(pfx) <= len(segs) and segs[: len(pfx)] == pfx]
353
+ serves_t = (max(matches, key=lambda x: len(x.split("_"))),) if matches else ()
354
+ src: LinkSource = "convention"
355
+ if not matches:
356
+ diags.append(_err("FF006", f"orphan spec '{sid}' matches no intent", p_rel, p_ln, sid, "set serves"))
357
+ spec_links[sid] = (serves_t, src, metrics)
358
+ for iid in serves_t:
359
+ int_specs[iid].append(sid)
360
+ return spec_links, int_specs
361
+
362
+
363
+ def _link_checks(
364
+ fdir: Path, cfg: mdl.Config, raw_spc: dict[str, _MdRow], dcfgs: _DCfgs, disc: _Disc, sp_l: _SLinks, dgs: list[Any]
365
+ ) -> tuple[dict[str, mdl.Check], dict[str, list[str]]]:
366
+ norm_specs: dict[str, list[str]] = {}
367
+ for sid in sorted(raw_spc):
368
+ norm_specs.setdefault(sid.removeprefix("spec_").replace("-", "_"), []).append(sid)
369
+ cfg_checks: dict[str, tuple[str, mdl.CheckOverride]] = {}
370
+ for dom, dc in sorted(dcfgs.items()):
371
+ for cid, cov in sorted(dc.checks.items()):
372
+ if cid in cfg_checks:
373
+ m = f"duplicate check '{cid}' across checks/{cfg_checks[cid][0]}.yaml and checks/{dom}.yaml"
374
+ dgs.append(_err("FF004", m, f"checks/{dom}.yaml", item=cid))
375
+ else:
376
+ cfg_checks[cid] = (dom, cov)
377
+ cm, spc_checks, runners = {}, {sid: [] for sid in raw_spc}, cfg.effective_runners()
378
+ for cid in sorted(set(disc) | set(cfg_checks)):
379
+ dc_e, cfg_p = disc.get(cid), cfg_checks.get(cid)
380
+ if dc_e and cfg_p and dc_e[0] != cfg_p[0]:
381
+ m = f"check '{cid}' in {dc_e[1]} collides with checks/{cfg_p[0]}.yaml"
382
+ dgs.append(_err("FF004", m, f"checks/{cfg_p[0]}.yaml", item=cid))
383
+ continue
384
+ dom = dc_e[0] if dc_e else (cfg_p[0] if cfg_p else "")
385
+ cov, chk_yaml, c_argv = cfg_p[1] if cfg_p else None, f"checks/{dom}.yaml", None
386
+ if cov and cov.argv is not None:
387
+ c_path, c_ln = dc_e[1:3] if dc_e else (chk_yaml, 1)
388
+ kind, c_argv, c_tgt = "argv", cov.argv, " ".join(cov.argv)
389
+ elif cov and cov.file and cov.argv is None:
390
+ if (resolved := _resolve_fdir_file(fdir, cov.file)) is None:
391
+ dgs.append(_err("FF007", f"{chk_yaml}: '{cid}' file '{cov.file}' invalid", chk_yaml, item=cid))
392
+ continue
393
+ if (ext := resolved.suffix.lower()) not in runners:
394
+ dgs.append(_err("FF007", f"{chk_yaml}: no runner for '{ext or resolved.name}'", chk_yaml, item=cid))
395
+ continue
396
+ rel_root = resolved.relative_to(fdir.parent).as_posix()
397
+ kind, c_argv = "runner", tuple(p.replace("{file}", rel_root) for p in runners[ext])
398
+ c_path, c_ln, c_tgt = resolved.relative_to(fdir).as_posix(), 1, rel_root
399
+ elif dc_e is not None:
400
+ kind, c_path, c_ln, c_tgt = "pytest", dc_e[1], dc_e[2], dc_e[3]
401
+ else:
402
+ m = f"check '{cid}' in {chk_yaml} missing pytest function and file/argv"
403
+ dgs.append(_err("FF007", m, chk_yaml, item=cid))
404
+ continue
405
+ if cov and cov.proves is not None:
406
+ proves_t, c_src = tuple(s for s in cov.proves if s in raw_spc and raw_spc[s][0] == dom), "override"
407
+ msg = f"check '{cid}' proves unknown '{{}}' in '{dom}'"
408
+ dgs.extend(_err("FF007", msg.format(s), chk_yaml, item=cid) for s in cov.proves if s not in proves_t)
409
+ else:
410
+ cands = [s for s in norm_specs.get(cid[5:].split("__", 1)[0], []) if raw_spc[s][0] == dom]
411
+ proves_t, c_src = ((cands[0],), "convention") if len(cands) == 1 else ((), "convention")
412
+ if len(cands) != 1:
413
+ m = f"check '{cid}' ambiguous ({', '.join(cands)})" if cands else f"unwired check '{cid}'"
414
+ dgs.append(_err("FF007", m, c_path, c_ln, cid, "set proves"))
415
+ for sid in proves_t:
416
+ spc_checks[sid].append(cid)
417
+ for mn, mr in cov.metrics.items() if cov else ():
418
+ sp_l[sid][2].setdefault(mn, mr)
419
+ t_out, doc_s = cov.timeout if (cov and cov.timeout is not None) else cfg.timeout, dc_e[4] if dc_e else ""
420
+ ser = bool(cov and cov.serial)
421
+ cm[cid] = mdl.Check(cid, dom, kind, c_path, c_ln, c_tgt, c_argv, proves_t, c_src, t_out, ser, doc_s)
422
+ return cm, spc_checks
423
+
424
+
425
+ def load_factory(factory_dir: Path, *, load_changes: bool = True) -> Factory:
426
+ """Parse and link `ff.yaml`, `<domain>` intents/specs/checks, tests, and changes under `factory_dir`."""
427
+ fdir, files = _scan_factory_files(factory_dir)
428
+ diags: list[Diagnostic] = []
429
+ cfg = _load_config(fdir, diags)
430
+ raw_int, int_doms = _parse_markdown_items(fdir, "intent", diags)
431
+ raw_spc, spc_doms = _parse_markdown_items(fdir, "spec", diags)
432
+ for d in sorted(spc_doms - int_doms):
433
+ p = f"specs/{d}.md"
434
+ diags.append(_err("FF006", f"{p} has no matching intents/{d}.md", p, 1, hint=f"add intents/{d}.md"))
435
+ dcfgs = _load_domain_checks(fdir, int_doms, diags)
436
+ disc = _discover_pytest_checks(fdir, int_doms | spc_doms | set(dcfgs), dcfgs, diags)
437
+ if not load_changes:
438
+ changes = {}
439
+ elif cfg.changes_source == "github":
440
+ changes = gitio.fetch_github_changes(fdir.parent, cfg.github_label)
441
+ else:
442
+ changes = gitio.parse_file_changes(fdir, diags)
443
+ spec_links, int_specs = _link_specs(raw_int, raw_spc, dcfgs, diags)
444
+ cm, spc_checks = _link_checks(fdir, cfg, raw_spc, dcfgs, disc, spec_links, diags)
445
+ im = {k: mdl.Intent(k, *v, tuple(sorted(int_specs[k]))) for k, v in sorted(raw_int.items())}
446
+ sm = {k: mdl.Spec(k, *v, *spec_links[k], tuple(sorted(spc_checks[k]))) for k, v in sorted(raw_spc.items())}
447
+ doms = tuple(sorted({x.domain for m in (im, sm, cm) for x in m.values()} | set(dcfgs)))
448
+ dom_files: dict[str, dict[str, str]] = {}
449
+ for dom in doms:
450
+ dc_f, d_py = dcfgs[dom].file if dom in dcfgs else "", f"tests/test_{dom.replace('-', '_')}.py"
451
+ d_cks = [ck for ck in cm.values() if ck.domain == dom]
452
+ cands = [f"intents/{dom}.md", f"specs/{dom}.md", f"checks/{dom}.yaml", dc_f, d_py]
453
+ if "tests/conftest.py" in files and any(ck.kind == "pytest" for ck in d_cks):
454
+ cands.append("tests/conftest.py")
455
+ cands.extend(ck.path for ck in d_cks if not ck.path.startswith("checks/"))
456
+ dom_files[dom] = {r: files[r] for r in sorted({"ff.yaml", *cands}) if r in files}
457
+ return Factory(fdir.parent, fdir, cfg.name, cfg, im, sm, cm, changes, doms, files, dom_files, tuple(diags))
ff/proofs.py ADDED
@@ -0,0 +1,178 @@
1
+ """Build, read, write, and verify unified per-domain `factory/proofs/<domain>.json` artifacts."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterable, Mapping
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from ff import models as m
10
+ from ff import schemas
11
+ from ff.models import CheckRecord, Error, Factory, IntentStatus, MetricRule, format_json
12
+
13
+ _DOM_ORDER: tuple[IntentStatus, ...] = ("ERROR", "FAILING", "UNCOVERED", "UNCLEAR", "UNPROVEN", "PARTIAL", "PROVEN")
14
+
15
+
16
+ def _m_entry(val: float | int | None, rule: MetricRule | None, passed: bool, check: str | None) -> dict[str, Any]:
17
+ lo, hi, unit = (rule.min, rule.max, rule.unit) if rule else (None, None, "")
18
+ return {"value": val, "min": lo, "max": hi, "unit": unit, "passed": passed, "check": check}
19
+
20
+
21
+ def _status_counts(entries: Iterable[Mapping[str, Any]]) -> dict[str, int]:
22
+ items = list(entries)
23
+ out: dict[str, int] = {"total": len(items)}
24
+ for v in items:
25
+ out[v["status"]] = out.get(v["status"], 0) + 1
26
+ return out
27
+
28
+
29
+ def build_proofs(factory: Factory, records: Mapping[str, CheckRecord]) -> dict[str, dict[str, Any]]:
30
+ """Compile file digests, check records, and evaluated spec/intent/domain verdicts."""
31
+ eval_specs: dict[str, dict[str, Any]] = {}
32
+ for sid, sp in sorted(factory.specs.items()):
33
+ spec_metrics: dict[str, Any] = {}
34
+ missing_metric = failed_metric = False
35
+ for mn, rule in sorted(sp.metrics.items()):
36
+ emitting = [(c, records[c].metrics[mn]) for c in sp.checks if c in records and mn in records[c].metrics]
37
+ if not emitting:
38
+ missing_metric = True
39
+ spec_metrics[mn] = _m_entry(None, rule, False, None)
40
+ else:
41
+ evaluated = [(cid, *rule.evaluate(raw)) for cid, raw in emitting]
42
+ failed = [item for item in evaluated if not item[2]]
43
+ chosen_cid, chosen_val, chosen_ok = failed[0] if failed else evaluated[0]
44
+ failed_metric = failed_metric or not chosen_ok
45
+ spec_metrics[mn] = _m_entry(chosen_val, rule, chosen_ok, chosen_cid)
46
+ for cid in sp.checks:
47
+ if rec := records.get(cid):
48
+ for mn, mval in sorted(rec.metrics.items()):
49
+ spec_metrics.setdefault(mn, _m_entry(mval, None, True, cid))
50
+
51
+ has_err = missing_metric or any(cid not in records or records[cid].status == "error" for cid in sp.checks)
52
+ has_fail = failed_metric or any(cid in records and records[cid].status == "fail" for cid in sp.checks)
53
+ sr = ((sp.unclear, "UNCLEAR"), (not sp.checks, "UNPROVEN"), (has_err, "ERROR"), (has_fail, "FAILING"))
54
+ d = {"id": sid, "title": sp.title, "status": next((st for c, st in sr if c), "PROVEN")}
55
+ sr_2 = {"serves": list(sp.serves), "checks": list(sp.checks), "metrics": dict(sorted(spec_metrics.items()))}
56
+ eval_specs[sid] = d | sr_2
57
+
58
+ eval_intents: dict[str, dict[str, Any]] = {}
59
+ for iid, it in sorted(factory.intents.items()):
60
+ linked = [eval_specs[sid] for sid in it.specs if sid in eval_specs]
61
+ pn, tn, ss = sum(1 for x in linked if x["status"] == "PROVEN"), len(linked), {x["status"] for x in linked}
62
+ st_i = "UNCLEAR" if it.unclear else ("UNCOVERED" if tn == 0 else "")
63
+ if not st_i:
64
+ ir = (("ERROR" in ss, "ERROR"), ("FAILING" in ss, "FAILING"), (pn == tn, "PROVEN"), (pn > 0, "PARTIAL"))
65
+ st_i = next((st for c, st in ir if c), "UNCLEAR" if "UNCLEAR" in ss else "UNPROVEN")
66
+ eval_intents[iid] = {
67
+ "id": iid,
68
+ "title": it.title,
69
+ "status": st_i,
70
+ "specs": list(it.specs),
71
+ "proven": pn,
72
+ "total": tn,
73
+ }
74
+
75
+ out: dict[str, dict[str, Any]] = {}
76
+ for dom in factory.domains:
77
+ d_files = dict(factory.domain_files.get(dom, {"ff.yaml": factory.files.get("ff.yaml", "")}))
78
+ dom_cks = [(c, ck) for c, ck in sorted(factory.checks.items()) if ck.domain == dom]
79
+ d_chks = {c: records[c].to_proof_entry() for c, _ in dom_cks if c in records}
80
+ chk_st = [{"status": records[c].status.upper() if c in records else "UNRUN"} for c, _ in dom_cks]
81
+ d_int = {iid: v for iid, v in eval_intents.items() if factory.intents[iid].domain == dom}
82
+ d_spc = {sid: v for sid, v in eval_specs.items() if factory.specs[sid].domain == dom}
83
+ obs = {v["status"] for v in d_int.values()} | {v["status"] for v in d_spc.values()}
84
+ d_st: IntentStatus = next((c for c in _DOM_ORDER if c in obs), "PROVEN")
85
+ sc = _status_counts
86
+ summ = {"intents": sc(d_int.values()), "specs": sc(d_spc.values()), "checks": sc(chk_st)}
87
+ dig = m.sha256_hex(m.encode_compact(d_files))
88
+ h = {"version": m.FORMAT, "domain": dom, "digest": dig, "files": d_files, "status": d_st, "summary": summ}
89
+ out[dom] = h | {"checks": d_chks, "intents": d_int, "specs": d_spc}
90
+ return out
91
+
92
+
93
+ def evaluate_gate(factory: Factory, proofs_by_domain: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
94
+ """Check evaluated intent and spec statuses against `config.fail_on`."""
95
+ fail_set = set(factory.config.fail_on)
96
+ ks = (("intent", "intents"), ("spec", "specs"))
97
+ blockers = [
98
+ {"id": iid, "kind": k, "domain": dom, "status": e["status"]}
99
+ for dom in sorted(proofs_by_domain)
100
+ for k, key in ks
101
+ for iid, e in sorted(proofs_by_domain[dom].get(key, {}).items())
102
+ if e["status"].lower() in fail_set
103
+ ]
104
+ return {"passed": not blockers, "fail_on": list(factory.config.fail_on), "blockers": blockers}
105
+
106
+
107
+ def read_proofs(factory_dir: Path) -> dict[str, dict[str, Any]]:
108
+ """Load and validate all `factory/proofs/*.json` domain documents."""
109
+ out: dict[str, dict[str, Any]] = {}
110
+ for path in sorted(pdir.glob("*.json")) if (pdir := factory_dir / "proofs").is_dir() else ():
111
+ doc = m.read_json_obj(path, f"proofs/{path.name}")
112
+ if errs := schemas.validate("proofs", doc, label=f"proofs/{path.name}"):
113
+ raise Error(errs[0])
114
+ if str(doc["domain"]) != path.stem:
115
+ raise Error(f"proofs/{path.name}: domain '{doc['domain']}' must match filename '{path.stem}'")
116
+ out[str(doc["domain"])] = doc
117
+ return out
118
+
119
+
120
+ def extract_records(dom_proofs: Mapping[str, Mapping[str, Any]]) -> dict[str, CheckRecord]:
121
+ """Extract normalized `CheckRecord` instances from saved domain proof documents."""
122
+ out: dict[str, CheckRecord] = {}
123
+ for dom in sorted(dom_proofs):
124
+ for cid, e in sorted(dom_proofs[dom].get("checks", {}).items()):
125
+ mc = {str(k): (v if type(v) is int else float(v)) for k, v in e["metrics"].items() if m.is_finite_number(v)}
126
+ out[cid] = CheckRecord(e["check"], e["status"], e["summary"], mc, tuple(e["evidence"]), tuple(e["proves"]))
127
+ return out
128
+
129
+
130
+ def check_proofs_fresh(factory: Factory, dom_proofs: Mapping[str, Mapping[str, Any]]) -> tuple[bool, list[str]]:
131
+ """Check whether saved `proofs/*.json` match current domain file SHA-256 digests."""
132
+ drifted: list[str] = []
133
+ for dom in factory.domains:
134
+ exp_files = factory.domain_files.get(dom, {})
135
+ if (doc := dom_proofs.get(dom)) is None:
136
+ drifted.append(f"proofs/{dom}.json")
137
+ continue
138
+ disk_files = doc.get("files", {})
139
+ changed = [p for p in sorted(set(exp_files) | set(disk_files)) if exp_files.get(p) != disk_files.get(p)]
140
+ drifted.extend(changed)
141
+ if doc.get("digest") != m.sha256_hex(m.encode_compact(exp_files)) and not changed:
142
+ drifted.append(f"proofs/{dom}.json")
143
+ drifted.extend(f"proofs/{extra}.json" for extra in sorted(set(dom_proofs) - set(factory.domains)))
144
+ return not (unique := sorted(set(drifted))), unique
145
+
146
+
147
+ def write_proofs(fdir: Path, prf_d: Mapping[str, Mapping[str, Any]], *, prune: bool = True) -> None:
148
+ """Atomically write `factory/proofs/<domain>.json`, optionally pruning removed domains."""
149
+ (pdir := fdir / "proofs").mkdir(parents=True, exist_ok=True)
150
+ for dom, doc in sorted(prf_d.items()):
151
+ m.atomic_write(pdir / f"{dom}.json", format_json(doc).encode("utf-8"))
152
+ if prune:
153
+ active = {f"{dom}.json" for dom in prf_d}
154
+ for existing in pdir.glob("*.json"):
155
+ if existing.name not in active:
156
+ existing.unlink()
157
+
158
+
159
+ def verify_proofs_match(fdir: Path, exp_p: Mapping[str, Mapping[str, Any]]) -> list[str]:
160
+ """Compare committed `proofs/*.json` against freshly computed domain proof documents."""
161
+ mismatches: list[str] = []
162
+ found = {p.stem: p for p in pdir.glob("*.json")} if (pdir := fdir / "proofs").is_dir() else {}
163
+ for dom, exp_doc in sorted(exp_p.items()):
164
+ rel = f"proofs/{dom}.json"
165
+ if (path := found.pop(dom, None)) is None:
166
+ mismatches.append(f"factory/{rel} is missing (hint: run 'ff run')")
167
+ continue
168
+ try:
169
+ disk_doc = m.read_json_obj(path, rel)
170
+ if errs := schemas.validate("proofs", disk_doc, label=rel):
171
+ mismatches.append(errs[0])
172
+ elif disk_doc != dict(exp_doc):
173
+ mismatches.append(f"factory/{rel} is stale or modified (hint: run 'ff run')")
174
+ except Error as exc:
175
+ mismatches.append(str(exc))
176
+ msg = "factory/proofs/{}.json belongs to a removed domain (hint: run 'ff run')"
177
+ mismatches.extend(msg.format(e) for e in sorted(found))
178
+ return mismatches
ff/py.typed ADDED
File without changes