throughline 4.3.0__tar.gz → 4.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.
- {throughline-4.3.0/src/throughline.egg-info → throughline-4.4.0}/PKG-INFO +4 -3
- {throughline-4.3.0 → throughline-4.4.0}/README.md +3 -2
- {throughline-4.3.0 → throughline-4.4.0}/pyproject.toml +1 -1
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/brief.py +13 -5
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/inherit.py +29 -4
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/items.py +4 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/schema.py +35 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/storage.py +8 -1
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/tomledit.py +3 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/validate.py +8 -1
- {throughline-4.3.0 → throughline-4.4.0/src/throughline.egg-info}/PKG-INFO +4 -3
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/SOURCES.txt +1 -0
- throughline-4.4.0/tests/test_attribute_kinds.py +114 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_schema_source.py +46 -3
- {throughline-4.3.0 → throughline-4.4.0}/LICENSE +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/NOTICE +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/setup.cfg +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/__init__.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/apply.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/cli.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/collision.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/composition.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/diagrams.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/dump.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/filters.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/fingerprint.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/graph.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/grounding.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/identity.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/inject.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/links.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/model.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/parser.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/ratification.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/resolvers.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/schema_ops.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/seam.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/signatures.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/signed_links.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/sources.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/uid.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/union.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/version.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/views.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline/worklist.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/dependency_links.txt +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/entry_points.txt +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/requires.txt +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/top_level.txt +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_amend.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_apply.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_apply_once.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_baseline.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_clarify.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_deprecated_names.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_diagram_cli.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_doctor.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_engine.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_filters.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_flag.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_library_api.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_link_guard.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_migrate_withdrawn.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_normative_by_type.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_own_tree.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratification_change.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratification_withdrawal.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratified_content.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratified_deletion.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratifier_correction.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratify_several.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratify_status.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratify_transition_refused_first.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_register_type.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_resolve_collision.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_resolve_cross_graph.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_schema_ops.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_signatures.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_signed_links.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_spec_lists.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_tombstone_record.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_unset_attrs.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_worklist.py +0 -0
- {throughline-4.3.0 → throughline-4.4.0}/tests/test_yaml_loader.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.4.0
|
|
4
4
|
Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
|
|
5
5
|
Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
|
|
|
36
36
|
|
|
37
37
|
**Dogfooded:** throughline's own spec is itself a throughline project —
|
|
38
38
|
<!-- tl:count type == 'system_requirement' -->
|
|
39
|
-
|
|
39
|
+
248
|
|
40
40
|
<!-- tl:end --> system requirements,
|
|
41
41
|
<!-- tl:count type == 'user_requirement' -->
|
|
42
42
|
39
|
|
@@ -206,6 +206,7 @@ Upward and downward coverage are independent and both matter:
|
|
|
206
206
|
| `uid-filename` | an item's file is not named `<UID>.yml` (git could not see it collide) |
|
|
207
207
|
| `tombstone-deleted` | a retired UID's tombstone was erased (bad merge / stray `git rm`) |
|
|
208
208
|
| `schema` | missing required attr or out-of-enum value |
|
|
209
|
+
| `attribute-kind` | an attribute's value is not of its declared kind (`int`, `float`, `bool`, `date` as YYYY-MM-DD, `string`, `text`) |
|
|
209
210
|
| `suspect-link` | target changed since the link was last confirmed |
|
|
210
211
|
| `unreviewed` | item content changed since last review |
|
|
211
212
|
| `unratified` | AI-origin item still `proposed` |
|
|
@@ -244,7 +245,7 @@ that declares no sources is untouched by any of this.
|
|
|
244
245
|
A graph whose own items follow a shared model — every deck in a series, every plan
|
|
245
246
|
written to one standard — can take its schema from a source instead of copying it.
|
|
246
247
|
Mark that one source `schema = true`; the project is then checked by the source's
|
|
247
|
-
item types, attributes, link types, statuses, transitions, roles and
|
|
248
|
+
item types, attributes, link types, statuses, transitions, roles, grounding and coverage rules,
|
|
248
249
|
plus whatever it adds itself. It may add an attribute, a type, a status or a link
|
|
249
250
|
type, but never redefine one the source declares: a widened enum or a changed
|
|
250
251
|
attribute is refused when the configuration is read, naming both values.
|
|
@@ -8,7 +8,7 @@ version control; a `check` command validates the whole graph and gates CI.
|
|
|
8
8
|
|
|
9
9
|
**Dogfooded:** throughline's own spec is itself a throughline project —
|
|
10
10
|
<!-- tl:count type == 'system_requirement' -->
|
|
11
|
-
|
|
11
|
+
248
|
|
12
12
|
<!-- tl:end --> system requirements,
|
|
13
13
|
<!-- tl:count type == 'user_requirement' -->
|
|
14
14
|
39
|
|
@@ -178,6 +178,7 @@ Upward and downward coverage are independent and both matter:
|
|
|
178
178
|
| `uid-filename` | an item's file is not named `<UID>.yml` (git could not see it collide) |
|
|
179
179
|
| `tombstone-deleted` | a retired UID's tombstone was erased (bad merge / stray `git rm`) |
|
|
180
180
|
| `schema` | missing required attr or out-of-enum value |
|
|
181
|
+
| `attribute-kind` | an attribute's value is not of its declared kind (`int`, `float`, `bool`, `date` as YYYY-MM-DD, `string`, `text`) |
|
|
181
182
|
| `suspect-link` | target changed since the link was last confirmed |
|
|
182
183
|
| `unreviewed` | item content changed since last review |
|
|
183
184
|
| `unratified` | AI-origin item still `proposed` |
|
|
@@ -216,7 +217,7 @@ that declares no sources is untouched by any of this.
|
|
|
216
217
|
A graph whose own items follow a shared model — every deck in a series, every plan
|
|
217
218
|
written to one standard — can take its schema from a source instead of copying it.
|
|
218
219
|
Mark that one source `schema = true`; the project is then checked by the source's
|
|
219
|
-
item types, attributes, link types, statuses, transitions, roles and
|
|
220
|
+
item types, attributes, link types, statuses, transitions, roles, grounding and coverage rules,
|
|
220
221
|
plus whatever it adds itself. It may add an attribute, a type, a status or a link
|
|
221
222
|
type, but never redefine one the source declares: a widened enum or a changed
|
|
222
223
|
attribute is refused when the configuration is read, naming both values.
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "throughline"
|
|
7
|
-
version = "4.
|
|
7
|
+
version = "4.4.0"
|
|
8
8
|
description = "A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.11"
|
|
@@ -14,6 +14,7 @@ from __future__ import annotations
|
|
|
14
14
|
import argparse
|
|
15
15
|
from pathlib import Path
|
|
16
16
|
|
|
17
|
+
from .inherit import coverage_path
|
|
17
18
|
from .graph import Index
|
|
18
19
|
from .signatures import retired
|
|
19
20
|
from .parser import build_parser
|
|
@@ -282,7 +283,7 @@ def _describe_requirement(req) -> str:
|
|
|
282
283
|
return " and ".join(parts)
|
|
283
284
|
|
|
284
285
|
|
|
285
|
-
def _ctx_coverage(schema) -> str:
|
|
286
|
+
def _ctx_coverage(schema, inheritance=None) -> str:
|
|
286
287
|
out = ["## Coverage rules\n"]
|
|
287
288
|
if not schema.coverage:
|
|
288
289
|
out.append("_No `[[rules.coverage]]` declared._")
|
|
@@ -290,12 +291,19 @@ def _ctx_coverage(schema) -> str:
|
|
|
290
291
|
out.append("Each rule requires the matching items to have the stated link "
|
|
291
292
|
"(unmet → a `coverage` finding). They are numbered as "
|
|
292
293
|
"`tl schema rule remove` counts them:\n")
|
|
293
|
-
|
|
294
|
+
pos = 0
|
|
295
|
+
for rule in schema.coverage:
|
|
294
296
|
filt = rule.get("filter", "*")
|
|
295
297
|
needs = rule.get("needs", "?")
|
|
296
298
|
sev = rule.get("severity", WARNING)
|
|
297
|
-
|
|
298
|
-
|
|
299
|
+
line = f"items where `{filt}` **need** `{needs}` (severity: {sev})"
|
|
300
|
+
# An inherited rule is the schema source's (SR-0275, SR-0279): it is not
|
|
301
|
+
# this project's to remove, so it takes no number here.
|
|
302
|
+
if inheritance is not None and inheritance.owns(*coverage_path(rule)):
|
|
303
|
+
out.append(f"- {line} (from `{inheritance.namespace}`)")
|
|
304
|
+
continue
|
|
305
|
+
pos += 1
|
|
306
|
+
out.append(f"{pos}. {line}")
|
|
299
307
|
return "\n".join(out)
|
|
300
308
|
|
|
301
309
|
|
|
@@ -516,7 +524,7 @@ def context_markdown(project) -> str:
|
|
|
516
524
|
_ctx_links(schema, inheritance),
|
|
517
525
|
_ctx_status(schema, inheritance),
|
|
518
526
|
_ctx_grounding(schema),
|
|
519
|
-
_ctx_coverage(schema),
|
|
527
|
+
_ctx_coverage(schema, inheritance),
|
|
520
528
|
_CTX_FORMAT,
|
|
521
529
|
_ctx_commands(),
|
|
522
530
|
_ctx_snapshot(project),
|
|
@@ -10,9 +10,9 @@ formed, and the project's own.
|
|
|
10
10
|
|
|
11
11
|
What is inherited is exactly what SR-0275 names: item types and their attributes,
|
|
12
12
|
link types and endpoint rules, statuses, transitions and status roles, ratify
|
|
13
|
-
roles,
|
|
14
|
-
the project's name,
|
|
15
|
-
project's own.
|
|
13
|
+
roles, the grounding configuration, and coverage rules. Everything else in
|
|
14
|
+
``throughline.toml`` — the project's name, the severities of its named rules, docs,
|
|
15
|
+
sources, the rest of ``[ratify]`` — stays the project's own.
|
|
16
16
|
|
|
17
17
|
A project may add to what it inherits but never redefine it (SR-0276). A name the
|
|
18
18
|
source declares may be declared again only with the identical value; a list the
|
|
@@ -24,6 +24,7 @@ enum's values belong to whoever declares the attribute.
|
|
|
24
24
|
from __future__ import annotations
|
|
25
25
|
|
|
26
26
|
import copy
|
|
27
|
+
import json
|
|
27
28
|
from dataclasses import dataclass
|
|
28
29
|
|
|
29
30
|
from .schema import _GROUNDING_DEFAULTS, SchemaError
|
|
@@ -31,7 +32,8 @@ from .schema import _GROUNDING_DEFAULTS, SchemaError
|
|
|
31
32
|
# A declaration's address: ("type", name), ("attr", type, name), ("link", name),
|
|
32
33
|
# ("link_rule", type), ("status", value), ("status_role", role),
|
|
33
34
|
# ("transition", from), ("ratify_role", role), ("grounding", key, member) for a
|
|
34
|
-
# list member
|
|
35
|
+
# list member, ("grounding", key) for any other value, and ("coverage", rule) for a
|
|
36
|
+
# coverage rule, the rule written as canonical JSON since a rule has no name.
|
|
35
37
|
Path = tuple[str, ...]
|
|
36
38
|
|
|
37
39
|
|
|
@@ -73,6 +75,10 @@ def describe(path: Path) -> str:
|
|
|
73
75
|
return f"transitions from '{path[1]}'"
|
|
74
76
|
if kind == "ratify_role":
|
|
75
77
|
return f"ratify role '{path[1]}'"
|
|
78
|
+
if kind == "coverage":
|
|
79
|
+
rule = json.loads(path[1])
|
|
80
|
+
return (f"coverage rule: items where {rule.get('filter', '*')} need "
|
|
81
|
+
f"{rule.get('needs', '?')}")
|
|
76
82
|
if len(path) == 3:
|
|
77
83
|
return f"grounding {path[1]} entry '{path[2]}'"
|
|
78
84
|
return f"grounding {path[1]}"
|
|
@@ -109,9 +115,17 @@ def declarations(config: dict) -> dict[Path, object]:
|
|
|
109
115
|
out[("grounding", key, member)] = True
|
|
110
116
|
else:
|
|
111
117
|
out[("grounding", key)] = value
|
|
118
|
+
for rule in ((config.get("rules") or {}).get("coverage") or []):
|
|
119
|
+
out[coverage_path(rule)] = True
|
|
112
120
|
return out
|
|
113
121
|
|
|
114
122
|
|
|
123
|
+
def coverage_path(rule: dict) -> Path:
|
|
124
|
+
"""A coverage rule's address: the rule itself, written so that two rules saying
|
|
125
|
+
the same thing have the same address."""
|
|
126
|
+
return ("coverage", json.dumps(rule, sort_keys=True, ensure_ascii=False))
|
|
127
|
+
|
|
128
|
+
|
|
115
129
|
def _refuse(path: Path, namespace: str, here, there) -> InheritanceError:
|
|
116
130
|
return InheritanceError(
|
|
117
131
|
f"{describe(path)} is declared by the schema source '{namespace}' and "
|
|
@@ -193,6 +207,17 @@ def merge(source: dict, local: dict, namespace: str) -> tuple[dict, Inheritance]
|
|
|
193
207
|
if ratify_roles:
|
|
194
208
|
out["ratify"] = {**(local.get("ratify") or {}), "roles": ratify_roles}
|
|
195
209
|
|
|
210
|
+
# Coverage rules: the source's, then the project's own that the source does not
|
|
211
|
+
# already state. A follower cannot drop one it inherits; it has no way to say so.
|
|
212
|
+
theirs_rules = list(((source.get("rules") or {}).get("coverage")) or [])
|
|
213
|
+
mine_rules = list(((local.get("rules") or {}).get("coverage")) or [])
|
|
214
|
+
if theirs_rules:
|
|
215
|
+
seen = {coverage_path(r) for r in theirs_rules}
|
|
216
|
+
rules_out = dict(local.get("rules") or {})
|
|
217
|
+
rules_out["coverage"] = copy.deepcopy(theirs_rules) + [
|
|
218
|
+
copy.deepcopy(r) for r in mine_rules if coverage_path(r) not in seen]
|
|
219
|
+
out["rules"] = rules_out
|
|
220
|
+
|
|
196
221
|
grounding = dict(local.get("grounding") or {})
|
|
197
222
|
for key in set(source.get("grounding") or {}) | set(grounding):
|
|
198
223
|
there = (source.get("grounding") or {}).get(key)
|
|
@@ -28,6 +28,7 @@ from .grounding import (
|
|
|
28
28
|
)
|
|
29
29
|
from .graph import Index
|
|
30
30
|
from .model import Item, Link
|
|
31
|
+
from .schema import kind_accepts
|
|
31
32
|
from .signatures import OUTRIGHT, STAMP, latest, names, retired, signatures
|
|
32
33
|
from .uid import UidError, next_uid, parse_uid
|
|
33
34
|
|
|
@@ -61,6 +62,9 @@ def coerce_attr(schema, item_type: str, key: str, raw: str):
|
|
|
61
62
|
if low in ("false", "0", "no"):
|
|
62
63
|
return False
|
|
63
64
|
raise ValueError(f"expected a boolean, got '{raw}'")
|
|
65
|
+
if kind == "date" and not kind_accepts("date", raw):
|
|
66
|
+
# A date was taken as any text until SR-0282.
|
|
67
|
+
raise ValueError(f"expected a calendar date written YYYY-MM-DD, got '{raw}'")
|
|
64
68
|
except ValueError as e:
|
|
65
69
|
raise UidError(f"--attr {key}={raw}: {e}") from e
|
|
66
70
|
return raw
|
|
@@ -16,6 +16,7 @@ at load time so the tool fails fast instead of silently mis-behaving.
|
|
|
16
16
|
"""
|
|
17
17
|
from __future__ import annotations
|
|
18
18
|
|
|
19
|
+
import datetime as _dt
|
|
19
20
|
import re
|
|
20
21
|
from dataclasses import dataclass, field
|
|
21
22
|
|
|
@@ -58,6 +59,40 @@ _STATUS_ROLE_KEYS = frozenset(
|
|
|
58
59
|
{"initial", "proposed", "ratified", "invalidated", "suspect", "tombstone"})
|
|
59
60
|
|
|
60
61
|
|
|
62
|
+
_ISO_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def kind_accepts(kind: str | None, value) -> bool:
|
|
66
|
+
"""Whether ``value`` is of the declared attribute ``kind`` (SR-0282). A kind of
|
|
67
|
+
``None`` is free-form and accepts anything; an enum's membership is its own
|
|
68
|
+
check (SR-0023). Defined once, for check and for every write."""
|
|
69
|
+
if kind is None or kind == "enum":
|
|
70
|
+
return True
|
|
71
|
+
if kind == "int":
|
|
72
|
+
return isinstance(value, int) and not isinstance(value, bool)
|
|
73
|
+
if kind == "float":
|
|
74
|
+
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
|
75
|
+
if kind == "bool":
|
|
76
|
+
return isinstance(value, bool)
|
|
77
|
+
if kind in ("string", "text"):
|
|
78
|
+
return isinstance(value, str)
|
|
79
|
+
if kind == "date":
|
|
80
|
+
# YAML reads an unquoted 2026-10-30 as a date; a quoted one is text in the
|
|
81
|
+
# same shape. A timestamp is not a calendar date.
|
|
82
|
+
if isinstance(value, _dt.datetime):
|
|
83
|
+
return False
|
|
84
|
+
if isinstance(value, _dt.date):
|
|
85
|
+
return True
|
|
86
|
+
if isinstance(value, str) and _ISO_DATE.match(value):
|
|
87
|
+
try:
|
|
88
|
+
_dt.date.fromisoformat(value)
|
|
89
|
+
except ValueError:
|
|
90
|
+
return False
|
|
91
|
+
return True
|
|
92
|
+
return False
|
|
93
|
+
return True
|
|
94
|
+
|
|
95
|
+
|
|
61
96
|
class SchemaError(ValueError):
|
|
62
97
|
"""Malformed or internally inconsistent project configuration (SR-0082)."""
|
|
63
98
|
|
|
@@ -962,7 +962,7 @@ def _remove_inherited_declarations(root: Path) -> tuple[str, ...]:
|
|
|
962
962
|
formed with: the source supplies it either way. A declaration written in a form
|
|
963
963
|
this editor cannot follow is left as it is, which is harmless for the same
|
|
964
964
|
reason. Idempotent: a removed declaration is not there to be removed again."""
|
|
965
|
-
from .inherit import declarations, describe, redundant
|
|
965
|
+
from .inherit import coverage_path, declarations, describe, redundant
|
|
966
966
|
|
|
967
967
|
cfg_file = root / CONFIG_NAME
|
|
968
968
|
text = cfg_file.read_text(encoding="utf-8")
|
|
@@ -1031,6 +1031,13 @@ def _remove_inherited_declarations(root: Path) -> tuple[str, ...]:
|
|
|
1031
1031
|
for key, value in (config.get("grounding") or {}).items():
|
|
1032
1032
|
if isinstance(value, list):
|
|
1033
1033
|
shrink("grounding", key, ("grounding", key), paths)
|
|
1034
|
+
# Coverage rules are blocks of their own, taken last to first so each
|
|
1035
|
+
# removal leaves the positions before it where they were.
|
|
1036
|
+
mine_rules = list(((config.get("rules") or {}).get("coverage")) or [])
|
|
1037
|
+
for index in reversed(range(len(mine_rules))):
|
|
1038
|
+
path = coverage_path(mine_rules[index])
|
|
1039
|
+
if path in paths:
|
|
1040
|
+
attempt(path, lambda i=index: doc.remove_array_table(("rules", "coverage"), i))
|
|
1034
1041
|
|
|
1035
1042
|
# A table the removals emptied goes too, innermost first.
|
|
1036
1043
|
for table in (*((("types", t),) for t in (config.get("types") or {})),
|
|
@@ -388,6 +388,9 @@ class TomlDocument:
|
|
|
388
388
|
f"this document has {len(spans)} [[{written}]] block(s); "
|
|
389
389
|
f"there is no #{index + 1}")
|
|
390
390
|
start, end = spans[index]
|
|
391
|
+
if end < len(self._lines):
|
|
392
|
+
# The comment directly above the next header introduces that block.
|
|
393
|
+
end = self._comment_start(end, start)
|
|
391
394
|
floor = spans[index - 1][1] - 1 if index else -1
|
|
392
395
|
at = self._comment_start(start, floor)
|
|
393
396
|
self._lines[at:end] = comment_block(because) if because else []
|
|
@@ -16,6 +16,7 @@ from .fingerprint import content_fingerprint, deletion_fingerprint, fingerprint
|
|
|
16
16
|
from .signed_links import describe_drift, link_drift, recorded_links
|
|
17
17
|
from .filters import FilterError, safe_eval
|
|
18
18
|
from .graph import Index
|
|
19
|
+
from .schema import kind_accepts
|
|
19
20
|
from .grounding import ambiguity_report, grounding_gap, is_flagged_ambiguous, is_unserved
|
|
20
21
|
from .signatures import (
|
|
21
22
|
CONTENT, STAMP, W_BY, W_OF, W_REASON, describe, relevant, retired, signatures,
|
|
@@ -49,7 +50,7 @@ _DEFAULT_SEVERITY = {
|
|
|
49
50
|
"key-collision": ERROR,
|
|
50
51
|
"uid-filename": ERROR,
|
|
51
52
|
"malformed-link": ERROR,
|
|
52
|
-
"schema": ERROR, "unknown-key": ERROR, "empty-graph": ERROR,
|
|
53
|
+
"schema": ERROR, "attribute-kind": ERROR, "unknown-key": ERROR, "empty-graph": ERROR,
|
|
53
54
|
"empty-registers": WARNING,
|
|
54
55
|
"dangling-link": ERROR, "deleted-link-target": ERROR, "refines-cycle": ERROR,
|
|
55
56
|
"namespace-unresolved": ERROR,
|
|
@@ -293,6 +294,12 @@ def validate(project, strict: bool = False,
|
|
|
293
294
|
if present and spec.kind == "enum" and item.attrs[name] not in spec.values:
|
|
294
295
|
add("schema", item.uid, f,
|
|
295
296
|
f"attribute '{name}'='{item.attrs[name]}' not in {list(spec.values)}")
|
|
297
|
+
# The declared kind (SR-0282): a rule of its own, so a project upgrading
|
|
298
|
+
# with values written under the old leniency can lower it alone.
|
|
299
|
+
if present and not kind_accepts(spec.kind, item.attrs[name]):
|
|
300
|
+
add("attribute-kind", item.uid, f,
|
|
301
|
+
f"attribute '{name}' is declared {spec.kind} but holds "
|
|
302
|
+
f"{item.attrs[name]!r}")
|
|
296
303
|
|
|
297
304
|
# Link integrity (SR-0032) + type legality (SR-0030).
|
|
298
305
|
for link in item.links:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: throughline
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.4.0
|
|
4
4
|
Summary: A Git-native requirements management tool with a scope-avalanche grounding layer: permanent UIDs, one file per item, typed links, suspect detection, and a CI-gating check.
|
|
5
5
|
Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
|
|
6
6
|
License-Expression: Apache-2.0
|
|
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
|
|
|
36
36
|
|
|
37
37
|
**Dogfooded:** throughline's own spec is itself a throughline project —
|
|
38
38
|
<!-- tl:count type == 'system_requirement' -->
|
|
39
|
-
|
|
39
|
+
248
|
|
40
40
|
<!-- tl:end --> system requirements,
|
|
41
41
|
<!-- tl:count type == 'user_requirement' -->
|
|
42
42
|
39
|
|
@@ -206,6 +206,7 @@ Upward and downward coverage are independent and both matter:
|
|
|
206
206
|
| `uid-filename` | an item's file is not named `<UID>.yml` (git could not see it collide) |
|
|
207
207
|
| `tombstone-deleted` | a retired UID's tombstone was erased (bad merge / stray `git rm`) |
|
|
208
208
|
| `schema` | missing required attr or out-of-enum value |
|
|
209
|
+
| `attribute-kind` | an attribute's value is not of its declared kind (`int`, `float`, `bool`, `date` as YYYY-MM-DD, `string`, `text`) |
|
|
209
210
|
| `suspect-link` | target changed since the link was last confirmed |
|
|
210
211
|
| `unreviewed` | item content changed since last review |
|
|
211
212
|
| `unratified` | AI-origin item still `proposed` |
|
|
@@ -244,7 +245,7 @@ that declares no sources is untouched by any of this.
|
|
|
244
245
|
A graph whose own items follow a shared model — every deck in a series, every plan
|
|
245
246
|
written to one standard — can take its schema from a source instead of copying it.
|
|
246
247
|
Mark that one source `schema = true`; the project is then checked by the source's
|
|
247
|
-
item types, attributes, link types, statuses, transitions, roles and
|
|
248
|
+
item types, attributes, link types, statuses, transitions, roles, grounding and coverage rules,
|
|
248
249
|
plus whatever it adds itself. It may add an attribute, a type, a status or a link
|
|
249
250
|
type, but never redefine one the source declares: a widened enum or a changed
|
|
250
251
|
attribute is refused when the configuration is read, naming both values.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Copyright (c) 2026 Henry J Grech-Cini
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
"""A declared attribute holds a value of its declared kind (SR-0282).
|
|
4
|
+
|
|
5
|
+
Check validated only required attributes and enum membership, and a date was
|
|
6
|
+
validated nowhere: a source's checked day reading "next tuesday" passed every
|
|
7
|
+
gate. These tests hold check and the writes to the kinds the schema declares, and
|
|
8
|
+
leave an undeclared attribute free-form.
|
|
9
|
+
"""
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import datetime as dt
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
import pytest
|
|
16
|
+
|
|
17
|
+
from throughline.cli import main as cli_main
|
|
18
|
+
from throughline.schema import kind_accepts
|
|
19
|
+
from throughline.storage import load_project, write_item
|
|
20
|
+
from throughline.validate import validate
|
|
21
|
+
|
|
22
|
+
KINDS = """attrs.count = { type = "int" }
|
|
23
|
+
attrs.weight = { type = "float" }
|
|
24
|
+
attrs.flag = { type = "bool" }
|
|
25
|
+
attrs.checked = { type = "date" }
|
|
26
|
+
attrs.label = { type = "string" }
|
|
27
|
+
attrs.notes = { type = "text" }
|
|
28
|
+
attrs.loose = {}
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _cli(argv) -> int:
|
|
33
|
+
return cli_main([str(a) for a in argv])
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _project(tmp_path: Path) -> Path:
|
|
37
|
+
root = tmp_path / "p"
|
|
38
|
+
assert _cli(["-C", root, "init", "--name", "t", "--bare"]) == 0
|
|
39
|
+
cfg = root / "throughline.toml"
|
|
40
|
+
text = cfg.read_text(encoding="utf-8")
|
|
41
|
+
assert "[types.requirement]\n" in text
|
|
42
|
+
cfg.write_text(text.replace("[types.requirement]\n", "[types.requirement]\n" + KINDS, 1),
|
|
43
|
+
encoding="utf-8")
|
|
44
|
+
assert _cli(["-C", root, "register", "new", "INT", "vision"]) == 0
|
|
45
|
+
assert _cli(["-C", root, "register", "new", "FR", "features"]) == 0
|
|
46
|
+
assert _cli(["-C", root, "new", "INT", "--type", "intent", "--title", "why"]) == 0
|
|
47
|
+
assert _cli(["-C", root, "new", "FR", "--type", "requirement", "--title", "r",
|
|
48
|
+
"--ground", "INT-0001"]) == 0
|
|
49
|
+
return root
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _hold(root: Path, **attrs) -> list:
|
|
53
|
+
project = load_project(root)
|
|
54
|
+
item = project.get("FR-0001")
|
|
55
|
+
item.attrs.update(attrs)
|
|
56
|
+
write_item(item, project.register_of("FR-0001"))
|
|
57
|
+
return [f for f in validate(load_project(root)) if f.rule == "attribute-kind"]
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
@pytest.mark.parametrize("kind,good,bad", [
|
|
61
|
+
("int", [3, 0, -2], [True, 2.5, "3"]),
|
|
62
|
+
("float", [2.5, 3], [True, "2.5"]),
|
|
63
|
+
("bool", [True, False], [1, "yes"]),
|
|
64
|
+
("date", [dt.date(2026, 10, 30), "2026-10-30"],
|
|
65
|
+
["next tuesday", "2026-13-01", "30/10/2026", dt.datetime(2026, 10, 30, 9)]),
|
|
66
|
+
("string", ["x", ""], [3, True]),
|
|
67
|
+
("text", ["a\nb"], [3]),
|
|
68
|
+
])
|
|
69
|
+
def test_each_kind_accepts_its_values_and_no_other(kind, good, bad):
|
|
70
|
+
assert all(kind_accepts(kind, v) for v in good)
|
|
71
|
+
assert not any(kind_accepts(kind, v) for v in bad)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def test_no_kind_and_enum_accept_anything_here():
|
|
75
|
+
assert kind_accepts(None, object())
|
|
76
|
+
assert kind_accepts("enum", "whatever") # membership is its own check (SR-0023)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def test_check_reports_a_value_of_the_wrong_kind(tmp_path):
|
|
80
|
+
root = _project(tmp_path)
|
|
81
|
+
found = _hold(root, checked="next tuesday", count="three", flag="yes")
|
|
82
|
+
assert sorted(f.message.split("'")[1] for f in found) == ["checked", "count", "flag"]
|
|
83
|
+
assert all(f.uid == "FR-0001" and f.severity == "error" for f in found)
|
|
84
|
+
assert any("'next tuesday'" in f.message and "date" in f.message for f in found)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def test_values_of_the_right_kind_and_free_form_ones_pass(tmp_path):
|
|
88
|
+
root = _project(tmp_path)
|
|
89
|
+
assert _hold(root, count=3, weight=1.5, flag=True, checked="2026-10-30",
|
|
90
|
+
label="x", notes="y", loose=["anything", 1], undeclared={"a": 1}) == []
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def test_the_rule_can_be_lowered_alone(tmp_path):
|
|
94
|
+
root = _project(tmp_path)
|
|
95
|
+
cfg = root / "throughline.toml"
|
|
96
|
+
text = cfg.read_text(encoding="utf-8")
|
|
97
|
+
if "\n[rules]\n" in text:
|
|
98
|
+
text = text.replace("\n[rules]\n", '\n[rules]\nattribute-kind = "warning"\n', 1)
|
|
99
|
+
else:
|
|
100
|
+
text = text.replace("[types.requirement]", '[rules]\nattribute-kind = "warning"\n\n'
|
|
101
|
+
"[types.requirement]", 1)
|
|
102
|
+
cfg.write_text(text, encoding="utf-8")
|
|
103
|
+
found = _hold(root, checked="soon")
|
|
104
|
+
assert [f.severity for f in found] == ["warning"]
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def test_writes_refuse_a_date_that_is_not_one(tmp_path, capsys):
|
|
108
|
+
root = _project(tmp_path)
|
|
109
|
+
assert _cli(["-C", root, "new", "FR", "--type", "requirement", "--title", "x",
|
|
110
|
+
"--ground", "INT-0001", "--attr", "checked=next tuesday"]) != 0
|
|
111
|
+
assert "YYYY-MM-DD" in capsys.readouterr().err
|
|
112
|
+
assert _cli(["-C", root, "amend", "FR-0001", "--attr", "checked=2026-02-30"]) != 0
|
|
113
|
+
assert _cli(["-C", root, "amend", "FR-0001", "--attr", "checked=2026-10-30"]) == 0
|
|
114
|
+
assert load_project(root).get("FR-0001").attrs["checked"] == "2026-10-30"
|
|
@@ -192,9 +192,8 @@ def test_migrate_removes_the_copy_keeps_what_is_added_and_runs_once(tmp_path, ca
|
|
|
192
192
|
# What the project adds, and the comments on it, stay.
|
|
193
193
|
assert "attrs.tone" in text and "# a local attribute" in text
|
|
194
194
|
assert "# the slide type, copied" in text
|
|
195
|
-
# The
|
|
196
|
-
|
|
197
|
-
assert "# Coverage: every live requirement" in text and "[[rules.coverage]]" in text
|
|
195
|
+
# The template's coverage rule is the standard's too, so its copy goes (SR-0275).
|
|
196
|
+
assert "[[rules.coverage]]" not in text
|
|
198
197
|
after = load_project(fol).schema
|
|
199
198
|
assert after == before
|
|
200
199
|
assert _cli(["-C", fol, "check"]) == 0
|
|
@@ -314,3 +313,47 @@ def test_an_attribute_is_added_to_an_inherited_type_in_the_project_itself(tmp_pa
|
|
|
314
313
|
project = load_project(fol)
|
|
315
314
|
assert project.config["types"]["slide"]["attrs"] == {"caption": {"type": "string"}}
|
|
316
315
|
assert project.schema.attr("slide", "layout") is not None
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
# --------------------------------------------------------------------------- #
|
|
319
|
+
# SR-0275 — a schema source passes on its coverage rules
|
|
320
|
+
# --------------------------------------------------------------------------- #
|
|
321
|
+
|
|
322
|
+
RULE = ('\n[[rules.coverage]]\nfilter = "type == \'slide\'"\n'
|
|
323
|
+
'needs = "incoming:derives_from"\nseverity = "error"\n')
|
|
324
|
+
# A rule the follower adds itself, which the standard does not state.
|
|
325
|
+
OWN = ("\n# the follower's own rule"
|
|
326
|
+
'\n[[rules.coverage]]\nfilter = "type == \'nfr\'"\n'
|
|
327
|
+
'needs = "incoming:verifies"\n')
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
def test_a_follower_is_held_to_its_sources_coverage_rules(tmp_path):
|
|
331
|
+
_standard(tmp_path, extra=STANDARD + RULE)
|
|
332
|
+
fol = _follower(tmp_path, OWN)
|
|
333
|
+
filters = [r["filter"] for r in load_project(fol).schema.coverage]
|
|
334
|
+
# The source's rules first, the follower's own after them, and the template
|
|
335
|
+
# rule both carry stated once.
|
|
336
|
+
assert filters == ["type == 'requirement' and status != 'deleted'",
|
|
337
|
+
"type == 'slide'", "type == 'nfr'"]
|
|
338
|
+
|
|
339
|
+
|
|
340
|
+
def test_the_brief_marks_an_inherited_rule_and_numbers_only_the_followers(tmp_path, capsys):
|
|
341
|
+
_standard(tmp_path, extra=STANDARD + RULE)
|
|
342
|
+
fol = _follower(tmp_path, OWN)
|
|
343
|
+
capsys.readouterr()
|
|
344
|
+
assert _cli(["-C", fol, "context"]) == 0
|
|
345
|
+
out = capsys.readouterr().out
|
|
346
|
+
section = out.split("## Coverage rules", 1)[1].split("\n## ", 1)[0]
|
|
347
|
+
assert "- items where `type == 'slide'`" in section and "(from `std`)" in section
|
|
348
|
+
assert "1. items where `type == 'nfr'`" in section and "2. " not in section
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
def test_migrate_removes_a_copied_coverage_rule_and_keeps_the_followers(tmp_path):
|
|
352
|
+
_standard(tmp_path, extra=STANDARD + RULE)
|
|
353
|
+
fol = _follower(tmp_path, RULE + OWN)
|
|
354
|
+
before = load_project(fol).schema.coverage
|
|
355
|
+
migrate_project(fol)
|
|
356
|
+
text = (fol / "throughline.toml").read_text(encoding="utf-8")
|
|
357
|
+
assert "type == 'slide'" not in text and "status != 'deleted'" not in text
|
|
358
|
+
assert text.count("[[rules.coverage]]") == 1 and "# the follower's own rule" in text
|
|
359
|
+
assert load_project(fol).schema.coverage == before
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|