throughline 2.2.0__tar.gz → 2.2.1__tar.gz

{throughline-2.2.0/src/throughline.egg-info → throughline-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 2.2.0
+Version: 2.2.1
 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.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-156
+159
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 25

{throughline-2.2.0 → throughline-2.2.1}/README.md

@@ -8,7 +8,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-156
+159
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 25

{throughline-2.2.0 → throughline-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "2.2.0"
+version = "2.2.1"
 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."
 readme = "README.md"
 requires-python = ">=3.11"

{throughline-2.2.0 → throughline-2.2.1}/src/throughline/cli.py

@@ -47,7 +47,7 @@ from .storage import (
     write_manifest,
 )
 from .uid import PREFIX_GRAMMAR, UidError, next_uid, parse_uid, valid_prefix
-from .validate import ERROR, FilterError, eval_filter, validate
+from .validate import ERROR, OFF, WARNING, FilterError, eval_filter, validate
 from .version import distribution_version
 
 OK, FINDINGS, USAGE = 0, 1, 2
@@ -1286,12 +1286,13 @@ def _ctx_coverage(schema) -> str:
         out.append("_No `[[rules.coverage]]` declared._")
         return "\n".join(out)
     out.append("Each rule requires the matching items to have the stated link "
-               "(unmet → a `coverage` finding):\n")
-    for rule in schema.coverage:
+               "(unmet → a `coverage` finding). They are numbered as "
+               "`tl schema rule remove` counts them:\n")
+    for pos, rule in enumerate(schema.coverage, start=1):
         filt = rule.get("filter", "*")
         needs = rule.get("needs", "?")
-        sev = rule.get("severity", "error")
-        out.append(f"- items where `{filt}` **need** `{needs}` "
+        sev = rule.get("severity", WARNING)
+        out.append(f"{pos}. items where `{filt}` **need** `{needs}` "
                    f"(severity: {sev})")
     return "\n".join(out)
 
@@ -1363,7 +1364,7 @@ _CTX_COMMAND_EMPHASIS = {
     "delete": "tombstones an item; the file stays, the item stops counting",
     "amend": "change content through the tool, never by opening the YAML",
     "schema": "change the schema itself — nouns: status, transition, type, attr, "
-              "linktype, linkrule, grounding; refuses a change that would "
+              "linktype, linkrule, grounding, rule; refuses a change that would "
               "invalidate existing items and says what to fix",
 }
 
@@ -1814,6 +1815,7 @@ def _add_schema_parser(sub) -> None:
         "linktype": "the link vocabulary",
         "linkrule": "endpoint constraints on a link type",
         "grounding": "the grounding configuration",
+        "rule": "coverage rules the gate enforces",
     }
     made: dict[str, object] = {}
 
@@ -1928,6 +1930,23 @@ def _add_schema_parser(sub) -> None:
     v.add_argument("field", metavar="FIELD")
     v.add_argument("value")
 
+    v = _schema_verb("rule", "add",
+                     lambda p, a: schema_ops.rule_add(
+                         p, filter=a.filter, needs=a.needs, severity=a.severity),
+                     "declare a coverage rule")
+    v.add_argument("--filter", required=True,
+                   help="which items the rule governs, e.g. \"type == 'system_"
+                        "requirement' and attrs.get('verification') == 'test'\"")
+    v.add_argument("--needs", required=True,
+                   help="what they must have: incoming:<link type> or "
+                        "outgoing:<link type>")
+    v.add_argument("--severity", default=None, choices=[ERROR, WARNING, OFF],
+                   help="default: warning")
+    v = _schema_verb("rule", "remove",
+                     lambda p, a: schema_ops.rule_remove(p, a.index),
+                     "withdraw a coverage rule, by its position in `tl context`")
+    v.add_argument("index", type=int, metavar="N")
+
 
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="tl", description=__doc__.splitlines()[0])

{throughline-2.2.0 → throughline-2.2.1}/src/throughline/filters.py

@@ -34,10 +34,96 @@ _METHODS = frozenset({
 })
 
 
+# Every name a filter may reference (SR-0045). Declared here, beside the grammar,
+# so the static check below and the namespace `validate._filter_namespace` builds
+# cannot drift apart; a test holds the two to each other.
+FILTER_NAMES = frozenset({
+    "type", "status", "register", "uid", "derived", "normative",
+    "title", "text", "rationale", "attrs", "links",
+    "true", "false", "none",
+})
+
+
 class FilterError(ValueError):
     """A filter expression could not be parsed or evaluated (SR-0045)."""
 
 
+def check_filter(expr: str, names: frozenset[str] = FILTER_NAMES) -> None:
+    """Validate ``expr`` against the grammar without evaluating it (SR-0191).
+
+    Evaluation cannot answer 'is this expression sound?', because `and`/`or`
+    short-circuit: in ``type == 'x' and verifcation == 'y'`` the misspelling is
+    reached only for items that pass the first test, so whether the mistake is
+    noticed depends on which items the graph happens to hold. This walks every
+    branch instead, so the answer is a property of the expression alone.
+
+    Raises :class:`FilterError` naming the first fault found.
+    """
+    if not expr or not expr.strip():
+        return
+    try:
+        tree = ast.parse(expr, mode="eval")
+    except SyntaxError as e:
+        raise FilterError(f"could not parse filter: {e.msg}") from e
+    _check(tree.body, names)
+
+
+def _check(node, names: frozenset[str]) -> None:
+    """Walk one node of the same grammar :func:`_eval` executes. The two stay in
+    step by sharing ``_COMPARISONS`` and ``_METHODS``; a test evaluates and checks
+    the same expressions so a form accepted by one cannot be rejected by the
+    other."""
+    if isinstance(node, ast.BoolOp):
+        for value in node.values:
+            _check(value, names)
+        return
+    if isinstance(node, ast.UnaryOp):
+        if not isinstance(node.op, (ast.Not, ast.USub, ast.UAdd)):
+            raise FilterError(f"unsupported operator '{type(node.op).__name__}'")
+        _check(node.operand, names)
+        return
+    if isinstance(node, ast.Compare):
+        _check(node.left, names)
+        for op, comparator in zip(node.ops, node.comparators):
+            if type(op) not in _COMPARISONS:
+                raise FilterError(f"unsupported comparison '{type(op).__name__}'")
+            _check(comparator, names)
+        return
+    if isinstance(node, ast.Name):
+        if node.id not in names:
+            raise FilterError(f"unknown name '{node.id}'")
+        return
+    if isinstance(node, ast.Constant):
+        return
+    if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
+        for element in node.elts:
+            _check(element, names)
+        return
+    if isinstance(node, ast.Subscript):
+        if isinstance(node.slice, ast.Slice):
+            raise FilterError("slices are not allowed in filters")
+        _check(node.value, names)
+        _check(node.slice, names)
+        return
+    if isinstance(node, ast.Call):
+        _check_call(node, names)
+        return
+    raise FilterError(f"unsupported expression '{type(node).__name__}'")
+
+
+def _check_call(node, names: frozenset[str]) -> None:
+    func = node.func
+    if not isinstance(func, ast.Attribute):
+        raise FilterError("only method calls on values are allowed")
+    if func.attr not in _METHODS:
+        raise FilterError(f"method '{func.attr}' is not allowed in filters")
+    if node.keywords:
+        raise FilterError("keyword arguments are not allowed in filters")
+    _check(func.value, names)
+    for arg in node.args:
+        _check(arg, names)
+
+
 def safe_eval(expr: str, namespace: dict) -> object:
     """Evaluate one filter expression against ``namespace`` without eval/exec.
 

{throughline-2.2.0 → throughline-2.2.1}/src/throughline/schema.py

@@ -19,8 +19,16 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
+from .filters import FilterError, check_filter
+
 ERROR, WARNING, OFF = "error", "warning", "off"
 
+# What a coverage rule's `needs` clause looks like: a direction and a link type
+# (SR-0042). Declared here because this is where a rule is admitted or refused;
+# validation reads the same pattern, so the clause the loader accepts and the
+# clause the gate acts on can never be two different things.
+COVERAGE_NEEDS_RE = re.compile(r"(incoming|outgoing):(\w+)$")
+
 # Grounding defaults when a project declares no [grounding] table. Kept here so
 # the grounding layer and the schema agree on one source of truth.
 _GROUNDING_DEFAULTS = {
@@ -53,6 +61,45 @@ class SchemaError(ValueError):
     """Malformed or internally inconsistent project configuration (SR-0082)."""
 
 
+def _check_coverage(coverage: tuple) -> None:
+    """Refuse a coverage rule that could not be enforced (SR-0191).
+
+    A rule the gate cannot run is the failure this exists to end: until now a
+    filter that raised matched nothing, so `check` reported the graph sound while
+    the rule asserted nothing at all. Checked here, at load, because the filter
+    language short-circuits — whether an unusable expression is reached depends on
+    which items the graph holds, so only a check made before any item is read
+    gives the same answer every time.
+    """
+    for pos, rule in enumerate(coverage):
+        where = f"[[rules.coverage]] #{pos + 1}"
+        if not isinstance(rule, dict):
+            raise SchemaError(f"{where} is not a table")
+        try:
+            check_filter(rule.get("filter") or "")
+        except FilterError as e:
+            raise SchemaError(
+                f"{where} has an unusable filter: {e}\n"
+                f"    filter = {rule.get('filter')!r}\n"
+                "  An item attribute is read with attrs.get('name'); `tl query "
+                "<EXPR>` tries an expression out.") from e
+        needs = rule.get("needs")
+        if needs is None:
+            raise SchemaError(
+                f"{where} declares no 'needs', so it requires nothing of the "
+                "items it matches; state it as 'incoming:<link type>' or "
+                "'outgoing:<link type>'")
+        if not COVERAGE_NEEDS_RE.match(str(needs).strip()):
+            raise SchemaError(
+                f"{where} has an unusable 'needs' clause {needs!r} — expected "
+                "'incoming:<link type>' or 'outgoing:<link type>'")
+        severity = rule.get("severity")
+        if severity is not None and severity not in (ERROR, WARNING, OFF):
+            raise SchemaError(
+                f"{where} has unknown severity {severity!r} (expected "
+                f"'{ERROR}', '{WARNING}' or '{OFF}')")
+
+
 @dataclass(frozen=True)
 class AttrSpec:
     """One declared attribute of an item type."""
@@ -182,6 +229,7 @@ class Schema:
 
         rules = config.get("rules") or {}
         coverage = tuple(rules.get("coverage", []) or [])
+        _check_coverage(coverage)
         rule_overrides = {k: v for k, v in rules.items() if k != "coverage"}
 
         docs_paths = tuple((config.get("docs") or {}).get("paths", []) or [])

{throughline-2.2.0 → throughline-2.2.1}/src/throughline/schema_ops.py

@@ -492,3 +492,55 @@ def attr_remove(project: Project, itype: str, name: str) -> Change:
 def _remove_attr(doc: TomlDocument, itype: str, name: str, why: str) -> None:
     doc.remove_key(f"types.{itype}", f"attrs.{name}")
     doc.note_table(f"types.{itype}", why)
+
+
+# `coverage` is the only kind of rule declared as a table under [rules] (SR-0192).
+# Every other key there names a validation rule and sets its severity — a
+# different shape, with a meaning of its own — so these verbs are defined for
+# coverage alone rather than for a generality that does not exist.
+_COVERAGE = ("rules", "coverage")
+
+
+def _coverage(project: Project) -> list[dict]:
+    return list((project.config.get("rules") or {}).get("coverage") or [])
+
+
+def rule_add(project: Project, *, filter: str, needs: str,
+             severity: str | None = None) -> Change:
+    """Declare a coverage rule. The filter and the needs clause are validated by
+    :meth:`Schema.from_config` before anything is written, in
+    :func:`apply_change` — which is the point of the operation: a rule the gate
+    could not enforce cannot reach the file (SR-0191, SR-0192)."""
+    rule: dict = {"filter": filter, "needs": needs}
+    if severity is not None:
+        rule["severity"] = severity
+    cfg = _copy(project)
+    rules = cfg.setdefault("rules", {})
+    existing = list(rules.get("coverage") or [])
+    if rule in existing:
+        raise SchemaOpError("that coverage rule is already declared")
+    rules["coverage"] = existing + [rule]
+    return Change(
+        f"adding a coverage rule: items matching {filter!r} need {needs}", cfg,
+        lambda doc, why: doc.add_array_table(_COVERAGE, rule, because=why))
+
+
+def rule_remove(project: Project, index: int) -> Change:
+    """Withdraw the ``index``-th coverage rule, counting from 1 as `tl context`
+    prints them. By position because a coverage rule has no name to be called
+    by, and the list is short and ordered."""
+    rules_list = _coverage(project)
+    if not rules_list:
+        raise SchemaOpError("this project declares no coverage rules")
+    if index < 1 or index > len(rules_list):
+        raise SchemaOpError(
+            f"this project declares {len(rules_list)} coverage rule(s); "
+            f"there is no #{index}")
+    doomed = rules_list[index - 1]
+    cfg = _copy(project)
+    cfg.setdefault("rules", {})["coverage"] = [
+        r for pos, r in enumerate(rules_list) if pos != index - 1]
+    return Change(
+        f"removing coverage rule #{index} (needs {doomed.get('needs')})", cfg,
+        lambda doc, why: doc.remove_array_table(_COVERAGE, index - 1,
+                                                because=why))

{throughline-2.2.0 → throughline-2.2.1}/src/throughline/storage.py

@@ -22,6 +22,17 @@ from typing import NamedTuple
 
 import yaml
 
+# One loader for every YAML the Tool reads (SR-0193). PyYAML's C loader parses the
+# same files about nine times faster than the pure-Python one and constructs the
+# same result; both are *safe* loaders that build no Python objects (NFR-0022).
+# Chosen once here, so no module reads YAML by another route.
+_YAML_LOADER = getattr(yaml, "CSafeLoader", yaml.SafeLoader)
+
+
+def _load_yaml(text: str):
+    """Parse one YAML document safely, through the loader chosen above."""
+    return yaml.load(text, Loader=_YAML_LOADER)
+
 from .fingerprint import fingerprint
 from .graph import Index
 from .grounding import ratification_refusal
@@ -635,7 +646,7 @@ def _build_project(root: Path, config: dict, manifest_names: set[str]) -> Projec
     manifests = sorted(m for name in manifest_names for m in root.rglob(name))
     for manifest in manifests:
         reg_dir = manifest.parent
-        raw = yaml.safe_load(manifest.read_text(encoding="utf-8")) or {}
+        raw = _load_yaml(manifest.read_text(encoding="utf-8")) or {}
         reg = Register.from_manifest(raw, path=reg_dir)
         if reg.prefix in project.registers:
             # A second register folder claims a prefix already loaded. Keeping the
@@ -649,7 +660,7 @@ def _build_project(root: Path, config: dict, manifest_names: set[str]) -> Projec
         for item_file in sorted(reg_dir.glob("*.yml")):
             if item_file.name in manifest_names:
                 continue
-            d = yaml.safe_load(item_file.read_text(encoding="utf-8")) or {}
+            d = _load_yaml(item_file.read_text(encoding="utf-8")) or {}
             item = Item.from_dict(d, path=item_file)
             item._register_prefix = reg.prefix
             for msg in item._load_errors:
@@ -750,7 +761,7 @@ def baseline_statuses(project: Project, ref: str = "HEAD") -> dict[str, str] | N
                 capture_output=True, text=True, check=True).stdout
         except (subprocess.CalledProcessError, FileNotFoundError, OSError):
             continue  # not present at ref (new file) or bad ref for this path
-        data = yaml.safe_load(blob) or {}
+        data = _load_yaml(blob) or {}
         status = data.get("status")
         if isinstance(status, str):
             out[item.uid] = status
@@ -787,7 +798,7 @@ def baseline_statuses(project: Project, ref: str = "HEAD") -> dict[str, str] | N
                 capture_output=True, text=True, check=True).stdout
         except (subprocess.CalledProcessError, FileNotFoundError, OSError):
             continue
-        data = yaml.safe_load(blob) or {}
+        data = _load_yaml(blob) or {}
         uid, status = data.get("uid"), data.get("status")
         if isinstance(uid, str) and isinstance(status, str):
             out.setdefault(uid, status)

{throughline-2.2.0 → throughline-2.2.1}/src/throughline/tomledit.py

@@ -342,6 +342,52 @@ class TomlDocument:
         start, end = span
         del self._lines[self._comment_start(start, -1):end]
 
+    def array_table_spans(self,
+                          name: str | tuple[str, ...]) -> list[tuple[int, int]]:
+        """``(header_index, end)`` for each ``[[name]]`` block, in file order.
+        ``end`` is exclusive and stops at the next header of any kind."""
+        want = _as_path(name)
+        headers = self._headers()
+        return [(idx, headers[pos + 1][0] if pos + 1 < len(headers)
+                 else len(self._lines))
+                for pos, (idx, found, is_array) in enumerate(headers)
+                if found == want and is_array]
+
+    def add_array_table(self, name: str | tuple[str, ...], values: dict, *,
+                        because: str | None = None) -> None:
+        """Append a ``[[name]]`` block holding ``values``.
+
+        Appended rather than written in place, because the members of an
+        array-of-tables are ordered and the ones already there are not this
+        change's business — the same reason :meth:`add_to_array` writes at the
+        end of an array (SR-0183)."""
+        written = _render_path(_as_path(name))
+        body: list[str] = []
+        for key, value in values.items():
+            body.extend(render_assignment(key, value))
+        note = comment_block(because) if because else []
+        tail = [""] if self._lines and self._lines[-1].strip() else []
+        self._lines.extend(tail + note + [f"[[{written}]]"] + body)
+
+    def remove_array_table(self, name: str | tuple[str, ...], index: int, *,
+                           because: str | None = None) -> None:
+        """Remove the ``index``-th (0-based) ``[[name]]`` block, taking the
+        comment that introduced it with it.
+
+        ``because`` is left behind in the block's place. A removal has no key or
+        table left to hang its reason on, and the gap where the rule used to be
+        is the one spot where a reader looking for it will pass (SR-0184)."""
+        spans = self.array_table_spans(name)
+        written = _render_path(_as_path(name))
+        if index < 0 or index >= len(spans):
+            raise TomlEditError(
+                f"this document has {len(spans)} [[{written}]] block(s); "
+                f"there is no #{index + 1}")
+        start, end = spans[index]
+        floor = spans[index - 1][1] - 1 if index else -1
+        at = self._comment_start(start, floor)
+        self._lines[at:end] = comment_block(because) if because else []
+
     def note_table(self, name: str | tuple[str, ...], because: str) -> None:
         """Record ``because`` above the header of an existing table."""
         span = self._table_span(name)

{throughline-2.2.0 → throughline-2.2.1}/src/throughline/validate.py

@@ -15,7 +15,7 @@ from .fingerprint import fingerprint
 from .filters import FilterError, safe_eval
 from .graph import Index
 from .grounding import reaches_root
-from .schema import ERROR, OFF, WARNING
+from .schema import COVERAGE_NEEDS_RE, ERROR, OFF, WARNING
 from .storage import CONFIG_NAME, FORMAT_VERSION, STATUS_ROLES_MAJOR
 from .uid import UID_RE, collisions
 
@@ -54,6 +54,10 @@ _DEFAULT_SEVERITY = {
     "ambiguous": WARNING, "coverage": WARNING, "vague-word": WARNING,
     "unpublished": WARNING,
 }
+# `rule-filter` is deliberately absent above. Every rule there describes a
+# judgement a project may reasonably make differently; a coverage rule that
+# cannot be evaluated is not one of those. Silencing it would restore exactly the
+# inert gate SR-0191 exists to expose, with nothing to tell it from a live one.
 
 def _file(item) -> str:
     return str(item._path) if item._path else ""
@@ -352,10 +356,18 @@ def _coverage_rules(project, idx: Index, strict: bool) -> list[Finding]:
     incoming/outgoing link of a given type."""
     findings: list[Finding] = []
     schema = project.schema
-    for rule in schema.coverage:
+    cfg_file = str(project.path / CONFIG_NAME)
+    for pos, rule in enumerate(schema.coverage):
         needs = rule.get("needs", "")
-        m = re.match(r"(incoming|outgoing):(\w+)", needs)
+        m = COVERAGE_NEEDS_RE.match(str(needs).strip())
         if not m:
+            # Unreachable through a loaded project — Schema.from_config refuses a
+            # rule this malformed (SR-0191). Reported rather than skipped so a
+            # schema built by hand cannot reintroduce the silent inert rule.
+            findings.append(Finding(
+                "rule-filter", ERROR, "", cfg_file,
+                f"[[rules.coverage]] #{pos + 1} has an unusable 'needs' clause "
+                f"{needs!r}"))
             continue
         direction, ltype = m.group(1), m.group(2)
         sev = rule.get("severity", WARNING)
@@ -363,8 +375,23 @@ def _coverage_rules(project, idx: Index, strict: bool) -> list[Finding]:
             sev = ERROR
         if sev == OFF:
             continue
+        expr = rule.get("filter", "")
         for item in project.items():
-            if item.is_deleted or not _match_filter(item, rule.get("filter", ""), idx):
+            if item.is_deleted:
+                continue
+            try:
+                matched = eval_filter(item, expr, idx)
+            except FilterError as e:
+                # The rule cannot be enforced. Reported once, as an error, and the
+                # rule abandoned: a filter that raises used to be read as 'matches
+                # nothing', which left the gate asserting nothing while check
+                # printed that the graph was sound (SR-0191).
+                findings.append(Finding(
+                    "rule-filter", ERROR, "", cfg_file,
+                    f"[[rules.coverage]] #{pos + 1} ({needs}) could not be "
+                    f"evaluated against {item.uid}: {e} — filter = {expr!r}"))
+                break
+            if not matched:
                 continue
             links = (idx.in_links(item.uid, {ltype}) if direction == "incoming"
                      else idx.out_links(item.uid, {ltype}))
@@ -403,7 +430,9 @@ class _LinkView:
 def _filter_namespace(item, idx: Index | None = None) -> dict:
     """The one set of names an SR-0045 filter can reference (grammar: SR-0104).
     Shared by coverage rules, the `query` CLI, and document injection so the
-    language is identical in all three."""
+    language is identical in all three. The keys are exactly
+    :data:`throughline.filters.FILTER_NAMES`, which is what the static check
+    validates against; a test holds the two together."""
     return {
         "type": item.type, "status": item.status, "register": item._register_prefix,
         "uid": item.uid, "derived": item.derived, "normative": item.normative,
@@ -425,15 +454,6 @@ def eval_filter(item, expr: str, idx: Index | None = None) -> bool:
     return bool(safe_eval(expr, _filter_namespace(item, idx)))
 
 
-def _match_filter(item, expr: str, idx: Index | None = None) -> bool:
-    """Lenient variant for config-declared coverage rules: a malformed rule
-    filter simply fails to match rather than aborting the whole check."""
-    try:
-        return eval_filter(item, expr, idx)
-    except FilterError:
-        return False
-
-
 def is_external(target: str) -> bool:
     """True if a link target is a free external reference — a URL, a repository path,
     or an anchor (SR-0031) — that the graph deliberately leaves opaque. Public so a

{throughline-2.2.0 → throughline-2.2.1/src/throughline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 2.2.0
+Version: 2.2.1
 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.
 Author-email: Henry J Grech-Cini <henry.grechcini@gmail.com>
 License-Expression: Apache-2.0
@@ -36,7 +36,7 @@ version control; a `check` command validates the whole graph and gates CI.
 
 **Dogfooded:** throughline's own spec is itself a throughline project —
 <!-- tl:count type == 'system_requirement' -->
-156
+159
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 25

{throughline-2.2.0 → throughline-2.2.1}/src/throughline.egg-info/SOURCES.txt

@@ -30,4 +30,5 @@ tests/test_doctor.py
 tests/test_engine.py
 tests/test_filters.py
 tests/test_ratify_status.py
-tests/test_schema_ops.py
+tests/test_schema_ops.py
+tests/test_yaml_loader.py

{throughline-2.2.0 → throughline-2.2.1}/tests/test_engine.py

@@ -569,6 +569,58 @@ def test_coverage_rule_needs_incoming_link():
     assert ("FR-1", "coverage") in _rules(validate(p))
 
 
+def test_coverage_rule_with_an_unusable_filter_is_refused_at_load():
+    """SR-0191. The filter names a bare attribute where the language requires
+    attrs.get(...). Before this, the rule matched no item, check reported the
+    graph sound, and the gate asserted nothing at all."""
+    with pytest.raises(SchemaError, match="unknown name 'verification'"):
+        Schema.from_config({"rules": {"coverage": [
+            {"filter": "type == 'requirement' and verification == 'test'",
+             "needs": "incoming:verifies"}]}})
+
+
+def test_coverage_rule_refusal_names_the_rule_and_the_expression():
+    """SR-0191. A refusal that does not say which rule sends its reader off to
+    read the whole file."""
+    with pytest.raises(SchemaError) as e:
+        Schema.from_config({"rules": {"coverage": [
+            {"filter": "true", "needs": "incoming:verifies"},
+            {"filter": "nope == 1", "needs": "incoming:verifies"}]}})
+    assert "#2" in str(e.value)
+    assert "nope == 1" in str(e.value)
+
+
+def test_coverage_rule_with_an_unusable_needs_clause_is_refused():
+    """SR-0191. An unparseable `needs` was skipped, which left the rule inert in
+    exactly the way a broken filter did."""
+    for needs in ("verifies", "sideways:verifies", None):
+        rule = {"filter": "true"}
+        if needs is not None:
+            rule["needs"] = needs
+        with pytest.raises(SchemaError):
+            Schema.from_config({"rules": {"coverage": [rule]}})
+
+
+def test_coverage_rule_with_an_unknown_severity_is_refused():
+    """SR-0191. A misspelt severity is neither error, warning nor off, so the
+    finding it produced could be neither counted nor silenced."""
+    with pytest.raises(SchemaError, match="severity"):
+        Schema.from_config({"rules": {"coverage": [
+            {"filter": "true", "needs": "incoming:verifies",
+             "severity": "eror"}]}})
+
+
+def test_a_filter_that_raises_at_evaluation_is_an_error_not_a_non_match():
+    """SR-0191. The static check cannot see every failure — comparing values
+    whose types do not compare depends on the data. Reaching past the load-time
+    refusal is how that residue is exercised."""
+    p = _grounded_project()
+    p.schema.coverage = ({"filter": "attrs.get('missing') > 1",
+                          "needs": "incoming:verifies"},)
+    assert any(f.rule == "rule-filter" and f.severity == "error"
+               for f in validate(p))
+
+
 # ---------------------------------------------------------------------- schema
 
 def test_schema_helpers_are_the_single_source(tmp_path):

{throughline-2.2.0 → throughline-2.2.1}/tests/test_filters.py

@@ -10,10 +10,10 @@ from __future__ import annotations
 
 import pytest
 
-from throughline.filters import FilterError, safe_eval
+from throughline.filters import FILTER_NAMES, FilterError, check_filter, safe_eval
 from throughline.graph import Index
 from throughline.model import Item, Link
-from throughline.validate import eval_filter
+from throughline.validate import _filter_namespace, eval_filter
 
 NS = {
     "uid": "SR-0045", "type": "system_requirement", "status": "approved",
@@ -167,3 +167,63 @@ def test_outgoing_and_to_work_without_index():
     _, _, it = _link_graph()
     assert eval_filter(it["SR-0001"], "links.outgoing('implements')", None)
     assert eval_filter(it["SR-0001"], "links.to('UR-0001')", None)
+
+
+# ------------------------------------------- static validation (SR-0191)
+
+def test_check_filter_accepts_what_eval_accepts():
+    """The static check and the evaluator walk one grammar. Every form the
+    evaluator runs must pass the check, or a legal filter would be refused at
+    load for being legal."""
+    for expr in (
+            "type == 'system_requirement'",
+            "attrs.get('priority') == 'must'",
+            "not normative or derived",
+            "status in ['approved', 'ratified']",
+            "attrs['score'] > 2",
+            "title.lower().startswith('filter')",
+            "'security' in attrs.get('tags')",
+            "uid == 'SR-0045' and (title != none)",
+    ):
+        check_filter(expr)          # must not raise
+        safe_eval(expr, NS)         # and must still evaluate
+
+
+def test_check_filter_rejects_a_bare_attribute_name():
+    """The defect this exists for: `verification == 'test'` instead of
+    `attrs.get('verification')`. The evaluator already knew; nothing asked it."""
+    with pytest.raises(FilterError, match="unknown name 'verification'"):
+        check_filter("verification == 'test'")
+
+
+def test_check_filter_sees_past_a_short_circuit():
+    """Why the check is static. Evaluation never reaches the misspelling for an
+    item whose type does not match, so an evaluation-time check would report
+    soundness or breakage depending on which items the graph happened to hold."""
+    expr = "type == 'nfr' and verifcation == 'test'"
+    # The evaluator, given a non-matching item, short-circuits and reports False.
+    assert safe_eval(expr, NS) is False
+    # The static check reads the whole expression and is not fooled.
+    with pytest.raises(FilterError, match="unknown name 'verifcation'"):
+        check_filter(expr)
+
+
+def test_check_filter_rejects_syntax_methods_and_forms():
+    for expr, message in (
+            ("type == ", "could not parse"),
+            ("title.format('{0.__class__}')", "not allowed"),
+            ("attrs.get('a', b=1)", "keyword arguments"),
+            ("title[0:2] == 'ab'", "slices are not allowed"),
+            ("__import__('os')", "only method calls"),
+            ("lambda: 1", "unsupported expression"),
+    ):
+        with pytest.raises(FilterError, match=message):
+            check_filter(expr)
+
+
+def test_filter_names_are_exactly_the_runtime_namespace():
+    """The static check validates against FILTER_NAMES; the evaluator reads the
+    namespace `_filter_namespace` builds. If they drift, the check either refuses
+    a legal filter or admits one that raises at evaluation."""
+    item = Item(uid="SR-0001", type="system_requirement", title="t")
+    assert set(_filter_namespace(item)) == set(FILTER_NAMES)

{throughline-2.2.0 → throughline-2.2.1}/tests/test_schema_ops.py

@@ -283,3 +283,89 @@ def test_a_change_the_schema_itself_rejects_is_a_usage_error(tmp_path):
                  "--because", "No longer used."])
 
     assert code == 2
+
+
+# ------------------------------------------- coverage rules (SR-0192)
+
+def test_a_coverage_rule_can_be_added_and_records_why(tmp_path):
+    """SR-0192. `[[rules.coverage]]` was the one part of the schema with no verb,
+    so a project wanting a rule other than the seeded one had to edit the file."""
+    root = _scaffold(tmp_path)
+    code = _cli(["-C", str(root), "schema", "rule", "add",
+                 "--filter", "type == 'requirement' and status != 'deleted'",
+                 "--needs", "incoming:verifies",
+                 "--because", "A requirement nothing tests is not finished."])
+
+    assert code == 0
+    rules = _config(root)["rules"]["coverage"]
+    assert {"filter": "type == 'requirement' and status != 'deleted'",
+            "needs": "incoming:verifies"} in rules
+    assert "A requirement nothing tests" in (root / "throughline.toml").read_text()
+
+
+def test_adding_a_rule_whose_filter_cannot_be_evaluated_is_refused(tmp_path):
+    """SR-0191 and SR-0192 together: this is why the verb exists. The expression
+    is the one that made a real project's gate inert — a bare attribute name
+    where the language requires attrs.get(...). It must not reach the file."""
+    root = _scaffold(tmp_path)
+    before = (root / "throughline.toml").read_text()
+
+    code = _cli(["-C", str(root), "schema", "rule", "add",
+                 "--filter", "type == 'requirement' and verification == 'test'",
+                 "--needs", "incoming:verifies",
+                 "--because", "Tested requirements need a test."])
+
+    assert code == 2
+    assert (root / "throughline.toml").read_text() == before
+
+
+def test_adding_a_rule_with_an_unusable_needs_clause_is_refused(tmp_path):
+    root = _scaffold(tmp_path)
+    before = (root / "throughline.toml").read_text()
+    code = _cli(["-C", str(root), "schema", "rule", "add",
+                 "--filter", "type == 'requirement'", "--needs", "verifies",
+                 "--because", "x"])
+    assert code == 2
+    assert (root / "throughline.toml").read_text() == before
+
+
+def test_a_coverage_rule_can_be_removed_by_position(tmp_path):
+    """SR-0192. A coverage rule has no name to be called by, so it is withdrawn
+    by the position `tl context` prints it at."""
+    root = _scaffold(tmp_path)
+    base = len(_config(root).get("rules", {}).get("coverage", []))
+    for ltype in ("verifies", "implements"):
+        assert _cli(["-C", str(root), "schema", "rule", "add",
+                     "--filter", f"type == '{ltype}-ish'",
+                     "--needs", f"incoming:{ltype}",
+                     "--because", f"Cover {ltype}."]) == 0
+    assert len(_config(root)["rules"]["coverage"]) == base + 2
+
+    code = _cli(["-C", str(root), "schema", "rule", "remove", str(base + 1),
+                 "--because", "Superseded by the second rule."])
+
+    assert code == 0
+    remaining = _config(root)["rules"]["coverage"]
+    assert len(remaining) == base + 1
+    assert remaining[-1]["needs"] == "incoming:implements"
+    # The reason survives the thing it explains (SR-0184).
+    assert "Superseded by the second rule." in (root / "throughline.toml").read_text()
+
+
+def test_removing_a_rule_that_is_not_there_is_a_usage_error(tmp_path):
+    root = _scaffold(tmp_path)
+    beyond = len(_config(root).get("rules", {}).get("coverage", [])) + 1
+    assert _cli(["-C", str(root), "schema", "rule", "remove", str(beyond),
+                 "--because", "x"]) == 2
+
+
+def test_adding_a_rule_leaves_the_rest_of_the_file_alone(tmp_path):
+    """SR-0183. An array-of-tables is appended, so no existing block moves."""
+    root = _scaffold(tmp_path)
+    before = (root / "throughline.toml").read_text()
+    assert _cli(["-C", str(root), "schema", "rule", "add",
+                 "--filter", "type == 'requirement'",
+                 "--needs", "incoming:verifies",
+                 "--because", "Requirements need tests."]) == 0
+    after = (root / "throughline.toml").read_text()
+    assert after.startswith(before.rstrip("\n"))

throughline-2.2.1/tests/test_yaml_loader.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2026 Henry J Grech-Cini
+# SPDX-License-Identifier: Apache-2.0
+"""SR-0193: one safe loader for every YAML read, the C one where PyYAML has it."""
+from __future__ import annotations
+
+import yaml
+import pytest
+
+from throughline import storage
+from throughline.cli import main as cli
+
+
+def _dump(root) -> str:
+    """The project as `tl dump` prints it — the whole parsed graph as one string."""
+    import io
+    from contextlib import redirect_stdout
+
+    out = io.StringIO()
+    with redirect_stdout(out):
+        code = cli(["-C", str(root), "dump"])
+    assert code == 0
+    return out.getvalue()
+
+
+def test_the_c_loader_is_used_when_libyaml_is_present():
+    if yaml.__with_libyaml__:
+        assert storage._YAML_LOADER is yaml.CSafeLoader
+    else:  # pragma: no cover - depends on how PyYAML was built
+        assert storage._YAML_LOADER is yaml.SafeLoader
+
+
+def test_both_loaders_read_a_project_identically(tmp_path, monkeypatch):
+    root = tmp_path / "p"
+    root.mkdir()
+    assert cli(["-C", str(root), "init", "--name", "loader", "--no-demo"]) == 0
+    assert cli(["-C", str(root), "new", "INT", "--type", "intent", "--origin", "human",
+                "--title", "Why", "--no-interactive"]) == 0
+    assert cli(["-C", str(root), "new", "REQ", "--type", "requirement", "--origin", "human",
+                "--ground", "INT-0001", "--ground-type", "derives_from",
+                "--title", "A title with: a colon, \"quotes\" and — a dash",
+                "--text", "Two\nlines", "--no-interactive"]) == 0
+    fast = _dump(root)
+    monkeypatch.setattr(storage, "_YAML_LOADER", yaml.SafeLoader)
+    slow = _dump(root)
+    assert fast == slow and '"REQ-0001"' in fast
+
+
+@pytest.mark.parametrize("loader", [yaml.SafeLoader] + ([yaml.CSafeLoader] if yaml.__with_libyaml__ else []))
+def test_a_python_object_tag_is_refused_by_either_loader(loader, monkeypatch):
+    monkeypatch.setattr(storage, "_YAML_LOADER", loader)
+    with pytest.raises(yaml.YAMLError):
+        storage._load_yaml("uid: !!python/object/apply:os.system ['echo owned']\n")