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.
Files changed (84) hide show
  1. {throughline-4.3.0/src/throughline.egg-info → throughline-4.4.0}/PKG-INFO +4 -3
  2. {throughline-4.3.0 → throughline-4.4.0}/README.md +3 -2
  3. {throughline-4.3.0 → throughline-4.4.0}/pyproject.toml +1 -1
  4. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/brief.py +13 -5
  5. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/inherit.py +29 -4
  6. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/items.py +4 -0
  7. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/schema.py +35 -0
  8. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/storage.py +8 -1
  9. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/tomledit.py +3 -0
  10. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/validate.py +8 -1
  11. {throughline-4.3.0 → throughline-4.4.0/src/throughline.egg-info}/PKG-INFO +4 -3
  12. {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/SOURCES.txt +1 -0
  13. throughline-4.4.0/tests/test_attribute_kinds.py +114 -0
  14. {throughline-4.3.0 → throughline-4.4.0}/tests/test_schema_source.py +46 -3
  15. {throughline-4.3.0 → throughline-4.4.0}/LICENSE +0 -0
  16. {throughline-4.3.0 → throughline-4.4.0}/NOTICE +0 -0
  17. {throughline-4.3.0 → throughline-4.4.0}/setup.cfg +0 -0
  18. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/__init__.py +0 -0
  19. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/apply.py +0 -0
  20. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/cli.py +0 -0
  21. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/collision.py +0 -0
  22. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/composition.py +0 -0
  23. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/diagrams.py +0 -0
  24. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/dump.py +0 -0
  25. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/filters.py +0 -0
  26. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/fingerprint.py +0 -0
  27. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/graph.py +0 -0
  28. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/grounding.py +0 -0
  29. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/identity.py +0 -0
  30. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/inject.py +0 -0
  31. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/links.py +0 -0
  32. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/model.py +0 -0
  33. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/parser.py +0 -0
  34. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/ratification.py +0 -0
  35. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/resolvers.py +0 -0
  36. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/schema_ops.py +0 -0
  37. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/seam.py +0 -0
  38. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/signatures.py +0 -0
  39. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/signed_links.py +0 -0
  40. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/sources.py +0 -0
  41. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/uid.py +0 -0
  42. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/union.py +0 -0
  43. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/version.py +0 -0
  44. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/views.py +0 -0
  45. {throughline-4.3.0 → throughline-4.4.0}/src/throughline/worklist.py +0 -0
  46. {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/dependency_links.txt +0 -0
  47. {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/entry_points.txt +0 -0
  48. {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/requires.txt +0 -0
  49. {throughline-4.3.0 → throughline-4.4.0}/src/throughline.egg-info/top_level.txt +0 -0
  50. {throughline-4.3.0 → throughline-4.4.0}/tests/test_amend.py +0 -0
  51. {throughline-4.3.0 → throughline-4.4.0}/tests/test_apply.py +0 -0
  52. {throughline-4.3.0 → throughline-4.4.0}/tests/test_apply_once.py +0 -0
  53. {throughline-4.3.0 → throughline-4.4.0}/tests/test_baseline.py +0 -0
  54. {throughline-4.3.0 → throughline-4.4.0}/tests/test_clarify.py +0 -0
  55. {throughline-4.3.0 → throughline-4.4.0}/tests/test_deprecated_names.py +0 -0
  56. {throughline-4.3.0 → throughline-4.4.0}/tests/test_diagram_cli.py +0 -0
  57. {throughline-4.3.0 → throughline-4.4.0}/tests/test_doctor.py +0 -0
  58. {throughline-4.3.0 → throughline-4.4.0}/tests/test_engine.py +0 -0
  59. {throughline-4.3.0 → throughline-4.4.0}/tests/test_filters.py +0 -0
  60. {throughline-4.3.0 → throughline-4.4.0}/tests/test_flag.py +0 -0
  61. {throughline-4.3.0 → throughline-4.4.0}/tests/test_library_api.py +0 -0
  62. {throughline-4.3.0 → throughline-4.4.0}/tests/test_link_guard.py +0 -0
  63. {throughline-4.3.0 → throughline-4.4.0}/tests/test_migrate_withdrawn.py +0 -0
  64. {throughline-4.3.0 → throughline-4.4.0}/tests/test_normative_by_type.py +0 -0
  65. {throughline-4.3.0 → throughline-4.4.0}/tests/test_own_tree.py +0 -0
  66. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratification_change.py +0 -0
  67. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratification_withdrawal.py +0 -0
  68. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratified_content.py +0 -0
  69. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratified_deletion.py +0 -0
  70. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratifier_correction.py +0 -0
  71. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratify_several.py +0 -0
  72. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratify_status.py +0 -0
  73. {throughline-4.3.0 → throughline-4.4.0}/tests/test_ratify_transition_refused_first.py +0 -0
  74. {throughline-4.3.0 → throughline-4.4.0}/tests/test_register_type.py +0 -0
  75. {throughline-4.3.0 → throughline-4.4.0}/tests/test_resolve_collision.py +0 -0
  76. {throughline-4.3.0 → throughline-4.4.0}/tests/test_resolve_cross_graph.py +0 -0
  77. {throughline-4.3.0 → throughline-4.4.0}/tests/test_schema_ops.py +0 -0
  78. {throughline-4.3.0 → throughline-4.4.0}/tests/test_signatures.py +0 -0
  79. {throughline-4.3.0 → throughline-4.4.0}/tests/test_signed_links.py +0 -0
  80. {throughline-4.3.0 → throughline-4.4.0}/tests/test_spec_lists.py +0 -0
  81. {throughline-4.3.0 → throughline-4.4.0}/tests/test_tombstone_record.py +0 -0
  82. {throughline-4.3.0 → throughline-4.4.0}/tests/test_unset_attrs.py +0 -0
  83. {throughline-4.3.0 → throughline-4.4.0}/tests/test_worklist.py +0 -0
  84. {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.0
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
- 247
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 grounding,
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
- 247
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 grounding,
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.3.0"
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
- for pos, rule in enumerate(schema.coverage, start=1):
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
- out.append(f"{pos}. items where `{filt}` **need** `{needs}` "
298
- f"(severity: {sev})")
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, and the grounding configuration. Everything else in ``throughline.toml`` —
14
- the project's name, its rules, docs, sources, the rest of ``[ratify]`` — stays the
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 and ("grounding", key) for any other value.
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.0
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
- 247
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 grounding,
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.
@@ -46,6 +46,7 @@ src/throughline.egg-info/top_level.txt
46
46
  tests/test_amend.py
47
47
  tests/test_apply.py
48
48
  tests/test_apply_once.py
49
+ tests/test_attribute_kinds.py
49
50
  tests/test_baseline.py
50
51
  tests/test_clarify.py
51
52
  tests/test_deprecated_names.py
@@ -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 comment introducing the coverage rule belongs to it, not to the
196
- # emptied table before it.
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