throughline 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 2.2.0
+Version: 2.3.0
 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,10 +36,10 @@ 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
+161
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-25
+26
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

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

@@ -8,10 +8,10 @@ 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
+161
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-25
+26
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "2.2.0"
+version = "2.3.0"
 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.3.0}/src/throughline/cli.py

@@ -20,6 +20,7 @@ from .graph import Index
 from .grounding import (
     GroundingError,
     invalidate,
+    ratification_obstacle,
     ratify,
     reaches_root,
     set_status,
@@ -47,7 +48,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 +1287,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 +1365,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",
 }
 
@@ -1694,6 +1696,75 @@ def cmd_subgraph(args) -> int:
     return OK
 
 
+def _render_for_ratification(project, item, *, emit) -> None:
+    """Put the item in front of the person about to sign it (SR-0195, UR-0029).
+
+    Not :func:`throughline.inject.render_item`: that renders Markdown for a
+    published document, and states every attribute alike. A ratifier is being asked
+    to judge, so this separates the normative attributes — the ones whose change
+    breaks the signature — from the rest, and names each grounding target so the
+    'why' reads as a sentence instead of a bare UID the reader has to go and look
+    up. Emitted on stderr like every other piece of guidance (SR-0120), leaving
+    stdout to the one line that says what was ratified.
+    """
+    schema = project.schema
+    emit("")
+    emit(f"{item.uid}  [{item.type}/{item.status}] {item.title}".rstrip())
+    for label, body in (("", item.text), ("rationale", item.rationale)):
+        if not body:
+            continue
+        emit("")
+        if label:
+            emit(f"{label}:")
+        for line in body.splitlines():
+            emit(f"  {line}" if line else "")
+    grounding = [ln for ln in (_ground_line(project, link, schema)
+                               for link in item.links) if ln]
+    emit("")
+    if grounding:
+        emit("grounded by:")
+        for line in grounding:
+            emit(f"  {line}")
+    else:
+        # A root needs no grounding and says so; anything else could not have got
+        # this far, since ratification_obstacle refuses an ungrounded item.
+        emit("grounded by: nothing — this is a root and justifies itself")
+    normative = [n for n in schema.normative_attrs(item.type) if n in item.attrs]
+    if normative:
+        emit("")
+        emit("normative attributes (a change here breaks this signature): "
+             + " · ".join(f"{n}={item.attrs[n]}" for n in normative))
+    emit("")
+
+
+def _ground_line(project, link, schema) -> str | None:
+    """One grounding link rendered with its target's title, or None for a link that
+    confers no grounding — those are context, not justification, and listing them
+    here would present a 'relates' neighbour as a reason the item exists."""
+    if link.type not in schema.ground_link_types:
+        return None
+    target = project.get(link.target)
+    if target is None:
+        return f"{link.type} {link.target}  (unresolved)"
+    return f"{link.type} {link.target}  [{target.type}/{target.status}] {target.title}".rstrip()
+
+
+def _confirm(question: str) -> bool:
+    """Ask a yes/no question on an interactive terminal, defaulting to no (SR-0195).
+
+    A confirmation is not a prompt for a value, so it has no flag behind it and
+    SR-0120's rule that a fully specified command is never prompted for one does
+    not reach it: the whole point is to stop a command that already says everything
+    it needs to say. Silence, EOF and anything unrecognised all decline — the
+    default must never be the irreversible answer.
+    """
+    try:
+        raw = input(f"{question} [y/N]: ").strip().lower()
+    except EOFError:
+        return False
+    return raw in ("y", "yes")
+
+
 def cmd_ratify(args) -> int:
     try:
         project = load_project(args.path)
@@ -1704,6 +1775,26 @@ def cmd_ratify(args) -> int:
     uid = _resolve_uid(project, args.uid, "ratify", "UID")
     if uid is None:
         return USAGE
+    item = project.get(uid)
+    if item is None:
+        return _err(f"{uid} does not exist")
+    # Refuse before rendering anything or asking anyone (SR-0195). The old order
+    # asked who was taking accountability and only then discovered that nothing
+    # could be signed, which taught that the prompt was a formality. The index is
+    # built once and handed to ratify, so the question asked here and the write
+    # below read the same graph.
+    idx = Index.build(project)
+    obstacle = ratification_obstacle(project.schema, idx, item)
+    if obstacle is not None:
+        return _err(obstacle)
+    # Ratifying is taking accountability, so the content comes before the signature
+    # (UR-0029) — and before the identity prompt, so the reader knows what they are
+    # being asked about while they are being asked. Non-interactive runs render
+    # nothing: there is no reader to serve, and output nobody reads is noise in CI.
+    interactive = _interactive()
+    if interactive:
+        _render_for_ratification(
+            project, item, emit=lambda line: print(line, file=sys.stderr))
     # Offer the identity this repository already signs commits with (SR-0156). It
     # is only ever a default: _resolve_value shows it and takes it on assent, and a
     # non-interactive session that names no ratifier is refused, not signed for.
@@ -1711,8 +1802,18 @@ def cmd_ratify(args) -> int:
                         default=default_ratifier(args.path))
     if by is None:
         return USAGE
+    # The stop that makes the rendering more than decoration, asked whether or not
+    # --by was supplied (SR-0195) — a fully specified command is exactly how a bulk
+    # or habitual ratification is run, and display without a stop is a warning that
+    # scrolled past. SR-0120 permits it: confirming an act is not prompting for a
+    # value. Declining writes nothing and is not an error; the user was asked and
+    # answered.
+    if interactive and not _confirm(f"ratify {uid} as {by}?"):
+        print("not ratified", file=sys.stderr)
+        return OK
     try:
-        item = ratify(project, uid, by=by, by_id=getattr(args, "by_id", None))
+        item = ratify(project, uid, by=by, index=idx,
+                      by_id=getattr(args, "by_id", None))
     except IdentityError as e:
         return _err(str(e))
     except (ProjectError, GroundingError, SchemaError) as e:
@@ -1814,6 +1915,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 +2030,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.3.0}/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.3.0}/src/throughline/grounding.py

@@ -67,6 +67,33 @@ def ratification_refusal(schema, idx: Index, item: Item) -> str | None:
     return None
 
 
+def ratification_obstacle(schema, idx: Index, item: Item) -> str | None:
+    """Why :func:`ratify` would refuse ``item`` as the graph now stands, or ``None``
+    when it would proceed — the whole precondition set, asked without writing
+    anything (SR-0195).
+
+    ratify must refuse an item it cannot accept *before* a front end renders it or
+    asks anyone to confirm it, so "may this be signed?" has to be answerable ahead
+    of the act. :func:`ratify` answers it through this same function rather than
+    repeating the conditions, so the refusal a user is shown early is by
+    construction the refusal the write would have raised. It is a superset of
+    :func:`ratification_refusal`, which stays the narrower "must never be signed"
+    predicate the migration repair binds against (SR-0152) — an unstamped record
+    is exactly what that repair exists to complete, so it must not be told that an
+    already-ratified item has nothing to accept."""
+    refusal = ratification_refusal(schema, idx, item)
+    if refusal is not None:
+        return refusal
+    already = (item.status == schema.status_role("ratified")
+               if schema.ratify_moves_status
+               else item.attrs.get(RATIFIED_BY_ATTR) is not None)
+    if already and item.attrs.get("ratified_fingerprint") == fingerprint(item, schema):
+        return (f"{item.uid} is already ratified by "
+                f"{item.attrs.get('ratified_by', 'a human')} and its content has "
+                "not changed since — there is nothing to accept")
+    return None
+
+
 def ratify(project, uid: str, by: str, *, index: Index | None = None,
            by_id: str | None = None) -> Item:
     """A human takes accountability. Refused for ambiguous or ungrounded items —
@@ -86,26 +113,15 @@ def ratify(project, uid: str, by: str, *, index: Index | None = None,
         raise GroundingError(f"{uid} does not exist")
     schema = project.schema
     idx = index if index is not None else Index.build(project)
-    refusal = ratification_refusal(schema, idx, item)
-    if refusal is not None:
-        raise GroundingError(refusal)
-    # Ratifying an already-ratified item whose content has not moved accepts
-    # nothing, and would replace the record of who accepted it leaving no trace
-    # that it changed (SR-0148). An item ratified before the stamp existed has
-    # none to compare against, so that first call is allowed through and stamps it.
+    # Every reason this may be refused, including that an already-ratified item
+    # whose content has not moved accepts nothing and would replace the record of
+    # who accepted it leaving no trace that it changed (SR-0148). An item ratified
+    # before the stamp existed has none to compare against, so that first call is
+    # allowed through and stamps it.
+    obstacle = ratification_obstacle(schema, idx, item)
+    if obstacle is not None:
+        raise GroundingError(obstacle)
     current = fingerprint(item, schema)
-    # "Already ratified" is read from whatever this project uses as the durable
-    # proof (SR-0172). Where ratification advances the item, that is the status, as
-    # it always has been. Where it does not, the status says nothing about sign-off
-    # and the record itself is the only honest witness.
-    already = (item.status == schema.status_role("ratified")
-               if schema.ratify_moves_status
-               else item.attrs.get(RATIFIED_BY_ATTR) is not None)
-    if already and item.attrs.get("ratified_fingerprint") == current:
-        raise GroundingError(
-            f"{uid} is already ratified by "
-            f"{item.attrs.get('ratified_by', 'a human')} and its content has not "
-            "changed since — there is nothing to accept")
     # Advancing is the default, and is transition-validated — an item that cannot
     # legally reach the ratified status is refused rather than moved illegally. A
     # project that binds the ratified role to a workflow state turns this off, and

{throughline-2.2.0 → throughline-2.3.0}/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.3.0}/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.3.0}/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.3.0}/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)