@agent-ix/quoin 0.10.0 → 0.12.0
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.
- package/default-modules.yaml +16 -16
- package/dist/{base-cpv9xSpO.js → base-DGA47VMM.js} +1 -1
- package/dist/cli.js +1 -1
- package/dist/commands/catalog/list.js +2 -2
- package/dist/commands/catalog/show.js +2 -2
- package/dist/commands/catalog/validate.js +2 -2
- package/dist/commands/config/doctor.js +1 -1
- package/dist/commands/config/edit.js +1 -1
- package/dist/commands/config/get.js +1 -1
- package/dist/commands/config/set.js +1 -1
- package/dist/commands/matrix.js +1 -1
- package/dist/commands/module/ensure-defaults.js +3 -3
- package/dist/commands/module/install.js +2 -2
- package/dist/commands/module/list.js +2 -2
- package/dist/commands/module/remove.js +2 -2
- package/dist/commands/review.js +1 -1
- package/dist/commands/to-plan.js +1 -1
- package/dist/commands/update.js +2 -2
- package/dist/commands/write.js +3 -3
- package/dist/{flow-command-DrC7aLJv.js → flow-command-CPS23AjI.js} +1 -1
- package/dist/index.js +6 -6
- package/dist/{modules-DelLm9BE.js → modules-CCvL41O_.js} +2 -2
- package/dist/{plugins-DQmOmTBH.js → plugins-ByvihMa0.js} +1 -1
- package/dist/{version-BWo5LBah.js → version-Be_NtSa4.js} +1 -1
- package/dist/{write-BZWI_GSS.js → write-xs9kemgB.js} +1 -1
- package/package.json +2 -1
- package/skills/spec-correctness/SKILL.md +98 -0
- package/skills/spec-correctness/assets/property-queue-template.md +78 -0
- package/skills/spec-correctness/assets/strategy-table.md +101 -0
- package/skills/spec-correctness/assets/templates/fast-check.ts.md +153 -0
- package/skills/spec-correctness/assets/templates/hypothesis.py.md +155 -0
- package/skills/spec-correctness/assets/templates/proptest.rs.md +144 -0
- package/skills/spec-correctness/references/step-0-scope-and-harness.md +94 -0
- package/skills/spec-correctness/references/step-1-census.md +53 -0
- package/skills/spec-correctness/references/step-2-clause-grounding.md +159 -0
- package/skills/spec-correctness/references/step-3-strategy-selection.md +83 -0
- package/skills/spec-correctness/references/step-4-generate-tests.md +99 -0
- package/skills/spec-correctness/references/step-5-second-pass.md +79 -0
- package/skills/spec-correctness/references/step-6-review-queue.md +64 -0
- package/skills/spec-correctness/references/step-7-report-and-handoff.md +63 -0
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# TypeScript / fast-check templates
|
|
2
|
+
|
|
3
|
+
File: `tests/props/fr-NNN.prop.test.ts` (queued: `tests/props/_review/…`).
|
|
4
|
+
Inert marker: `it.skip` / `describe.skip`.
|
|
5
|
+
Runner: whichever the repo already uses — read `vitest.config.*`, `jest.config.*`, or
|
|
6
|
+
`package.json#scripts.test`. The imports below assume vitest; swap for `@jest/globals`
|
|
7
|
+
where the repo uses jest.
|
|
8
|
+
|
|
9
|
+
## Anatomy
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
// tests/props/fr-012.prop.test.ts
|
|
13
|
+
import fc from "fast-check";
|
|
14
|
+
import { describe, it, expect } from "vitest";
|
|
15
|
+
import { detectDuplicates, type Entry } from "../../src/catalog.js";
|
|
16
|
+
|
|
17
|
+
// grounded in step 2 from `## Inputs` + the signature at src/catalog.ts:88
|
|
18
|
+
const entryArb: fc.Arbitrary<Entry> = fc.record({
|
|
19
|
+
kind: fc.stringMatching(/^[a-z]{1,12}$/),
|
|
20
|
+
name: fc.stringMatching(/^[a-z]{1,12}$/),
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Trace: FR-012-AC-1 — declaring modules are listed in sorted order.
|
|
25
|
+
* spec-correctness: row=FR-012-AC-1 property=ordering extraction=extractable origin=regex review=none
|
|
26
|
+
*/
|
|
27
|
+
describe("FR-012-AC-1 duplicate modules are sorted", () => {
|
|
28
|
+
it("holds for any catalog", () => {
|
|
29
|
+
fc.assert(
|
|
30
|
+
fc.property(fc.array(entryArb, { maxLength: 32 }), (entries) => {
|
|
31
|
+
for (const d of detectDuplicates(entries).duplicates) {
|
|
32
|
+
expect(d.modules).toEqual([...d.modules].sort());
|
|
33
|
+
}
|
|
34
|
+
}),
|
|
35
|
+
);
|
|
36
|
+
});
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Both tag carriers: `Trace:` on its own JSDoc line, and `FR-012-AC-1` inside the `describe`
|
|
41
|
+
title.
|
|
42
|
+
|
|
43
|
+
## Family bodies
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
// round-trip
|
|
47
|
+
expect(parse(render(x))).toEqual(x);
|
|
48
|
+
|
|
49
|
+
// round-trip, lossy
|
|
50
|
+
expect(normalize(parse(render(x)))).toEqual(normalize(x));
|
|
51
|
+
|
|
52
|
+
// idempotence — seed with f's own outputs
|
|
53
|
+
const seeded = fc.oneof(rawConfigArb, rawConfigArb.map(normalize));
|
|
54
|
+
expect(normalize(normalize(x))).toEqual(normalize(x));
|
|
55
|
+
|
|
56
|
+
// invariant
|
|
57
|
+
expect(resolve(x).length).toBeLessThanOrEqual(MAX_MODULES);
|
|
58
|
+
|
|
59
|
+
// ordering, order-independence
|
|
60
|
+
expect(summarize(xs)).toEqual(summarize([...xs].reverse()));
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## error-case — negative domain
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
/**
|
|
67
|
+
* Trace: FR-005-AC-1 — an unknown command raises an error that names the usage.
|
|
68
|
+
* spec-correctness: row=FR-005-AC-1 property=error-case extraction=extractable origin=regex review=none
|
|
69
|
+
*/
|
|
70
|
+
describe("FR-005-AC-1 unknown commands error", () => {
|
|
71
|
+
it("rejects any command outside the known set", () => {
|
|
72
|
+
fc.assert(
|
|
73
|
+
fc.property(fc.stringMatching(/^[a-z]{1,12}$/), (cmd) => {
|
|
74
|
+
fc.pre(!KNOWN.has(cmd));
|
|
75
|
+
expect(() => run([cmd])).toThrow(UnknownCommandError); // class, from src
|
|
76
|
+
expect(() => run([cmd])).toThrow(/Usage:/); // payload, from ## Outputs
|
|
77
|
+
}),
|
|
78
|
+
);
|
|
79
|
+
});
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## lifecycle — fc.commands / modelRun
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
/**
|
|
87
|
+
* Trace: FR-040-AC-2 — a session accepts exactly the ops its state allows.
|
|
88
|
+
* spec-correctness: row=FR-040-AC-2 property=lifecycle extraction=extractable origin=regex review=none
|
|
89
|
+
*/
|
|
90
|
+
describe("FR-040-AC-2 session lifecycle", () => {
|
|
91
|
+
it("matches the model over any op sequence", () => {
|
|
92
|
+
fc.assert(
|
|
93
|
+
fc.property(fc.commands(allCommands, { maxCommands: 24 }), (cmds) =>
|
|
94
|
+
fc.modelRun(() => ({ model: newModel(), real: new Session() }), cmds),
|
|
95
|
+
),
|
|
96
|
+
);
|
|
97
|
+
});
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Each command's `check(model)` is the precondition; its `run(model, real)` carries the
|
|
102
|
+
assertion. That split *is* the precondition/oracle split from step 2.
|
|
103
|
+
|
|
104
|
+
## concurrency — deterministic scheduler
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
/**
|
|
108
|
+
* Trace: FR-050-AC-1 — concurrent writers never lose an entry.
|
|
109
|
+
* spec-correctness: row=FR-050-AC-1 property=concurrency extraction=extractable origin=regex review=none
|
|
110
|
+
*/
|
|
111
|
+
describe("FR-050-AC-1 concurrent writes", () => {
|
|
112
|
+
it("linearizes under any interleaving", async () => {
|
|
113
|
+
await fc.assert(
|
|
114
|
+
fc.asyncProperty(fc.scheduler(), async (s) => {
|
|
115
|
+
const store = new Store();
|
|
116
|
+
s.scheduleSequence([
|
|
117
|
+
{ label: "a", builder: () => store.put("a", 1) },
|
|
118
|
+
{ label: "b", builder: () => store.put("b", 2) },
|
|
119
|
+
]);
|
|
120
|
+
await s.waitAll();
|
|
121
|
+
expect(store.size).toBe(2);
|
|
122
|
+
}),
|
|
123
|
+
);
|
|
124
|
+
});
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`fc.scheduler()` is deterministic and shrinkable — never use real timers or `Promise.all`
|
|
129
|
+
races for a concurrency property.
|
|
130
|
+
|
|
131
|
+
## Queued form
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
/**
|
|
135
|
+
* Trace: FR-018-AC-3 — a plugin source maps to exactly one resolved root.
|
|
136
|
+
* spec-correctness: row=FR-018-AC-3 property=invariant extraction=candidate origin=regex-candidate review=required
|
|
137
|
+
*/
|
|
138
|
+
describe("FR-018-AC-3 source maps to one root", () => {
|
|
139
|
+
it.skip("spec-correctness review pending", () => { … });
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Acceptance turns `it.skip` into `it` and moves the file. The tag carriers are untouched.
|
|
144
|
+
|
|
145
|
+
## Notes
|
|
146
|
+
|
|
147
|
+
- `fc.assert(fc.property(…))` synchronous, `await fc.assert(fc.asyncProperty(…))` async.
|
|
148
|
+
A forgotten `await` makes the test pass vacuously.
|
|
149
|
+
- Bound every `fc.array` with `maxLength`.
|
|
150
|
+
- `fc.pre(...)` inside the property, not around it.
|
|
151
|
+
- Return `void` or `boolean` from a property predicate — an assertion that throws is fine;
|
|
152
|
+
a returned truthy non-boolean is not.
|
|
153
|
+
- Reuse the repo's existing arbitraries and factories before writing new ones.
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Python / hypothesis templates
|
|
2
|
+
|
|
3
|
+
File: `tests/props/test_fr_NNN.py` (queued: `tests/props/_review/…`).
|
|
4
|
+
Inert marker: `@pytest.mark.skip(reason="spec-correctness review pending")`.
|
|
5
|
+
|
|
6
|
+
## Anatomy
|
|
7
|
+
|
|
8
|
+
```python
|
|
9
|
+
# tests/props/test_fr_012.py
|
|
10
|
+
from hypothesis import given, strategies as st
|
|
11
|
+
|
|
12
|
+
from quoin.catalog import Entry, detect_duplicates
|
|
13
|
+
|
|
14
|
+
# grounded in step 2 from `## Inputs` + the signature at src/quoin/catalog.py:88
|
|
15
|
+
entries = st.builds(
|
|
16
|
+
Entry,
|
|
17
|
+
kind=st.from_regex(r"\A[a-z]{1,12}\Z"),
|
|
18
|
+
name=st.from_regex(r"\A[a-z]{1,12}\Z"),
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@given(catalog=st.lists(entries, max_size=32))
|
|
23
|
+
def test_fr_012_ac_1_duplicate_modules_sorted(catalog):
|
|
24
|
+
"""Trace: FR-012-AC-1 — declaring modules are listed in sorted order.
|
|
25
|
+
|
|
26
|
+
spec-correctness: row=FR-012-AC-1 property=ordering extraction=extractable origin=regex review=none
|
|
27
|
+
"""
|
|
28
|
+
for dup in detect_duplicates(catalog).duplicates:
|
|
29
|
+
assert dup.modules == sorted(dup.modules)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Both tag carriers: `Trace:` on its own docstring line, and `fr_012_ac_1_` in the function
|
|
33
|
+
name.
|
|
34
|
+
|
|
35
|
+
## Family bodies
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
# round-trip
|
|
39
|
+
assert parse(render(x)) == x
|
|
40
|
+
|
|
41
|
+
# round-trip, lossy
|
|
42
|
+
assert normalize(parse(render(x))) == normalize(x)
|
|
43
|
+
|
|
44
|
+
# idempotence — seed with f's own outputs
|
|
45
|
+
seeded = st.one_of(raw_configs, raw_configs.map(normalize))
|
|
46
|
+
assert normalize(normalize(x)) == normalize(x)
|
|
47
|
+
|
|
48
|
+
# invariant
|
|
49
|
+
assert len(resolve(x)) <= MAX_MODULES
|
|
50
|
+
|
|
51
|
+
# ordering, permutation preservation
|
|
52
|
+
assert Counter(reorder(xs)) == Counter(xs)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## error-case — negative domain
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
from hypothesis import assume
|
|
59
|
+
import pytest
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@given(cmd=st.from_regex(r"\A[a-z]{1,12}\Z"))
|
|
63
|
+
def test_fr_005_ac_1_unknown_command_errors(cmd):
|
|
64
|
+
"""Trace: FR-005-AC-1 — an unknown command raises an error that names the usage.
|
|
65
|
+
|
|
66
|
+
spec-correctness: row=FR-005-AC-1 property=error-case extraction=extractable origin=regex review=none
|
|
67
|
+
"""
|
|
68
|
+
assume(cmd not in KNOWN)
|
|
69
|
+
with pytest.raises(UnknownCommandError, match="Usage:"):
|
|
70
|
+
run([cmd])
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`pytest.raises(Class, match=...)` carries both required assertions — the error class from
|
|
74
|
+
the code, the payload from `## Outputs` — in one line.
|
|
75
|
+
|
|
76
|
+
Prefer `st.sampled_from` over a broad regex plus `assume` when the negative domain is small;
|
|
77
|
+
too many `assume` rejections trip hypothesis's health checks.
|
|
78
|
+
|
|
79
|
+
## lifecycle — RuleBasedStateMachine
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from hypothesis.stateful import RuleBasedStateMachine, invariant, precondition, rule
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class SessionMachine(RuleBasedStateMachine):
|
|
86
|
+
"""Trace: FR-040-AC-2 — a session accepts exactly the ops its state allows.
|
|
87
|
+
|
|
88
|
+
spec-correctness: row=FR-040-AC-2 property=lifecycle extraction=extractable origin=regex review=none
|
|
89
|
+
"""
|
|
90
|
+
|
|
91
|
+
def __init__(self):
|
|
92
|
+
super().__init__()
|
|
93
|
+
self.sut = Session()
|
|
94
|
+
self.model = []
|
|
95
|
+
|
|
96
|
+
@rule()
|
|
97
|
+
def open(self):
|
|
98
|
+
self.sut.open()
|
|
99
|
+
|
|
100
|
+
@rule(data=st.text(max_size=64))
|
|
101
|
+
@precondition(lambda self: self.sut.is_open)
|
|
102
|
+
def write(self, data):
|
|
103
|
+
self.sut.write(data)
|
|
104
|
+
self.model.append(data)
|
|
105
|
+
|
|
106
|
+
@invariant()
|
|
107
|
+
def buffer_matches_model(self):
|
|
108
|
+
assert self.sut.buffer == "".join(self.model)
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
TestSessionLifecycle = SessionMachine.TestCase
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
`@precondition` is the step-2 precondition; `@invariant` is the step-2 oracle.
|
|
115
|
+
|
|
116
|
+
## concurrency — always queued
|
|
117
|
+
|
|
118
|
+
hypothesis ships no interleaving scheduler, so a Python concurrency criterion is never
|
|
119
|
+
emitted unattended. Emit a `RuleBasedStateMachine` over the async model, queued:
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
@pytest.mark.skip(reason="spec-correctness review pending")
|
|
123
|
+
class TestConcurrentWrites(RuleBasedStateMachine):
|
|
124
|
+
"""Trace: FR-050-AC-1 — concurrent writers never lose an entry.
|
|
125
|
+
|
|
126
|
+
spec-correctness: row=FR-050-AC-1 property=concurrency extraction=not-extractable origin=llm-second-pass review=required confidence=low
|
|
127
|
+
"""
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Say in the queue row that the interleaving is not exhaustively explored — that is the
|
|
131
|
+
reason it needs a person.
|
|
132
|
+
|
|
133
|
+
## Queued form
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
@pytest.mark.skip(reason="spec-correctness review pending")
|
|
137
|
+
@given(src=plugin_sources)
|
|
138
|
+
def test_fr_018_ac_3_source_maps_to_one_root(src):
|
|
139
|
+
"""Trace: FR-018-AC-3 — a plugin source maps to exactly one resolved root.
|
|
140
|
+
|
|
141
|
+
spec-correctness: row=FR-018-AC-3 property=invariant extraction=candidate origin=regex-candidate review=required
|
|
142
|
+
"""
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Acceptance deletes the `@pytest.mark.skip` line and moves the file. The tag carriers do not
|
|
146
|
+
change.
|
|
147
|
+
|
|
148
|
+
## Notes
|
|
149
|
+
|
|
150
|
+
- `@given` outermost, `@pytest.mark.*` above it; hypothesis and pytest fixtures do not mix
|
|
151
|
+
freely — pass state through the strategy, not through a function-scoped fixture.
|
|
152
|
+
- Bound every `st.lists` with `max_size`, every `st.text` with `max_size`.
|
|
153
|
+
- Never `@seed(...)` a generated test, and never `@settings(derandomize=True)` — both hide
|
|
154
|
+
the failures the property exists to find.
|
|
155
|
+
- Raise `max_examples` only with a reason recorded in the queue.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Rust / proptest templates
|
|
2
|
+
|
|
3
|
+
File: `tests/props_fr_NNN.rs` (queued: `tests/props_review_fr_NNN.rs`).
|
|
4
|
+
Inert marker: `#[ignore = "spec-correctness review pending"]`.
|
|
5
|
+
|
|
6
|
+
Paths are **flat**: cargo auto-discovers integration tests only at `tests/*.rs`. A file
|
|
7
|
+
under `tests/props/` compiles as a helper module and never runs. See step 4.
|
|
8
|
+
|
|
9
|
+
## Anatomy
|
|
10
|
+
|
|
11
|
+
```rust
|
|
12
|
+
// tests/props_fr_012.rs
|
|
13
|
+
use proptest::prelude::*;
|
|
14
|
+
use quoin::catalog::{detect_duplicates, Entry};
|
|
15
|
+
|
|
16
|
+
fn entry() -> impl Strategy<Value = Entry> {
|
|
17
|
+
// grounded in step 2 from `## Inputs` + the signature at src/catalog.rs:88
|
|
18
|
+
("[a-z]{1,12}", "[a-z]{1,12}").prop_map(|(kind, name)| Entry::new(kind, name))
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
proptest! {
|
|
22
|
+
/// Trace: FR-012-AC-1 — declaring modules are listed in sorted order.
|
|
23
|
+
/// spec-correctness: row=FR-012-AC-1 property=ordering extraction=extractable origin=regex review=none
|
|
24
|
+
#[test]
|
|
25
|
+
fn fr_012_ac_1_duplicate_modules_sorted(entries in prop::collection::vec(entry(), 0..32)) {
|
|
26
|
+
for dup in detect_duplicates(&entries).duplicates {
|
|
27
|
+
let mut sorted = dup.modules.clone();
|
|
28
|
+
sorted.sort();
|
|
29
|
+
prop_assert_eq!(dup.modules, sorted);
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Both tag carriers are present: `Trace:` on its own doc-comment line, and `fr_012_ac_1_` in
|
|
36
|
+
the function name.
|
|
37
|
+
|
|
38
|
+
## Family bodies
|
|
39
|
+
|
|
40
|
+
Same `proptest! { #[test] fn … }` wrapper; only the assertion changes.
|
|
41
|
+
|
|
42
|
+
```rust
|
|
43
|
+
// round-trip
|
|
44
|
+
prop_assert_eq!(parse(&render(&x))?, x);
|
|
45
|
+
|
|
46
|
+
// round-trip, lossy (cite the FR line stating the loss)
|
|
47
|
+
prop_assert_eq!(normalize(&parse(&render(&x))?), normalize(&x));
|
|
48
|
+
|
|
49
|
+
// idempotence — seed with f's own outputs
|
|
50
|
+
fn seeded() -> impl Strategy<Value = Config> {
|
|
51
|
+
prop_oneof![raw_config(), raw_config().prop_map(|c| normalize(&c))]
|
|
52
|
+
}
|
|
53
|
+
prop_assert_eq!(normalize(&normalize(&x)), normalize(&x));
|
|
54
|
+
|
|
55
|
+
// invariant
|
|
56
|
+
prop_assert!(resolve(&x).len() <= MAX_MODULES);
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## error-case — negative domain
|
|
60
|
+
|
|
61
|
+
```rust
|
|
62
|
+
proptest! {
|
|
63
|
+
/// Trace: FR-005-AC-1 — an unknown command raises an error that names the usage.
|
|
64
|
+
/// spec-correctness: row=FR-005-AC-1 property=error-case extraction=extractable origin=regex review=none
|
|
65
|
+
#[test]
|
|
66
|
+
fn fr_005_ac_1_unknown_command_errors(
|
|
67
|
+
cmd in "[a-z]{1,12}".prop_filter("must be unknown", |c| !KNOWN.contains(&c.as_str()))
|
|
68
|
+
) {
|
|
69
|
+
let err = run(&[cmd.as_str()]).unwrap_err();
|
|
70
|
+
prop_assert!(matches!(err, Error::UnknownCommand(_))); // class, from the error enum
|
|
71
|
+
prop_assert!(err.to_string().contains("Usage:")); // payload, from ## Outputs
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## lifecycle — model vs SUT
|
|
77
|
+
|
|
78
|
+
```rust
|
|
79
|
+
proptest! {
|
|
80
|
+
/// Trace: FR-040-AC-2 — a session accepts exactly the ops its state allows.
|
|
81
|
+
/// spec-correctness: row=FR-040-AC-2 property=lifecycle extraction=extractable origin=regex review=none
|
|
82
|
+
#[test]
|
|
83
|
+
fn fr_040_ac_2_session_lifecycle(ops in prop::collection::vec(any_op(), 1..24)) {
|
|
84
|
+
let (mut model, mut sut) = (Model::default(), Session::new());
|
|
85
|
+
for op in ops {
|
|
86
|
+
let legal = model.allows(&op);
|
|
87
|
+
prop_assert_eq!(sut.apply(&op).is_ok(), legal);
|
|
88
|
+
if legal { model.apply(&op); }
|
|
89
|
+
prop_assert!(sut.invariant_holds());
|
|
90
|
+
}
|
|
91
|
+
prop_assert_eq!(sut.state(), model.state());
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## concurrency — loom
|
|
97
|
+
|
|
98
|
+
Not a `proptest!` block; `loom` enumerates interleavings itself.
|
|
99
|
+
|
|
100
|
+
```rust
|
|
101
|
+
/// Trace: FR-050-AC-1 — concurrent writers never lose an entry.
|
|
102
|
+
/// spec-correctness: row=FR-050-AC-1 property=concurrency extraction=extractable origin=regex review=none
|
|
103
|
+
#[test]
|
|
104
|
+
fn fr_050_ac_1_concurrent_writes_linearizable() {
|
|
105
|
+
loom::model(|| {
|
|
106
|
+
let store = loom::sync::Arc::new(Store::new());
|
|
107
|
+
let handles: Vec<_> = (0..2)
|
|
108
|
+
.map(|i| { let s = store.clone(); loom::thread::spawn(move || s.put(i, i)) })
|
|
109
|
+
.collect();
|
|
110
|
+
for h in handles { h.join().unwrap(); }
|
|
111
|
+
assert_eq!(store.len(), 2);
|
|
112
|
+
});
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Keep the loom model tiny — two threads, two ops. Interleavings explode.
|
|
117
|
+
|
|
118
|
+
## Queued form
|
|
119
|
+
|
|
120
|
+
```rust
|
|
121
|
+
proptest! {
|
|
122
|
+
/// Trace: FR-018-AC-3 — a plugin source maps to exactly one resolved root.
|
|
123
|
+
/// spec-correctness: row=FR-018-AC-3 property=invariant extraction=candidate origin=regex-candidate review=required
|
|
124
|
+
#[test]
|
|
125
|
+
#[ignore = "spec-correctness review pending"]
|
|
126
|
+
fn fr_018_ac_3_source_maps_to_one_root(src in plugin_source()) { … }
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Acceptance deletes the `#[ignore]` line and moves the file. The two tag carriers do not
|
|
131
|
+
change.
|
|
132
|
+
|
|
133
|
+
## Notes
|
|
134
|
+
|
|
135
|
+
- **Import by the `[lib] name`, not the package name.** They differ often —
|
|
136
|
+
`package.name = "quire-rs"` but `lib.name = "quire_rs"`, so an integration test writes
|
|
137
|
+
`use quire_rs::…`. Read `[lib] name` in `Cargo.toml`; fall back to the package name with
|
|
138
|
+
`-` replaced by `_` only when no `[lib]` block declares one.
|
|
139
|
+
- `prop_assert*` inside `proptest!`, plain `assert*` inside `loom::model`.
|
|
140
|
+
- Bound every `prop::collection::vec` — `0..32` unless the FR states a bound.
|
|
141
|
+
- Prefer building a negative domain directly over `prop_filter` when the filter rejects
|
|
142
|
+
most values; proptest gives up after too many rejections.
|
|
143
|
+
- Do not set `ProptestConfig { cases, .. }` above the default without recording why in the
|
|
144
|
+
queue.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Step 0: Scope and Harness
|
|
2
|
+
|
|
3
|
+
**Goal**: know what you are classifying, what harness you are writing into, and what
|
|
4
|
+
tracking-tag form the repo already uses.
|
|
5
|
+
|
|
6
|
+
## 1. Resolve scope
|
|
7
|
+
|
|
8
|
+
Repo root = the directory holding the spec tree. Default glob `spec/**/*.md`; a multi-repo
|
|
9
|
+
layout uses `specs/<category>/<component>/spec/**/*.md`.
|
|
10
|
+
|
|
11
|
+
## 2. Run the classifier
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
quire properties --scope <repo> --json 'spec/**/*.md'
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Requires quire-cli ≥ 0.12.0 (`quire --version`). Output shape:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{"documents": [{
|
|
21
|
+
"document": "<abs path>",
|
|
22
|
+
"archetype": "FR",
|
|
23
|
+
"criteria": [{
|
|
24
|
+
"row_id": "FR-027-AC-1",
|
|
25
|
+
"statement": "A stored organization is used ahead of the `origin` remote…",
|
|
26
|
+
"line": 74,
|
|
27
|
+
"shape": "assertion",
|
|
28
|
+
"property": "universal",
|
|
29
|
+
"extractable": true,
|
|
30
|
+
"extraction": "extractable",
|
|
31
|
+
"domain": null, "precondition": null, "oracle": null,
|
|
32
|
+
"signals": ["universal:determiner"]
|
|
33
|
+
}]
|
|
34
|
+
}]}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Field notes that matter:
|
|
38
|
+
|
|
39
|
+
- `row_id` — the only identifier shared with the matrix and with `gap-analysis`. Never
|
|
40
|
+
synthesize one, never alter one. A record with `row_id: null` cannot be tagged, so it
|
|
41
|
+
goes straight to the queue with reason `no-row-id`.
|
|
42
|
+
- `line` is 1-based and **file**-relative. Span `start`/`end` are **statement**-relative
|
|
43
|
+
byte offsets into `statement`. Do not mix them.
|
|
44
|
+
- Spans are usually `null` (they reach ~4% of the ecosystem corpus). Their absence says
|
|
45
|
+
nothing about the criterion; step 2 grounds the clauses regardless.
|
|
46
|
+
- `signals` is an audit trail, useful for diagnosis. `span:refused-weak-boundary` means the
|
|
47
|
+
engine declined to guess a boundary — read it as "the oracle must come from the code."
|
|
48
|
+
|
|
49
|
+
Add `--pretty` while developing. Stderr carries module diagnostics (`DuplicateArchetype`
|
|
50
|
+
etc.); they are noise for this skill, not findings.
|
|
51
|
+
|
|
52
|
+
## 3. Detect the harness
|
|
53
|
+
|
|
54
|
+
Probe the repo root, in this order. Record harness, generator library presence, test dir,
|
|
55
|
+
and runner.
|
|
56
|
+
|
|
57
|
+
| Harness | Manifest | Generator library | Test path |
|
|
58
|
+
| --- | --- | --- | --- |
|
|
59
|
+
| Rust / proptest | `Cargo.toml` | `proptest`, `proptest-state-machine`, `loom`, `arbitrary` in `[dev-dependencies]` | `tests/props_fr_NNN.rs` (flat — cargo discovers only `tests/*.rs`) |
|
|
60
|
+
| TypeScript / fast-check | `package.json` | `fast-check` in `devDependencies`; runner from `vitest.config.*`, `jest.config.*`, or `package.json#scripts.test` | `tests/props/fr-NNN.prop.test.ts` |
|
|
61
|
+
| Python / hypothesis | `pyproject.toml`, `setup.cfg`, `requirements*.txt` | `hypothesis`; runner from `pytest.ini` / `tox.ini` / `conftest.py` | `tests/props/test_fr_NNN.py` |
|
|
62
|
+
|
|
63
|
+
Rules:
|
|
64
|
+
|
|
65
|
+
- **Manifest present, generator library absent** — install nothing, and **write no test
|
|
66
|
+
files**. A file that imports a missing generator library breaks the suite even when every
|
|
67
|
+
test in it is skipped, because the import is evaluated at collection time. Record the
|
|
68
|
+
proposals as fenced code blocks in the queue instead, and report one line:
|
|
69
|
+
`harness <lib> not installed — add <lib> to <dev-deps>, then re-run to emit these`.
|
|
70
|
+
Adding a dependency is the user's call, not this skill's.
|
|
71
|
+
- **Polyglot repo** — resolve per-FR from the AC table's `Verification` column, which names
|
|
72
|
+
the test file (`Test (org.test.ts)` → TypeScript). If that column is absent, use the tree
|
|
73
|
+
holding the symbol step 2 grounded. Never pick one harness repo-wide by guessing.
|
|
74
|
+
- **No harness at all** — stop after steps 1 and 2. Emit the grounded strategies as prose
|
|
75
|
+
in the queue file. Write no test files.
|
|
76
|
+
|
|
77
|
+
## 4. Detect the existing tag style
|
|
78
|
+
|
|
79
|
+
Grep the existing test tree for the four forms `gap-analysis` accepts
|
|
80
|
+
(`skills/gap-analysis/references/step-3-matrix-verification.md`):
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
Trace: FR-
|
|
84
|
+
FR-[0-9]{3}-AC-
|
|
85
|
+
TC-[0-9]{3}
|
|
86
|
+
Tests for FR-
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Mimic the dominant form. The tags in step 4 are additive to it, never a replacement — if
|
|
90
|
+
this repo writes `// FR-025-AC-7:` line comments, keep writing those too.
|
|
91
|
+
|
|
92
|
+
## Output of this step
|
|
93
|
+
|
|
94
|
+
`{repo, glob, records[], harness, generator_lib_present, test_dir, runner, tag_style}`.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Step 1: Census
|
|
2
|
+
|
|
3
|
+
**Goal**: state what the classifier found, as counts, so the rest of the run has a
|
|
4
|
+
denominator. Nothing in this step is a judgement.
|
|
5
|
+
|
|
6
|
+
## Bucket
|
|
7
|
+
|
|
8
|
+
Cross-tabulate the records two ways:
|
|
9
|
+
|
|
10
|
+
- `property` × `extraction` — this drives routing and volume.
|
|
11
|
+
- `archetype` × `extraction` — this tells you where the properties live (FR? StR? NFR?).
|
|
12
|
+
|
|
13
|
+
Report the totals plainly:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
Criteria: 118
|
|
17
|
+
extraction extractable 51 · candidate 0 · not-extractable 67
|
|
18
|
+
property universal 43 · example 59 · error-case 9 · unclassified 5 · ordering 2
|
|
19
|
+
archetype FR 84 · NFR 21 · StR 13
|
|
20
|
+
spans present domain 4 · precondition 2 · oracle 5
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## What this step must never emit
|
|
24
|
+
|
|
25
|
+
- A threshold, a target, a percentage framed as a score, or a grade of any kind.
|
|
26
|
+
- A pass/fail, a verdict, or a severity. The classification carries no severity key and no
|
|
27
|
+
promotion path by design (quire-rs FR-052-CON-1).
|
|
28
|
+
- A suggestion to reword, split, or "improve" any criterion. Not as a recommendation, not
|
|
29
|
+
as a note, not as a parenthetical. If a criterion is a concrete example, the correct
|
|
30
|
+
response is an example-based test, not an edit to the spec.
|
|
31
|
+
- A comparison of this repo against another repo's ratio.
|
|
32
|
+
|
|
33
|
+
Phrase counts as facts: "59 criteria are concrete examples" — not "only 43% are
|
|
34
|
+
extractable" and never "consider rewriting the 59 example criteria as properties."
|
|
35
|
+
|
|
36
|
+
## What is worth flagging (as information)
|
|
37
|
+
|
|
38
|
+
- Records with `row_id: null` — they cannot be tagged, so they cannot be reconciled. Route
|
|
39
|
+
to the queue with reason `no-row-id`.
|
|
40
|
+
- Documents that produced zero criteria — usually the archetype binds no `ac` grammar
|
|
41
|
+
(US and IT are unbound), which is expected, not a gap.
|
|
42
|
+
- A `candidate` count above zero — rare (0.4% of the corpus). Worth naming because every
|
|
43
|
+
one of them is review-gated by construction.
|
|
44
|
+
|
|
45
|
+
## Archetype note
|
|
46
|
+
|
|
47
|
+
Do **not** down-weight StR. The measured ranking is StR 29.1% > NFR 28.9% > FR 19.2%
|
|
48
|
+
(quire-rs CR-029, which falsified the earlier CR-020 prediction that StR would score low).
|
|
49
|
+
Stakeholder criteria produce good properties.
|
|
50
|
+
|
|
51
|
+
## Output of this step
|
|
52
|
+
|
|
53
|
+
The census tables, plus the working set for step 2: every record with a `row_id`.
|