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/query.py ADDED
@@ -0,0 +1,118 @@
1
+ """Offline read queries (`status`, `ls`, `show`) shared by the CLI and MCP server."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Sequence
6
+ from typing import Any
7
+
8
+ from ff import proofs
9
+ from ff.models import CheckRecord, Error, Factory, InputError
10
+
11
+
12
+ def load_saved_state(factory: Factory) -> tuple[dict[str, CheckRecord], dict[str, dict[str, Any]], bool, list[str]]:
13
+ """Return `(records, domain_proofs, proofs_fresh, drifted_files)` from disk without running checks."""
14
+ disk_proofs = proofs.read_proofs(factory.factory_dir)
15
+ proofs_fresh, drifted = proofs.check_proofs_fresh(factory, disk_proofs)
16
+ records = proofs.extract_records(disk_proofs)
17
+ return records, proofs.build_proofs(factory, records), proofs_fresh, drifted
18
+
19
+
20
+ def status_payload(factory: Factory) -> dict[str, Any]:
21
+ """Build the structured `ff status` report."""
22
+ records, dom_proofs, proofs_fresh, drifted = load_saved_state(factory)
23
+ gate = proofs.evaluate_gate(factory, dom_proofs)
24
+ i_cnt: dict[str, int] = {"total": len(factory.intents)}
25
+ s_cnt: dict[str, int] = {"total": len(factory.specs)}
26
+ c_cnt: dict[str, int] = {"total": len(factory.checks)}
27
+ attention: list[dict[str, str]] = []
28
+
29
+ for dom in factory.domains:
30
+ doc = dom_proofs[dom]
31
+ for kind, key, cnt in (("intent", "intents", i_cnt), ("spec", "specs", s_cnt)):
32
+ for item_id, entry in sorted(doc.get(key, {}).items()):
33
+ st = entry["status"]
34
+ cnt[st] = cnt.get(st, 0) + 1
35
+ if st != "PROVEN":
36
+ attention.append(
37
+ {"id": item_id, "kind": kind, "domain": dom, "status": st, "title": entry["title"]}
38
+ )
39
+
40
+ for cid in sorted(factory.checks):
41
+ rec = records.get(cid)
42
+ cst = rec.status.upper() if rec is not None else "UNRUN"
43
+ c_cnt[cst] = c_cnt.get(cst, 0) + 1
44
+
45
+ h = {"name": factory.name, "domains": list(factory.domains), "proofs_fresh": proofs_fresh, "drifted_files": drifted}
46
+ return h | {"gate": gate, "counts": {"intents": i_cnt, "specs": s_cnt, "checks": c_cnt}, "attention": attention}
47
+
48
+
49
+ def _row(
50
+ iid: str, kind: str, dom: str, st: str, title: str, path: str, line: int, links: Sequence[str], src: str = ""
51
+ ) -> dict[str, Any]:
52
+ head = {"id": iid, "kind": kind, "domain": dom, "status": st, "title": title, "path": path, "line": line}
53
+ return head | {"links": list(links)} | ({"link_source": src} if src else {})
54
+
55
+
56
+ def list_payload(
57
+ factory: Factory, *, kind: str = "", domain: str = "", status: str = "", limit: int = 0
58
+ ) -> dict[str, Any]:
59
+ """List intents, specs, checks, and/or changes with optional filters."""
60
+ records, dom_proofs, _, _ = load_saved_state(factory)
61
+ i_stat = {iid: iv["status"] for doc in dom_proofs.values() for iid, iv in doc.get("intents", {}).items()}
62
+ s_stat = {sid: sv["status"] for doc in dom_proofs.values() for sid, sv in doc.get("specs", {}).items()}
63
+ items: list[dict[str, Any]] = []
64
+ if kind in {"", "intent"}:
65
+ items.extend(
66
+ _row(i, "intent", it.domain, i_stat.get(i, "UNCOVERED"), it.title, it.path, it.line, it.specs)
67
+ for i, it in sorted(factory.intents.items())
68
+ )
69
+ if kind in {"", "spec"}:
70
+ items.extend(
71
+ _row(s, "spec", sp.domain, s_stat.get(s, "UNPROVEN"), sp.title, sp.path, sp.line, sp.serves, sp.link_source)
72
+ for s, sp in sorted(factory.specs.items())
73
+ )
74
+ if kind in {"", "check"}:
75
+ for cid, ck in sorted(factory.checks.items()):
76
+ rec = records.get(cid)
77
+ st, ttl = (rec.status.upper(), rec.summary) if rec else ("UNRUN", ck.doc or ck.target)
78
+ items.append(_row(cid, "check", ck.domain, st, ttl, ck.path, ck.line, ck.proves, ck.link_source))
79
+ if kind in {"", "change"}:
80
+ items.extend(
81
+ _row(cid, "change", "-", ch.state.upper(), ch.title, ch.path, 1, ch.touches)
82
+ for cid, ch in sorted(factory.changes.items())
83
+ )
84
+
85
+ if domain:
86
+ items = [it for it in items if it["domain"] == domain]
87
+ if status:
88
+ upper = status.strip().upper()
89
+ items = [it for it in items if it["status"].upper() == upper]
90
+ sliced = items[:limit] if limit > 0 else items
91
+ return {"count": len(sliced), "total": len(items), "items": sliced}
92
+
93
+
94
+ def show_payload(factory: Factory, item_id: str) -> dict[str, Any]:
95
+ """Return full structured details for one intent, spec, check, or change."""
96
+ target = item_id.strip()
97
+ if not target:
98
+ raise InputError("item ID must not be empty")
99
+ records, dom_proofs, _, _ = load_saved_state(factory)
100
+ if it := factory.intents.get(target):
101
+ iv = dom_proofs.get(it.domain, {}).get("intents", {}).get(target, {})
102
+ tail = {"proven": iv.get("proven", 0), "total": iv.get("total", len(it.specs))}
103
+ return it.to_dict() | {"kind": "intent", "status": iv.get("status", "UNCOVERED"), "body": it.body} | tail
104
+ if sp := factory.specs.get(target):
105
+ sv = dom_proofs.get(sp.domain, {}).get("specs", {}).get(target, {})
106
+ base = sp.to_dict()
107
+ tail = {"thresholds": base["metrics"], "metrics": sv.get("metrics", {})}
108
+ return base | {"kind": "spec", "status": sv.get("status", "UNPROVEN"), "body": sp.body} | tail
109
+ if ck := factory.checks.get(target):
110
+ rec = records.get(target)
111
+ st = rec.status.upper() if rec else "UNRUN"
112
+ mid = {"kind": "check", "check_kind": ck.kind, "line": ck.line, "status": st}
113
+ tail = {"summary": rec.summary if rec else ck.doc, "metrics": dict(rec.metrics) if rec else {}}
114
+ return ck.to_dict() | mid | tail | {"evidence": list(rec.evidence) if rec else []}
115
+ if ch := factory.changes.get(target):
116
+ tail = {"motivation": ch.motivation, "changes": ch.changes, "impact": ch.impact}
117
+ return ch.to_dict() | {"kind": "change", "title": ch.title} | tail
118
+ raise Error(f"unknown item ID '{target}'")
ff/runner.py ADDED
@@ -0,0 +1,239 @@
1
+ """Parallel `asyncio` check runner with `$FF_RECORD`, `$FF_ARTIFACTS`, sandboxed env, and pollution guard."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import contextlib
7
+ import json
8
+ import os
9
+ import shutil
10
+ import signal
11
+ import sys
12
+ import tempfile
13
+ from collections.abc import Mapping, Sequence
14
+ from dataclasses import dataclass
15
+ from pathlib import Path
16
+
17
+ from ff import gitio, schemas
18
+ from ff.models import Check, CheckRecord, Factory, RecordStatus, atomic_write, is_denied_env, is_finite_number
19
+
20
+ _ALLOW_1 = {"PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_ALL", "LC_CTYPE"}
21
+ _BASE_ENV_ALLOW = frozenset(_ALLOW_1 | {"TMPDIR", "TEMP", "TMP", "SYSTEMROOT", "TZ"})
22
+ _LOG_CAP_BYTES, _STREAM_DRAIN_SECONDS = 65536, 1.0
23
+ _SEVERITY_RANK: dict[RecordStatus, int] = {"pass": 0, "fail": 1, "error": 2}
24
+
25
+
26
+ @dataclass(frozen=True, slots=True)
27
+ class CheckRunOutcome:
28
+ record: CheckRecord
29
+ exit_code: int
30
+ log_path: str
31
+ error: str = ""
32
+
33
+
34
+ @dataclass(frozen=True, slots=True)
35
+ class RunSummary:
36
+ outcomes: dict[str, CheckRunOutcome]
37
+ workspace_polluted: bool
38
+ polluted_paths: tuple[str, ...]
39
+
40
+ @property
41
+ def all_passed(self) -> bool:
42
+ return not self.workspace_polluted and all(o.record.status == "pass" for o in self.outcomes.values())
43
+
44
+
45
+ def build_check_env(
46
+ check_id: str,
47
+ record_path: Path,
48
+ artifacts_dir: Path,
49
+ extra_names: Sequence[str],
50
+ source_env: Mapping[str, str] | None = None,
51
+ ) -> dict[str, str]:
52
+ """Construct an allowlisted subprocess environment with `$FF_CHECK`, `$FF_RECORD`, and `$FF_ARTIFACTS`."""
53
+ src = os.environ if source_env is None else source_env
54
+ allowed = _BASE_ENV_ALLOW | {name for name in extra_names if not is_denied_env(name)}
55
+ env = {k: v for k, v in src.items() if k in allowed and not is_denied_env(k)}
56
+ injected = {"FF_CHECK": check_id, "FF_RECORD": str(record_path), "FF_ARTIFACTS": str(artifacts_dir)}
57
+ return env | injected | {"PYTHONDONTWRITEBYTECODE": "1"}
58
+
59
+
60
+ def build_check_argv(check: Check, factory: Factory) -> list[str]:
61
+ """Resolve literal `argv` for `argv`, extension `runner`, or discovered `pytest` checks."""
62
+ if check.kind in {"argv", "runner"} and check.argv is not None:
63
+ is_py = check.kind == "runner" and check.argv[0] == "python3"
64
+ return [shutil.which("python3") or sys.executable if is_py else check.argv[0], *check.argv[1:]]
65
+ pytest_cmd = list(factory.config.pytest_argv)
66
+ if pytest_cmd[0] == "pytest":
67
+ sib = Path(sys.executable).with_name("pytest")
68
+ exe = shutil.which("pytest") or (str(sib) if sib.is_file() else "")
69
+ pytest_cmd = [exe, *pytest_cmd[1:]] if exe else [sys.executable, "-m", "pytest", *pytest_cmd[1:]]
70
+ py_file, root_r = (factory.factory_dir / check.path).resolve(), factory.root.resolve()
71
+ rel_py = py_file.relative_to(root_r).as_posix() if py_file.is_relative_to(root_r) else str(py_file)
72
+ return [*pytest_cmd, "-q", "--tb=short", "-p", "no:cacheprovider", "-o", "addopts=", f"{rel_py}::{check.id}"]
73
+
74
+
75
+ async def _drain_stream(stream: asyncio.StreamReader | None, buf: bytearray) -> None:
76
+ if stream is not None:
77
+ while chunk := await stream.read(8192):
78
+ buf.extend(chunk)
79
+
80
+
81
+ async def _terminate_group(proc: asyncio.subprocess.Process) -> None:
82
+ if proc.returncode is not None:
83
+ return
84
+ for sig in (signal.SIGTERM, signal.SIGKILL):
85
+ with contextlib.suppress(ProcessLookupError, PermissionError):
86
+ os.killpg(proc.pid, sig)
87
+ try:
88
+ await asyncio.wait_for(proc.wait(), timeout=0.5)
89
+ return
90
+ except TimeoutError:
91
+ continue
92
+ with contextlib.suppress(ProcessLookupError):
93
+ await proc.wait()
94
+
95
+
96
+ def _cap_log(raw: bytes) -> bytes:
97
+ if len(raw) <= _LOG_CAP_BYTES:
98
+ return raw
99
+ text = raw.decode("utf-8", errors="replace").encode()
100
+ marker = f"\n...[truncated {len(text) - _LOG_CAP_BYTES} bytes]...\n".encode()
101
+ budget = max(0, _LOG_CAP_BYTES - len(marker))
102
+ half = budget // 2
103
+ return text[:half] + marker + text[-(budget - half) :]
104
+
105
+
106
+ def exit_to_status(code: int) -> tuple[RecordStatus, str]:
107
+ if code in (0, 1):
108
+ return ("pass", "") if code == 0 else ("fail", "check exited with code 1")
109
+ return "error", f"check killed by signal {-code}" if code < 0 else f"check exited with code {code}"
110
+
111
+
112
+ def _err_rec(
113
+ check: Check, err: str, metrics: dict[str, float | int] | None = None, ev: tuple[str, ...] = ()
114
+ ) -> tuple[CheckRecord, str]:
115
+ return CheckRecord(check.id, "error", err, metrics or {}, ev, check.proves), err
116
+
117
+
118
+ def reconcile_record(
119
+ check: Check, factory: Factory, record_path: Path, exit_status: RecordStatus, exit_reason: str
120
+ ) -> tuple[CheckRecord, str]:
121
+ """Validate `$FF_RECORD` if emitted, reconcile conservatively with exit code, and enforce metric rules."""
122
+ merged, raw_metrics, evidence = exit_status, {}, ()
123
+ summary = exit_reason or check.doc or f"{check.id} {exit_status}"
124
+ if record_path.is_file():
125
+ try:
126
+ raw_obj = json.loads(record_path.read_text(encoding="utf-8"))
127
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
128
+ return _err_rec(check, f"invalid $FF_RECORD JSON: {exc}")
129
+ if schema_errs := schemas.validate("record", raw_obj, label="$FF_RECORD"):
130
+ return _err_rec(check, schema_errs[0])
131
+ if (rec_cid := raw_obj.get("check", check.id)) != check.id:
132
+ return _err_rec(check, f"$FF_RECORD check '{rec_cid}' != '{check.id}'")
133
+ rec_st: RecordStatus = raw_obj["status"] if raw_obj.get("status") in _SEVERITY_RANK else exit_status
134
+ merged = exit_status if _SEVERITY_RANK[exit_status] >= _SEVERITY_RANK[rec_st] else rec_st
135
+ summary = str(raw_obj.get("summary") or "").strip() or exit_reason or check.doc or f"{check.id} {merged}"
136
+ for k, v in (raw_obj.get("metrics") or {}).items():
137
+ if not is_finite_number(v):
138
+ return _err_rec(check, f"metric '{k}' must be a finite number")
139
+ raw_metrics[str(k)] = v if isinstance(v, int) else float(v)
140
+ evidence = tuple(str(item) for item in (raw_obj.get("evidence") or ()))
141
+
142
+ rounded, bound_failures = dict(raw_metrics), []
143
+ for sid in check.proves:
144
+ if sp := factory.specs.get(sid):
145
+ for mname, rule in sorted(sp.metrics.items()):
146
+ if mname not in raw_metrics:
147
+ if len(sp.checks) == 1 and merged == "pass":
148
+ return _err_rec(check, f"missing required metric '{mname}' for {sid}", rounded, evidence)
149
+ else:
150
+ rounded[mname], ok = rule.evaluate(raw_metrics[mname])
151
+ if not ok:
152
+ bound_failures.append(f"{mname}={rounded[mname]} outside [{rule.min}, {rule.max}]")
153
+ error_msg = exit_reason if merged != "pass" else ""
154
+ if bound_failures and merged == "pass":
155
+ merged, error_msg = "fail", "; ".join(bound_failures)
156
+ summary = f"{summary} ({error_msg})"
157
+ elif merged == "error" and not error_msg:
158
+ error_msg = summary
159
+ return CheckRecord(check.id, merged, summary, dict(sorted(rounded.items())), evidence, check.proves), error_msg
160
+
161
+
162
+ async def _run_one(check: Check, factory: Factory) -> CheckRunOutcome:
163
+ log_rel = f".ff/logs/{check.id}.log"
164
+ buf = bytearray()
165
+ exit_code = -1
166
+
167
+ with tempfile.TemporaryDirectory(prefix=f"ff-{check.id}-") as tmp:
168
+ tmp_path = Path(tmp)
169
+ (artifacts_dir := tmp_path / "artifacts").mkdir(parents=True, exist_ok=True)
170
+ record_path = tmp_path / "record.json"
171
+ argv = build_check_argv(check, factory)
172
+ env = build_check_env(check.id, record_path, artifacts_dir, factory.config.env)
173
+ proc: asyncio.subprocess.Process | None = None
174
+ read_task: asyncio.Task[None] | None = None
175
+ try:
176
+ pipe, out_s = asyncio.subprocess.PIPE, asyncio.subprocess.STDOUT
177
+ proc = await asyncio.create_subprocess_exec(
178
+ *argv, cwd=factory.root, env=env, stdout=pipe, stderr=out_s, start_new_session=True
179
+ )
180
+ read_task = asyncio.create_task(_drain_stream(proc.stdout, buf))
181
+ await asyncio.wait_for(proc.wait(), timeout=check.timeout)
182
+ exit_code = proc.returncode if proc.returncode is not None else -1
183
+ exit_status, exit_reason = exit_to_status(exit_code)
184
+ except TimeoutError:
185
+ if proc is not None:
186
+ await _terminate_group(proc)
187
+ exit_code, exit_status, exit_reason = 124, "error", f"check timed out after {check.timeout}s"
188
+ except OSError as exc:
189
+ exit_code, exit_status, exit_reason = 127, "error", f"failed to start {argv[0]!r}: {exc}"
190
+ except asyncio.CancelledError:
191
+ if proc is not None and proc.returncode is None:
192
+ with contextlib.suppress(ProcessLookupError, PermissionError, TimeoutError):
193
+ os.killpg(proc.pid, signal.SIGKILL)
194
+ await asyncio.wait_for(proc.wait(), timeout=0.5)
195
+ raise
196
+ finally:
197
+ if read_task is not None:
198
+ with contextlib.suppress(TimeoutError, asyncio.CancelledError):
199
+ await asyncio.wait_for(asyncio.shield(read_task), timeout=_STREAM_DRAIN_SECONDS)
200
+ if not read_task.done():
201
+ read_task.cancel()
202
+ with contextlib.suppress(asyncio.CancelledError):
203
+ await read_task
204
+ getattr(proc, "_transport", asyncio.BaseTransport()).close()
205
+ await asyncio.sleep(0)
206
+ rec, err_msg = await asyncio.to_thread(reconcile_record, check, factory, record_path, exit_status, exit_reason)
207
+
208
+ raw_log = _cap_log(bytes(buf)) or ((err_msg + "\n").encode() if err_msg else b"")
209
+ await asyncio.to_thread(atomic_write, factory.root / log_rel, raw_log)
210
+ return CheckRunOutcome(record=rec, exit_code=exit_code, log_path=log_rel, error=err_msg)
211
+
212
+
213
+ async def execute_checks_async(
214
+ factory: Factory, check_ids: Sequence[str] | None = None, *, jobs: int = 0
215
+ ) -> RunSummary:
216
+ """Execute selected checks concurrently (parallel batch + serial checks) with pollution detection."""
217
+ selected = [factory.checks[cid] for cid in (check_ids if check_ids is not None else sorted(factory.checks))]
218
+ max_jobs = jobs if jobs > 0 else (factory.config.jobs if factory.config.jobs > 0 else min(os.cpu_count() or 4, 8))
219
+ sem = asyncio.Semaphore(max(1, max_jobs))
220
+ before_dirty = await asyncio.to_thread(gitio.workspace_status_paths, factory.root)
221
+ parallel, serial = [ck for ck in selected if not ck.serial], [ck for ck in selected if ck.serial]
222
+
223
+ async def _bounded(ck: Check) -> tuple[str, CheckRunOutcome]:
224
+ async with sem:
225
+ return ck.id, await _run_one(ck, factory)
226
+
227
+ outcomes = dict(await asyncio.gather(*(_bounded(ck) for ck in parallel))) if parallel else {}
228
+ for ck in serial:
229
+ outcomes[ck.id] = await _run_one(ck, factory)
230
+
231
+ after_dirty = await asyncio.to_thread(gitio.workspace_status_paths, factory.root)
232
+ diff = (after_dirty - before_dirty) if (before_dirty is not None and after_dirty is not None) else set()
233
+ polluted = sorted(p for p in diff if not p.startswith(".ff/"))
234
+ return RunSummary(dict(sorted(outcomes.items())), bool(polluted), tuple(polluted))
235
+
236
+
237
+ def run_checks(factory: Factory, check_ids: Sequence[str] | None = None, *, jobs: int = 0) -> RunSummary:
238
+ """Synchronous wrapper around `execute_checks_async`."""
239
+ return asyncio.run(execute_checks_async(factory, check_ids, jobs=jobs))
ff/scaffold.py ADDED
@@ -0,0 +1,239 @@
1
+ """Scaffold `factory/` (`ff init`), install `/ff` skill, and emit hook/CI snippets."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from importlib import resources
6
+ from importlib.resources.abc import Traversable
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ from ff import __version__
11
+ from ff.models import InputError, atomic_write, sha256_hex, slugify_heading
12
+
13
+ CONFTEST_PY = '''"""Pure-stdlib pytest plugin emitting $FF_RECORD for Factory Framework (zero ff import)."""
14
+
15
+ from __future__ import annotations
16
+
17
+ import json
18
+ import math
19
+ import os
20
+ from pathlib import Path
21
+ from typing import Any
22
+
23
+ import pytest
24
+
25
+
26
+ class Recorder:
27
+ """Collect summary, metrics, and evidence inside a check."""
28
+
29
+ def __init__(self) -> None:
30
+ self.summary_text, self.metrics_map, self.evidence_list = "", {}, []
31
+
32
+ def __call__(
33
+ self, summary: str = "", *, metrics: dict[str, float | int] | None = None, evidence: list[str] | None = None
34
+ ) -> None:
35
+ if summary:
36
+ self.summary(summary)
37
+ for k, v in (metrics or {}).items():
38
+ self.metric(k, v)
39
+ self.evidence(*(evidence or ()))
40
+
41
+ def summary(self, text: str) -> None:
42
+ self.summary_text = text.strip()
43
+
44
+ def metric(self, name: str, value: float | int) -> None:
45
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(float(value)):
46
+ raise ValueError(f"metric {name!r} must be a finite int or float")
47
+ self.metrics_map[str(name)] = value
48
+
49
+ def evidence(self, *items: str) -> None:
50
+ self.evidence_list.extend(str(item) for item in items)
51
+
52
+
53
+ _STATE: dict[str, Any] = {}
54
+
55
+
56
+ def _st(*, reset: bool = False) -> dict[str, Any]:
57
+ if reset or "rec" not in _STATE:
58
+ _STATE.clear()
59
+ _STATE.update({"rec": Recorder(), "doc": "", "passed": 0, "failed": 0, "skipped": 0, "errors": 0, "msg": ""})
60
+ return _STATE
61
+
62
+
63
+ def pytest_sessionstart(session: pytest.Session) -> None:
64
+ del session
65
+ _st(reset=True)
66
+
67
+
68
+ @pytest.fixture
69
+ def ff_record() -> Recorder:
70
+ return _st()["rec"]
71
+
72
+
73
+ def pytest_runtest_setup(item: pytest.Item) -> None:
74
+ doc = (getattr(getattr(item, "obj", None), "__doc__", None) or "").strip()
75
+ _st()["doc"] = doc.splitlines()[0].strip() if doc else ""
76
+
77
+
78
+ def pytest_runtest_logreport(report: pytest.TestReport) -> None:
79
+ st = _st()
80
+ if report.when == "call":
81
+ for k, v in getattr(report, "user_properties", ()):
82
+ if not isinstance(v, bool) and isinstance(v, (int, float)) and math.isfinite(float(v)):
83
+ st["rec"].metrics_map.setdefault(str(k), v)
84
+ key = "passed" if report.passed else ("failed" if report.failed else ("skipped" if report.skipped else ""))
85
+ if key:
86
+ st[key] += 1
87
+ elif report.failed or report.skipped:
88
+ st["errors" if report.failed else "skipped"] += 1
89
+ if report.failed and (lines := str(report.longreprtext).strip().splitlines()):
90
+ st["msg"] = lines[-1][:240]
91
+
92
+
93
+ def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
94
+ if not (record_path := os.environ.get("FF_RECORD")) or "rec" not in _STATE:
95
+ return
96
+ st, rec = _STATE, _STATE["rec"]
97
+ first = session.items[0] if session.items else None
98
+ raw_id = (getattr(first, "originalname", None) or first.name) if first else "test_unknown"
99
+ check_id = os.environ.get("FF_CHECK") or raw_id
100
+ if st["errors"] > 0 or st["skipped"] > 0 or (st["passed"] == 0 and st["failed"] == 0):
101
+ status, fb = "error", st["msg"] or ("check was skipped" if st["skipped"] else f"pytest exit {exitstatus}")
102
+ elif st["failed"] > 0 or exitstatus != 0:
103
+ status, fb = "fail", st["msg"] or "assertion failed"
104
+ else:
105
+ status, fb = "pass", st["doc"] or f"{check_id} passed"
106
+ payload = {
107
+ "check": check_id,
108
+ "evidence": rec.evidence_list,
109
+ "metrics": rec.metrics_map,
110
+ "status": status,
111
+ "summary": rec.summary_text or fb,
112
+ }
113
+ out = Path(record_path)
114
+ out.parent.mkdir(parents=True, exist_ok=True)
115
+ out.write_text(json.dumps(payload, ensure_ascii=False, allow_nan=False, sort_keys=True) + "\\n", encoding="utf-8")
116
+ '''
117
+
118
+ _EXAMPLE_INTENT = "# Hello\n\n## Greeting\n\nAs a caller, I want a clear welcome greeting, so that I can confirm the service is responsive.\n"
119
+ _EXAMPLE_SPEC = "# Hello\n\n## Greeting\n\n### Message\n\nGiven a caller requests a greeting, when the greeting is built, THE SYSTEM SHALL return a message starting with `Hello` of at least 5 characters.\n"
120
+ _EXAMPLE_CHECKS_SCRIPT = "version: 1\ndomain: hello\nchecks:\n test_hello_greeting_message:\n file: tests/check_hello.py\n metrics:\n greeting_len: { min: 5, precision: 0, unit: chars }\n"
121
+ _EXAMPLE_CHECKS_PYTEST = "version: 1\ndomain: hello\nspecs:\n spec_hello_greeting_message:\n metrics:\n greeting_len: { min: 5, precision: 0, unit: chars }\n"
122
+ _EXAMPLE_SCRIPT = '''"""Starter polyglot check for the hello domain (zero pytest dependency)."""
123
+
124
+ from __future__ import annotations
125
+
126
+ import json
127
+ import os
128
+ from pathlib import Path
129
+
130
+ msg = "Hello, Factory Framework!"
131
+ assert msg.startswith("Hello")
132
+ if record_path := os.environ.get("FF_RECORD"):
133
+ rec = {"summary": "Verified welcome greeting starts with Hello", "metrics": {"greeting_len": len(msg)}}
134
+ Path(record_path).write_text(json.dumps(rec | {"evidence": [f"message={msg}"]}), encoding="utf-8")
135
+ '''
136
+ _EXAMPLE_PYTEST = '''"""Starter pytest behavioral check for the hello domain."""
137
+
138
+ from __future__ import annotations
139
+
140
+ from typing import Any
141
+
142
+
143
+ def test_hello_greeting_message(ff_record: Any) -> None:
144
+ """Verify welcome message length and content."""
145
+ msg = "Hello, Factory Framework!"
146
+ assert msg.startswith("Hello")
147
+ ff_record(
148
+ "Verified welcome greeting starts with Hello",
149
+ metrics={"greeting_len": len(msg)},
150
+ evidence=[f"message={msg}"],
151
+ )
152
+ '''
153
+
154
+
155
+ def init_factory(root_dir: Path, *, example: bool = False, pytest_plugin: bool = False) -> dict[str, Any]:
156
+ """Scaffold `factory/` non-destructively inside `root_dir`."""
157
+ root = root_dir.resolve()
158
+ fdir, created = root / "factory", []
159
+ for sub in ("intents", "specs", "checks", "tests", "changes", "proofs"):
160
+ (fdir / sub).mkdir(parents=True, exist_ok=True)
161
+ co = "# Review contract intent, check, test, and configuration edits\n# /factory/intents/ @org/owners\n# /factory/checks/ @org/owners\n# /factory/tests/ @org/owners\n# /factory/ff.yaml @org/owners\n"
162
+ ff_cfg = f"# Factory Framework configuration\nversion: 1\nname: {slugify_heading(root.name) or 'project'}\n"
163
+ seed = [("factory/ff.yaml", ff_cfg), (".github/CODEOWNERS", co)]
164
+ if pytest_plugin:
165
+ seed.append(("factory/tests/conftest.py", CONFTEST_PY))
166
+ if example:
167
+ t_fn, t_src = ("test_hello.py", _EXAMPLE_PYTEST) if pytest_plugin else ("check_hello.py", _EXAMPLE_SCRIPT)
168
+ c_src = _EXAMPLE_CHECKS_PYTEST if pytest_plugin else _EXAMPLE_CHECKS_SCRIPT
169
+ pairs = [("intents/hello.md", _EXAMPLE_INTENT), ("specs/hello.md", _EXAMPLE_SPEC)]
170
+ pairs += [("checks/hello.yaml", c_src), (f"tests/{t_fn}", t_src)]
171
+ seed.extend((f"factory/{k}", v) for k, v in pairs)
172
+ for label, content in seed:
173
+ if not (dest := root / label).exists():
174
+ atomic_write(dest, content.encode())
175
+ created.append(label)
176
+ gi = root / ".gitignore"
177
+ ex_gi = gi.read_text(encoding="utf-8") if gi.is_file() else ""
178
+ if ".ff/" not in ex_gi.splitlines() and "/.ff/" not in ex_gi.splitlines():
179
+ atomic_write(gi, (ex_gi + ("" if (not ex_gi or ex_gi.endswith("\n")) else "\n") + ".ff/\n").encode())
180
+ created.append(".gitignore")
181
+ return {"ok": True, "factory": str(fdir), "created": created}
182
+
183
+
184
+ def _walk_traversable(node: Traversable, prefix: str = "") -> dict[str, bytes]:
185
+ out: dict[str, bytes] = {}
186
+ for child in sorted(node.iterdir(), key=lambda c: c.name):
187
+ if not child.name.startswith(".") and child.name != "__pycache__":
188
+ rel = f"{prefix}/{child.name}" if prefix else child.name
189
+ out.update(_walk_traversable(child, rel)) if child.is_dir() else out.__setitem__(rel, child.read_bytes())
190
+ return out
191
+
192
+
193
+ def install_skill(dest_dir: Path, *, check: bool = False) -> dict[str, Any]:
194
+ """Install or verify packaged `src/ff/skill/` into `<dest_dir>/ff/`."""
195
+ packaged, target = _walk_traversable(resources.files("ff").joinpath("skill")), dest_dir.resolve() / "ff"
196
+ if not check:
197
+ target.mkdir(parents=True, exist_ok=True)
198
+ for rel, data in sorted(packaged.items()):
199
+ atomic_write(target / rel, data)
200
+ for ex in sorted(target.rglob("*"), reverse=True):
201
+ if ex.is_file() and ex.relative_to(target).as_posix() not in packaged:
202
+ ex.unlink()
203
+ return {"ok": True, "target": str(target), "files": sorted(packaged)}
204
+ found = {p.relative_to(target).as_posix(): p for p in target.rglob("*") if p.is_file()} if target.is_dir() else {}
205
+ diffs: list[str] = []
206
+ for rel, data in sorted(packaged.items()):
207
+ if (d := found.pop(rel, None)) is None or sha256_hex(d.read_bytes()) != sha256_hex(data):
208
+ diffs.append(f"{'missing' if d is None else 'modified'}: {rel}")
209
+ all_d = [*diffs, *(f"extra: {e}" for e in sorted(found))]
210
+ return {"ok": not all_d, "target": str(target), "differences": all_d}
211
+
212
+
213
+ _HOOKS: dict[str, str] = {
214
+ "pre-commit": (
215
+ "repos:\n - repo: https://github.com/fmind/factory-framework\n rev: v__VER__\n hooks:\n"
216
+ " - id: ff-lint\n stages: [pre-commit]\n - id: ff-verify\n stages: [pre-push]\n"
217
+ ),
218
+ "lefthook": (
219
+ "pre-commit:\n jobs:\n - name: ff-lint\n run: uv run --locked ff lint\n"
220
+ "pre-push:\n jobs:\n - name: ff-verify\n run: uv run --locked ff verify --base origin/main --strict\n"
221
+ ),
222
+ "github-actions": (
223
+ "name: Factory Verify\non:\n push:\n branches: [main]\n pull_request:\npermissions:\n contents: read\n"
224
+ "jobs:\n verify:\n runs-on: ubuntu-26.04\n steps:\n"
225
+ " - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1\n with:\n fetch-depth: 0\n persist-credentials: false\n"
226
+ " - uses: astral-sh/setup-uv@a6eb1ab5522f2fc5c4be2f2a0808866c8e4d7ab2 # v7.6.0\n"
227
+ ' - name: Verify factory contract\n run: uvx --from "factory-framework==__VER__" ff verify --strict\n'
228
+ " - name: Check pull request against base branch\n if: ${{ github.event_name == 'pull_request' }}\n"
229
+ ' env:\n BASE_SHA: ${{ github.event.pull_request.base.sha }}\n run: uvx --from "factory-framework==__VER__" ff lint --base "$BASE_SHA" --strict\n'
230
+ ' - name: Write proof summary\n run: uvx --from "factory-framework==__VER__" ff export --format md --output "$GITHUB_STEP_SUMMARY"\n'
231
+ ),
232
+ }
233
+
234
+
235
+ def render_hook(tool: str) -> str:
236
+ """Emit ready-to-paste `pre-commit`, `lefthook`, or `github-actions` integration snippets."""
237
+ if (tmpl := _HOOKS.get(tool.strip().lower())) is None:
238
+ raise InputError(f"unknown hook target '{tool}'; choose pre-commit, lefthook, or github-actions")
239
+ return tmpl.replace("__VER__", __version__)