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.
- {factory_framework-0.3.1 → factory_framework-0.4.0}/PKG-INFO +32 -34
- factory_framework-0.4.0/README.md +167 -0
- {factory_framework-0.3.1 → factory_framework-0.4.0}/pyproject.toml +4 -1
- {factory_framework-0.3.1 → factory_framework-0.4.0}/pyproject.toml.orig +4 -1
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/__init__.py +4 -2
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/cli.py +5 -2
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/export.py +5 -2
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/gitio.py +17 -65
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/lint.py +105 -54
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/models.py +42 -17
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/parse.py +22 -28
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/proofs.py +6 -6
- factory_framework-0.4.0/src/ff/pytest_plugin.py +85 -0
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/query.py +1 -1
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/runner.py +68 -12
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/scaffold.py +5 -119
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/schemas.py +7 -9
- factory_framework-0.4.0/src/ff/skill/SKILL.md +47 -0
- factory_framework-0.4.0/src/ff/skill/references/authoring.md +54 -0
- factory_framework-0.4.0/src/ff/skill/references/checks.md +68 -0
- factory_framework-0.4.0/src/ff/skill/references/workflow.md +65 -0
- factory_framework-0.3.1/README.md +0 -169
- factory_framework-0.3.1/src/ff/skill/SKILL.md +0 -47
- factory_framework-0.3.1/src/ff/skill/references/authoring.md +0 -59
- factory_framework-0.3.1/src/ff/skill/references/checks.md +0 -69
- factory_framework-0.3.1/src/ff/skill/references/workflow.md +0 -55
- {factory_framework-0.3.1 → factory_framework-0.4.0}/LICENSE +0 -0
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/__main__.py +0 -0
- {factory_framework-0.3.1 → factory_framework-0.4.0}/src/ff/mcp.py +0 -0
- {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
|
+
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
|
[](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [](pyproject.toml) [](LICENSE)
|
|
51
51
|
|
|
52
|
-
Factory Framework (`ff`)
|
|
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
|
-
|
|
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/`
|
|
60
|
+
`ff` organizes every domain inside `factory/` using implicit `<domain>` filenames:
|
|
61
61
|
|
|
62
|
-
- **Intents** (`intents/<domain>.md`)
|
|
63
|
-
- **Specs** (`specs/<domain>.md`) define **what** the system guarantees (Given/When/Then or EARS recommended).
|
|
64
|
-
- **Checks** (`checks/<domain>.yaml`
|
|
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
|
-
- **
|
|
81
|
-
- **
|
|
82
|
-
- **
|
|
83
|
-
- **
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
116
|
-
- `ff lint` and `ff verify` — check
|
|
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
|
|
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
|
|
146
|
+
**3. Declare metric bounds and script target in `factory/checks/checkout.yaml`:**
|
|
147
147
|
|
|
148
148
|
```yaml
|
|
149
149
|
version: 1
|
|
150
|
-
|
|
151
|
-
|
|
150
|
+
specs:
|
|
151
|
+
spec_checkout_fast-totals_latency:
|
|
152
|
+
metrics:
|
|
153
|
+
p95_ms: { maximum: 50, unit: ms }
|
|
152
154
|
checks:
|
|
153
|
-
|
|
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
|
|
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/
|
|
200
|
-
- [Getting started](docs/
|
|
201
|
-
- [Core concepts](docs/
|
|
202
|
-
- [Configuration](docs/
|
|
203
|
-
- [Commands](docs/
|
|
204
|
-
- [Workflow](docs/
|
|
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
|
+
[](https://github.com/fmind/factory-framework/actions/workflows/ci.yml) [](pyproject.toml) [](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
|
+
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.
|
|
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
|
-
|
|
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="
|
|
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 =
|
|
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 :=
|
|
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(
|
|
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
|
|
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
|
-
|
|
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
|
|
99
|
+
return any(rx.fullmatch(tok) for rx in _ID_RXS)
|
|
112
100
|
|
|
113
101
|
|
|
114
|
-
def _parse_change_md(lines: list[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
|
|
115
|
+
elif line.startswith("# "):
|
|
129
116
|
title = line[2:].strip() or title
|
|
130
117
|
continue
|
|
131
118
|
elif line.startswith("## "):
|
|
132
|
-
|
|
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,
|
|
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,
|
|
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()))
|