factory-framework 0.3.1__tar.gz → 0.4.0__tar.gz

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.
Files changed (30) hide show
  1. {factory_framework-0.3.1 → factory_framework-0.4.0}/PKG-INFO +32 -34
  2. factory_framework-0.4.0/README.md +167 -0
  3. {factory_framework-0.3.1 → factory_framework-0.4.0}/pyproject.toml +4 -1
  4. {factory_framework-0.3.1 → factory_framework-0.4.0}/pyproject.toml.orig +4 -1
  5. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/__init__.py +4 -2
  6. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/cli.py +5 -2
  7. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/export.py +5 -2
  8. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/gitio.py +17 -65
  9. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/lint.py +105 -54
  10. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/models.py +42 -17
  11. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/parse.py +22 -28
  12. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/proofs.py +6 -6
  13. factory_framework-0.4.0/src/ff/pytest_plugin.py +85 -0
  14. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/query.py +1 -1
  15. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/runner.py +68 -12
  16. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/scaffold.py +5 -119
  17. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/schemas.py +7 -9
  18. factory_framework-0.4.0/src/ff/skill/SKILL.md +47 -0
  19. factory_framework-0.4.0/src/ff/skill/references/authoring.md +54 -0
  20. factory_framework-0.4.0/src/ff/skill/references/checks.md +68 -0
  21. factory_framework-0.4.0/src/ff/skill/references/workflow.md +65 -0
  22. factory_framework-0.3.1/README.md +0 -169
  23. factory_framework-0.3.1/src/ff/skill/SKILL.md +0 -47
  24. factory_framework-0.3.1/src/ff/skill/references/authoring.md +0 -59
  25. factory_framework-0.3.1/src/ff/skill/references/checks.md +0 -69
  26. factory_framework-0.3.1/src/ff/skill/references/workflow.md +0 -55
  27. {factory_framework-0.3.1 → factory_framework-0.4.0}/LICENSE +0 -0
  28. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/__main__.py +0 -0
  29. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/mcp.py +0 -0
  30. {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: factory-framework
3
- Version: 0.3.1
3
+ Version: 0.4.0
4
4
  Summary: Factory Framework (ff) links human intents and specs to parallel executable checks, records validated metrics, and exports stakeholder-ready proofs.
5
5
  Keywords: ai,ai-agents,agent-skills,agents-md,fitness-functions,local-first,mcp,model-context-protocol,python,software-engineering,software-factory,spec-driven-development,traceability
6
6
  Author: Médéric Hurier
@@ -49,20 +49,20 @@ Description-Content-Type: text/markdown
49
49
 
50
50
  [![CI](https://github.com/fmind/factory-framework/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-174EA6)](pyproject.toml) [![License: MIT](https://img.shields.io/badge/license-MIT-174EA6)](LICENSE)
51
51
 
52
- Factory Framework (`ff`) connects human product goals to automated tests in plain files inside your repository. Product owners, engineers, and AI coding agents work from one source of truth, and proof reports come from real executions — never manual checkboxes.
52
+ Factory Framework (`ff`) links plain-Markdown human goals directly to executable tests inside your repository. Stakeholders, engineers, and AI coding agents read the exact same contract, and verdicts come solely from executed checks — never manual checkboxes.
53
53
 
54
54
  [Overview](#overview) · [Benefits](#benefits) · [Installation](#installation) · [Usage](#usage) · [Example](#example) · [Documentation](#documentation)
55
55
 
56
56
  ## Overview
57
57
 
58
- Teams lose alignment when requirements live in wikis, tests check implementation details instead of user outcomes, and nobody knows what is truly proven.
58
+ Requirements rot in external wikis when tests verify implementation trivia instead of user outcomes and releases ship on guesswork.
59
59
 
60
- `ff` organizes every domain inside `factory/` with 1-to-1 file symmetry:
60
+ `ff` organizes every domain inside `factory/` using implicit `<domain>` filenames:
61
61
 
62
- - **Intents** (`intents/<domain>.md`) capture **why** a capability matters for humans (User Stories recommended).
63
- - **Specs** (`specs/<domain>.md`) define **what** the system guarantees (Given/When/Then or EARS recommended).
64
- - **Checks** (`checks/<domain>.yaml` + `tests/*`) map specs and numeric bounds to real tests in any language.
65
- - **Proofs** (`proofs/<domain>.json`) record digests, measured metrics, evidence, and computed `PROVEN`, `FAILING`, `UNPROVEN`, `UNCLEAR`, or `ERROR` verdicts.
62
+ - **Intents** (`intents/<domain>.md`) state **why** a capability matters for humans (User Stories recommended).
63
+ - **Specs** (`specs/<domain>.md`) define **what** the system guarantees (Given/When/Then or EARS recommended, with optional parent overview prose).
64
+ - **Checks** (`tests/*` + optional `checks/<domain>.yaml`) run real behavioral tests in any language and enforce standard JSON Schema metric bounds.
65
+ - **Proofs** (`proofs/<domain>.json`) record file digests, measured metrics, evidence, and computed `PROVEN`, `FAILING`, `UNPROVEN`, `UNCLEAR`, or `ERROR` verdicts.
66
66
 
67
67
  <p align="center">
68
68
  <a href="docs/assets/how-it-works.png">
@@ -76,11 +76,11 @@ Teams lose alignment when requirements live in wikis, tests check implementation
76
76
 
77
77
  ## Benefits
78
78
 
79
- - **Plain Markdown, zero clutter.** Write pure headings and prose with zero `{#id}` anchors or `[x]` checkboxes. Folder and heading names wire `intent <- spec <- check` automatically.
80
- - **Computed verdicts you can trust.** A spec turns `PROVEN` only when its checks execute, exit `0`, and satisfy every metric bound declared in `checks/<domain>.yaml`.
81
- - **Polyglot by default.** Run Python, Bash, Node.js, Java, Go, or Rust tests in parallel. Scripts can optionally write JSON metrics and evidence to `$FF_RECORD`, or keep using plain exit codes.
82
- - **Change accountability built in.** Document contract shifts in `factory/changes/YYYY-MM-DD_<slug>.md` or labeled GitHub issues; `ff verify --base` blocks silent weakening of proven specs, checks, or thresholds.
83
- - **Built for both humans and coding agents.** Export polished HTML, Markdown, CSV, or JSONL summaries with `ff export`, and equip agents with `/ff` (`ff skill install`) and optional read-only `ff mcp`.
79
+ - **Plain Markdown, zero clutter.** Write pure headings and overview prose with zero `{#id}` anchors or `[x]` checkboxes. Folder and heading names wire `intent <- spec <- check` automatically, and splitting a proven spec into deeper child leaves stays frictionless.
80
+ - **Zero-boilerplate `pytest` & polyglot runners.** Use Python (`ff_record` built-in plugin or standard `record_property`), Bash, Node.js, Go, Java, or Rust in parallel with optional `$FF_RECORD` JSON output.
81
+ - **Standard metric rules & single source of truth.** Declare bounds once under `specs.<id>.metrics` using JSON Schema keywords (`minimum`, `maximum`, `const`, optional `unit`) — omit `checks/<domain>.yaml` completely when conventions suffice.
82
+ - **Anti-weakening governance.** Track breaking shifts in `factory/changes/YYYY-MM-DD_<slug>.md` (with optional `issue:` links); `ff verify --base` blocks silent deletion or weakening of proven specs and bounds.
83
+ - **Ready for humans and agents.** Export standalone HTML, Markdown, CSV, or JSONL reports with `ff export`, install the `/ff` skill from [`skills/ff/`](skills/ff/SKILL.md) (or `ff skill install`), and serve read-only context with `ff mcp`.
84
84
 
85
85
  ## Installation
86
86
 
@@ -90,7 +90,7 @@ Requires Python 3.14+ on Linux or macOS with [`uv`](https://docs.astral.sh/uv/ge
90
90
  uv tool install --python 3.14 factory-framework
91
91
  ```
92
92
 
93
- Add optional extras when needed (`[pytest]` for pytest test-suite helpers, `[mcp]` for the read-only MCP server):
93
+ Include `[pytest]` for built-in pytest fixtures and `[mcp]` for the read-only MCP server:
94
94
 
95
95
  ```bash
96
96
  uv tool install --python 3.14 "factory-framework[pytest,mcp]"
@@ -101,7 +101,7 @@ uv tool install --python 3.14 "factory-framework[pytest,mcp]"
101
101
  Scaffold a starter contract, run checks, verify reproducibility, and export a report:
102
102
 
103
103
  ```bash
104
- ff init --example # Add --pytest to scaffold pytest fixtures instead of a standalone script
104
+ ff init --example # Add --pytest to scaffold tests/test_hello.py with built-in ff_record
105
105
  ff run
106
106
  ff status
107
107
  ff verify --strict
@@ -110,16 +110,16 @@ ff export -f html -o proof-report.html
110
110
 
111
111
  Everyday commands at a glance:
112
112
 
113
- - `ff init [--example] [--pytest]` — create `factory/` with a zero-dependency starter check (or `pytest` fixtures with `--pytest`).
113
+ - `ff init [--example] [--pytest]` — create `factory/` with a zero-dependency script (or `pytest` check via `--pytest`).
114
114
  - `ff status` and `ff ls --tree` — inspect domain verdicts and trace links from intents to specs and checks.
115
- - `ff show <id>` — read full statements, metric bounds, and latest recorded evidence for any item.
116
- - `ff lint` and `ff verify` — check domain symmetry (`FF001`–`FF012`), re-run tests, and enforce `--base` anti-weakening rules (`FFR0`–`FFR4`).
115
+ - `ff show <id>` — read full statements, metric rules, and latest evidence for any item.
116
+ - `ff lint` and `ff verify` — check headings, schemas, proof parity, and `--base` anti-weakening rules (`FFR0`–`FFR4`).
117
117
  - `ff export -f html|md|csv|jsonl` — share proof reports with stakeholders.
118
118
  - `ff skill install` and `ff mcp` — equip coding agents with `/ff` workflow instructions and read-only contract inspection.
119
119
 
120
120
  ## Example
121
121
 
122
- Suppose you want fast, accurate checkout pricing in domain `checkout`.
122
+ Suppose you require fast, accurate checkout totals in domain `checkout`.
123
123
 
124
124
  **1. State why in `factory/intents/checkout.md`:**
125
125
 
@@ -143,17 +143,17 @@ As a shopper, I want accurate order totals immediately, so that slow pricing nev
143
143
  Given a cart with regional shipping rules, when checkout totals are requested, then pricing, tax, and totals return in 50 ms or less.
144
144
  ```
145
145
 
146
- **3. Declare bounds and check targets in `factory/checks/checkout.yaml`:**
146
+ **3. Declare metric bounds and script target in `factory/checks/checkout.yaml`:**
147
147
 
148
148
  ```yaml
149
149
  version: 1
150
- domain: checkout
151
-
150
+ specs:
151
+ spec_checkout_fast-totals_latency:
152
+ metrics:
153
+ p95_ms: { maximum: 50, unit: ms }
152
154
  checks:
153
- check_checkout_fast-totals_latency:
155
+ test_checkout_fast_totals_latency:
154
156
  file: tests/check_checkout.py
155
- metrics:
156
- p95_ms: { max: 50, precision: 0, unit: ms }
157
157
  ```
158
158
 
159
159
  **4. Prove it with a behavioral check in `factory/tests/check_checkout.py`:**
@@ -161,10 +161,8 @@ checks:
161
161
  ```python
162
162
  import json, os
163
163
  from pathlib import Path
164
-
165
164
  elapsed_ms, body = call_checkout(items=3, region="EU")
166
165
  assert body["tax"] > 0 and body["total"] > body["subtotal"]
167
-
168
166
  if record_path := os.environ.get("FF_RECORD"):
169
167
  Path(record_path).write_text(
170
168
  json.dumps(
@@ -178,7 +176,7 @@ if record_path := os.environ.get("FF_RECORD"):
178
176
  )
179
177
  ```
180
178
 
181
- Using Bash, JavaScript, Go, Java, or `pytest`? Point `file:` at `.sh`/`.mjs`/`.js` scripts, use `argv: [go, test, ./...]` for compiled binaries, or pass `--pytest` on `ff init` for `ff_record` pytest fixtures.
179
+ Using `pytest`? Omit `checks/checkout.yaml`'s `checks:` block, name your function `test_checkout_fast_totals_latency(ff_record: Recorder)`, and omit `file:` — `ff` discovers `tests/test_checkout.py` automatically via the built-in `pytest11` plugin.
182
180
 
183
181
  **5. Run and inspect the verdict:**
184
182
 
@@ -196,10 +194,10 @@ Explore [`examples/demo-service/`](examples/demo-service/README.md) for a multi-
196
194
 
197
195
  ## Documentation
198
196
 
199
- - [Documentation home](docs/docs/index.md) — architecture overview and core principles
200
- - [Getting started](docs/docs/getting-started.md) — installation, walkthrough, and `factory/` layout
201
- - [Core concepts](docs/docs/concepts.md) — `<domain>` symmetry, leaf IDs, `$FF_RECORD`, proofs, and changes
202
- - [Configuration](docs/docs/configuration.md) — `factory/ff.yaml`, `factory/checks/<domain>.yaml`, and polyglot runners
203
- - [Commands](docs/docs/commands.md) — full CLI reference, rules (`FF001`–`FF012`, `FFR0`–`FFR4`), schemas, and MCP
204
- - [Workflow](docs/docs/workflow.md) — daily loop, `--base` CI gates, exports, and `/ff` agent setup
197
+ - [Documentation home](docs/index.md) — architecture overview and core principles
198
+ - [Getting started](docs/getting-started.md) — installation, walkthrough, and `factory/` layout
199
+ - [Core concepts](docs/concepts.md) — leaf headings, parent prose, `$FF_RECORD`, `pytest`, and proofs
200
+ - [Configuration](docs/configuration.md) — `factory/ff.yaml`, optional `factory/checks/<domain>.yaml`, and runners
201
+ - [Commands](docs/commands.md) — all 12 CLI commands, lint rules (`FF001`–`FF012`, `FFR0`–`FFR4`), and schemas
202
+ - [Workflow](docs/workflow.md) — daily loop, change notes (`issue:`), `--base` CI gates, exports, and agent skills
205
203
  - [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · [LICENSE](LICENSE)
@@ -0,0 +1,167 @@
1
+ <p align="center">
2
+ <img
3
+ src="docs/assets/factory-framework.svg"
4
+ alt="Factory Framework mirrored F | F logo"
5
+ width="128"
6
+ height="128"
7
+ >
8
+ </p>
9
+
10
+ # Factory Framework
11
+
12
+ **Turn plain-Markdown requirements into proven software.**
13
+
14
+ [![CI](https://github.com/fmind/factory-framework/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-174EA6)](pyproject.toml) [![License: MIT](https://img.shields.io/badge/license-MIT-174EA6)](LICENSE)
15
+
16
+ Factory Framework (`ff`) links plain-Markdown human goals directly to executable tests inside your repository. Stakeholders, engineers, and AI coding agents read the exact same contract, and verdicts come solely from executed checks — never manual checkboxes.
17
+
18
+ [Overview](#overview) · [Benefits](#benefits) · [Installation](#installation) · [Usage](#usage) · [Example](#example) · [Documentation](#documentation)
19
+
20
+ ## Overview
21
+
22
+ Requirements rot in external wikis when tests verify implementation trivia instead of user outcomes and releases ship on guesswork.
23
+
24
+ `ff` organizes every domain inside `factory/` using implicit `<domain>` filenames:
25
+
26
+ - **Intents** (`intents/<domain>.md`) state **why** a capability matters for humans (User Stories recommended).
27
+ - **Specs** (`specs/<domain>.md`) define **what** the system guarantees (Given/When/Then or EARS recommended, with optional parent overview prose).
28
+ - **Checks** (`tests/*` + optional `checks/<domain>.yaml`) run real behavioral tests in any language and enforce standard JSON Schema metric bounds.
29
+ - **Proofs** (`proofs/<domain>.json`) record file digests, measured metrics, evidence, and computed `PROVEN`, `FAILING`, `UNPROVEN`, `UNCLEAR`, or `ERROR` verdicts.
30
+
31
+ <p align="center">
32
+ <a href="docs/assets/how-it-works.png">
33
+ <img
34
+ src="docs/assets/how-it-works.png"
35
+ alt="How Factory Framework links Markdown intents and specs to parallel tests and domain proofs"
36
+ width="960"
37
+ >
38
+ </a>
39
+ </p>
40
+
41
+ ## Benefits
42
+
43
+ - **Plain Markdown, zero clutter.** Write pure headings and overview prose with zero `{#id}` anchors or `[x]` checkboxes. Folder and heading names wire `intent <- spec <- check` automatically, and splitting a proven spec into deeper child leaves stays frictionless.
44
+ - **Zero-boilerplate `pytest` & polyglot runners.** Use Python (`ff_record` built-in plugin or standard `record_property`), Bash, Node.js, Go, Java, or Rust in parallel with optional `$FF_RECORD` JSON output.
45
+ - **Standard metric rules & single source of truth.** Declare bounds once under `specs.<id>.metrics` using JSON Schema keywords (`minimum`, `maximum`, `const`, optional `unit`) — omit `checks/<domain>.yaml` completely when conventions suffice.
46
+ - **Anti-weakening governance.** Track breaking shifts in `factory/changes/YYYY-MM-DD_<slug>.md` (with optional `issue:` links); `ff verify --base` blocks silent deletion or weakening of proven specs and bounds.
47
+ - **Ready for humans and agents.** Export standalone HTML, Markdown, CSV, or JSONL reports with `ff export`, install the `/ff` skill from [`skills/ff/`](skills/ff/SKILL.md) (or `ff skill install`), and serve read-only context with `ff mcp`.
48
+
49
+ ## Installation
50
+
51
+ Requires Python 3.14+ on Linux or macOS with [`uv`](https://docs.astral.sh/uv/getting-started/installation/):
52
+
53
+ ```bash
54
+ uv tool install --python 3.14 factory-framework
55
+ ```
56
+
57
+ Include `[pytest]` for built-in pytest fixtures and `[mcp]` for the read-only MCP server:
58
+
59
+ ```bash
60
+ uv tool install --python 3.14 "factory-framework[pytest,mcp]"
61
+ ```
62
+
63
+ ## Usage
64
+
65
+ Scaffold a starter contract, run checks, verify reproducibility, and export a report:
66
+
67
+ ```bash
68
+ ff init --example # Add --pytest to scaffold tests/test_hello.py with built-in ff_record
69
+ ff run
70
+ ff status
71
+ ff verify --strict
72
+ ff export -f html -o proof-report.html
73
+ ```
74
+
75
+ Everyday commands at a glance:
76
+
77
+ - `ff init [--example] [--pytest]` — create `factory/` with a zero-dependency script (or `pytest` check via `--pytest`).
78
+ - `ff status` and `ff ls --tree` — inspect domain verdicts and trace links from intents to specs and checks.
79
+ - `ff show <id>` — read full statements, metric rules, and latest evidence for any item.
80
+ - `ff lint` and `ff verify` — check headings, schemas, proof parity, and `--base` anti-weakening rules (`FFR0`–`FFR4`).
81
+ - `ff export -f html|md|csv|jsonl` — share proof reports with stakeholders.
82
+ - `ff skill install` and `ff mcp` — equip coding agents with `/ff` workflow instructions and read-only contract inspection.
83
+
84
+ ## Example
85
+
86
+ Suppose you require fast, accurate checkout totals in domain `checkout`.
87
+
88
+ **1. State why in `factory/intents/checkout.md`:**
89
+
90
+ ```markdown
91
+ # Checkout
92
+
93
+ ## Fast Totals
94
+
95
+ As a shopper, I want accurate order totals immediately, so that slow pricing never delays my purchase.
96
+ ```
97
+
98
+ **2. State what in `factory/specs/checkout.md`:**
99
+
100
+ ```markdown
101
+ # Checkout
102
+
103
+ ## Fast Totals
104
+
105
+ ### Latency
106
+
107
+ Given a cart with regional shipping rules, when checkout totals are requested, then pricing, tax, and totals return in 50 ms or less.
108
+ ```
109
+
110
+ **3. Declare metric bounds and script target in `factory/checks/checkout.yaml`:**
111
+
112
+ ```yaml
113
+ version: 1
114
+ specs:
115
+ spec_checkout_fast-totals_latency:
116
+ metrics:
117
+ p95_ms: { maximum: 50, unit: ms }
118
+ checks:
119
+ test_checkout_fast_totals_latency:
120
+ file: tests/check_checkout.py
121
+ ```
122
+
123
+ **4. Prove it with a behavioral check in `factory/tests/check_checkout.py`:**
124
+
125
+ ```python
126
+ import json, os
127
+ from pathlib import Path
128
+ elapsed_ms, body = call_checkout(items=3, region="EU")
129
+ assert body["tax"] > 0 and body["total"] > body["subtotal"]
130
+ if record_path := os.environ.get("FF_RECORD"):
131
+ Path(record_path).write_text(
132
+ json.dumps(
133
+ {
134
+ "summary": "Checkout returned tax and totals under 50 ms",
135
+ "metrics": {"p95_ms": elapsed_ms},
136
+ "evidence": [f"p95_ms={elapsed_ms}", f"total={body['total']}"],
137
+ }
138
+ ),
139
+ encoding="utf-8",
140
+ )
141
+ ```
142
+
143
+ Using `pytest`? Omit `checks/checkout.yaml`'s `checks:` block, name your function `test_checkout_fast_totals_latency(ff_record: Recorder)`, and omit `file:` — `ff` discovers `tests/test_checkout.py` automatically via the built-in `pytest11` plugin.
144
+
145
+ **5. Run and inspect the verdict:**
146
+
147
+ ```bash
148
+ ff run
149
+ ff status
150
+ ```
151
+
152
+ ```text
153
+ Factory: shop-api | Proofs: fresh | Gate: PASSED
154
+ Intents: 1/1 proven | Specs: 1/1 proven | Checks: 1/1 passing
155
+ ```
156
+
157
+ Explore [`examples/demo-service/`](examples/demo-service/README.md) for a multi-domain `pytest` + Bash project and [`examples/checks/`](examples/checks/) for reusable check recipes.
158
+
159
+ ## Documentation
160
+
161
+ - [Documentation home](docs/index.md) — architecture overview and core principles
162
+ - [Getting started](docs/getting-started.md) — installation, walkthrough, and `factory/` layout
163
+ - [Core concepts](docs/concepts.md) — leaf headings, parent prose, `$FF_RECORD`, `pytest`, and proofs
164
+ - [Configuration](docs/configuration.md) — `factory/ff.yaml`, optional `factory/checks/<domain>.yaml`, and runners
165
+ - [Commands](docs/commands.md) — all 12 CLI commands, lint rules (`FF001`–`FF012`, `FFR0`–`FFR4`), and schemas
166
+ - [Workflow](docs/workflow.md) — daily loop, change notes (`issue:`), `--base` CI gates, exports, and agent skills
167
+ - [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [CHANGELOG.md](CHANGELOG.md) · [LICENSE](LICENSE)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "factory-framework"
3
- version = "0.3.1"
3
+ version = "0.4.0"
4
4
  description = "Factory Framework (ff) links human intents and specs to parallel executable checks, records validated metrics, and exports stakeholder-ready proofs."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.14"
@@ -61,6 +61,9 @@ Security = "https://github.com/fmind/factory-framework/security/policy"
61
61
  [project.scripts]
62
62
  ff = "ff:main"
63
63
 
64
+ [project.entry-points.pytest11]
65
+ ff = "ff.pytest_plugin"
66
+
64
67
  [build-system]
65
68
  requires = ["uv_build>=0.12.10,<0.14"]
66
69
  build-backend = "uv_build"
@@ -1,7 +1,7 @@
1
1
  # https://packaging.python.org/en/latest/specifications/pyproject-toml/
2
2
  [project]
3
3
  name = "factory-framework"
4
- version = "0.3.1"
4
+ version = "0.4.0"
5
5
  description = "Factory Framework (ff) links human intents and specs to parallel executable checks, records validated metrics, and exports stakeholder-ready proofs."
6
6
  readme = "README.md"
7
7
  requires-python = ">=3.14"
@@ -56,6 +56,9 @@ Security = "https://github.com/fmind/factory-framework/security/policy"
56
56
  [project.scripts]
57
57
  ff = "ff:main"
58
58
 
59
+ [project.entry-points.pytest11]
60
+ ff = "ff.pytest_plugin"
61
+
59
62
  [build-system]
60
63
  requires = ["uv_build>=0.12.10,<0.14"]
61
64
  build-backend = "uv_build"
@@ -2,7 +2,9 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- __version__ = "0.3.1"
5
+ from ff.models import Recorder
6
+
7
+ __version__ = "0.4.0"
6
8
 
7
9
 
8
10
  def main(argv: list[str] | None = None) -> int:
@@ -15,4 +17,4 @@ def main(argv: list[str] | None = None) -> int:
15
17
  return code
16
18
 
17
19
 
18
- __all__ = ["__version__", "main"]
20
+ __all__ = ["Recorder", "__version__", "main"]
@@ -67,7 +67,7 @@ def build_parser() -> _Parser:
67
67
  _add(("run", "ls", "export"), "--domain", default="", metavar="DOMAIN", help="Filter to DOMAIN.")
68
68
  subs["init"].add_argument("path", nargs="?", default=".", metavar="DIR", help="Project root.")
69
69
  subs["init"].add_argument("--example", action="store_true", help="Scaffold 'hello' domain.")
70
- subs["init"].add_argument("--pytest", action="store_true", help="Add pytest conftest.py + test_hello.py.")
70
+ subs["init"].add_argument("--pytest", action="store_true", help="Use pytest test_hello.py.")
71
71
  subs["run"].add_argument("checks", nargs="*", metavar="CHECK", help="Optional check IDs.")
72
72
  subs["run"].add_argument("--no-write", action="store_true", help="Run without writing proofs.")
73
73
  subs["ls"].add_argument("--kind", choices=("intent", "spec", "check", "change"), default="", help="Item kind.")
@@ -287,7 +287,10 @@ def run(argv: Sequence[str] | None = None) -> int:
287
287
  summ, exp_p, m_errs = runner.RunSummary({}, False, ()), proofs.build_proofs(fac, {}), []
288
288
  else:
289
289
  summ, _, exp_p, m_errs = _run_and_build(fac, None, ns.jobs)
290
- gate, mismatches = proofs.evaluate_gate(fac, exp_p), [] if l_errs else proofs.verify_proofs_match(fdir, exp_p)
290
+ gate, mismatches = (
291
+ proofs.evaluate_gate(exp_p, strict=ns.strict),
292
+ ([] if l_errs else proofs.verify_proofs_match(fdir, exp_p)),
293
+ )
291
294
  if ns.base and not l_errs:
292
295
  bs = lint.evaluate_base_rules(fac, ns.base, current_proofs=exp_p)
293
296
  diags.extend(replace(d, severity="error") if (ns.strict and d.severity == "warning") else d for d in bs)
@@ -78,9 +78,12 @@ def _safe_md(md_text: str) -> str:
78
78
 
79
79
 
80
80
  def _fmt_metrics(metrics_map: dict[str, Any]) -> str:
81
+ def _bounds(m: dict[str, Any]) -> list[str]:
82
+ return [f"{k} {m[k]}" for k in ("const", "minimum", "maximum") if m.get(k) is not None]
83
+
81
84
  parts = [
82
85
  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 ''}"
86
+ f"{f' ({", ".join(b)})' if (b := _bounds(m)) else ''}"
84
87
  for n, m in sorted(metrics_map.items())
85
88
  ]
86
89
  return "; ".join(parts)
@@ -225,7 +228,7 @@ def export_proofs(factory: Factory, *, fmt: str = "md", domain: str = "", summar
225
228
  raise InputError(f"summary file not found: '{summary_path}'")
226
229
  summary_md = summary_path.read_text(encoding="utf-8") if summary_path is not None else ""
227
230
  records, dom_proofs, _, _ = query.load_saved_state(factory)
228
- gate = proofs.evaluate_gate(factory, {domain: dom_proofs[domain]} if domain else dom_proofs)
231
+ gate = proofs.evaluate_gate({domain: dom_proofs[domain]} if domain else dom_proofs, strict=True)
229
232
  rows = _collect_rows(factory, records, dom_proofs, domain=domain)
230
233
  if kind in {"csv", "jsonl"}:
231
234
  return _render_csv(rows) if kind == "csv" else b"".join(encode_compact(r) for r in rows)
@@ -1,10 +1,8 @@
1
- """Safe literal-argv Git and GitHub CLI helpers for `--base` snapshots, issues, and pollution checks."""
1
+ """Safe literal-argv Git snapshots, pollution checks, and `changes/` note parsing."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
5
  import io
6
- import json
7
- import os
8
6
  import re
9
7
  import shutil
10
8
  import subprocess
@@ -18,11 +16,8 @@ import yaml
18
16
 
19
17
  from ff import models as m
20
18
 
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
19
  _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"}
20
+ _ISSUE_VAL_RE = re.compile(r"^(?:https://[^\s<>\"]+|(?:[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)?#[1-9][0-9]*)$")
26
21
  _ID_RXS = (m.INTENT_ID_RE, m.SPEC_ID_RE, m.CHECK_ID_RE)
27
22
 
28
23
 
@@ -100,19 +95,11 @@ def workspace_status_paths(root: Path) -> set[str] | None:
100
95
  return paths
101
96
 
102
97
 
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
98
  def _is_touch_id(tok: str) -> bool:
111
- return tok == "gate" or any(rx.fullmatch(tok) for rx in _ID_RXS)
99
+ return any(rx.fullmatch(tok) for rx in _ID_RXS)
112
100
 
113
101
 
114
- def _parse_change_md(lines: list[str], *, gh: bool = False) -> tuple[str, dict[str, str], dict[str, str]]:
115
- headers: dict[str, str] = {}
102
+ def _parse_change_md(lines: list[str]) -> tuple[str, dict[str, str]]:
116
103
  secs: dict[str, list[str]] = {"motivation": [], "changes": [], "impact": []}
117
104
  title, cur, fence = "", "", ""
118
105
  for raw in lines:
@@ -125,19 +112,15 @@ def _parse_change_md(lines: list[str], *, gh: bool = False) -> tuple[str, dict[s
125
112
  continue
126
113
  if fm := _FENCE_RE.match(line):
127
114
  fence = fm.group(1)
128
- elif not gh and line.startswith("# "):
115
+ elif line.startswith("# "):
129
116
  title = line[2:].strip() or title
130
117
  continue
131
118
  elif line.startswith("## "):
132
- key = line[3:].strip().lower()
133
- cur = _SECTIONS_MAP.get(key, "impact" if key == "impact" else "-") if gh else key
119
+ cur = line[3:].strip().lower()
134
120
  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
121
  if cur in secs:
139
122
  secs[cur].append(line)
140
- return title, headers, {k: "\n".join(v).strip() for k, v in secs.items()}
123
+ return title, {k: "\n".join(v).strip() for k, v in secs.items()}
141
124
 
142
125
 
143
126
  def parse_file_changes(factory_dir: Path, diags: list[m.Diagnostic]) -> dict[str, m.Change]:
@@ -173,6 +156,13 @@ def parse_file_changes(factory_dir: Path, diags: list[m.Diagnostic]) -> dict[str
173
156
  _err(f"{rel}: invalid type '{ctype}'", rel, item=cid)
174
157
  if cstate not in m.CHANGE_STATES:
175
158
  _err(f"{rel}: invalid state '{cstate}'", rel, item=cid)
159
+ issue_raw, issue_str, issue_ok = fm.get("issue"), "", True
160
+ if issue_raw is not None:
161
+ if not isinstance(issue_raw, str) or not _ISSUE_VAL_RE.fullmatch(cand := issue_raw.strip()):
162
+ _err(f"{rel}: invalid issue reference '{issue_raw}'", rel, item=cid)
163
+ issue_ok = False
164
+ else:
165
+ issue_str = cand
176
166
  touches: list[str] = []
177
167
  if not isinstance(tr := fm.get("touches"), list) or not tr:
178
168
  _err(f"{rel}: 'touches' must be a non-empty list", rel, item=cid)
@@ -182,48 +172,10 @@ def parse_file_changes(factory_dir: Path, diags: list[m.Diagnostic]) -> dict[str
182
172
  _err(f"{rel}: invalid touched ID '{tid}'", rel, item=cid)
183
173
  elif tid not in touches:
184
174
  touches.append(tid)
185
- title, _, secs = _parse_change_md(text[end + 5 :].splitlines(), gh=False)
175
+ title, secs = _parse_change_md(text[end + 5 :].splitlines())
186
176
  if not secs["motivation"] or not secs["changes"]:
187
177
  _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"])
178
+ if id_ok and issue_ok and ctype in m.CHANGE_TYPES and cstate in m.CHANGE_STATES and touches:
179
+ args = (secs["motivation"], secs["changes"], secs["impact"], issue_str)
190
180
  out[cid] = m.Change(cid, ctype, tuple(touches), cstate, rel, title or cid, *args)
191
181
  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()))