throughline 3.2.0__tar.gz → 3.3.0__tar.gz

{throughline-3.2.0/src/throughline.egg-info → throughline-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.2.0
+Version: 3.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' -->
-164
+165
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-28
+29
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

{throughline-3.2.0 → throughline-3.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' -->
-164
+165
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-28
+29
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

{throughline-3.2.0 → throughline-3.3.0}/pyproject.toml

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

@@ -1784,91 +1784,115 @@ def _confirm(question: str) -> bool:
 
 
 def cmd_ratify(args) -> int:
+    """Ratify one or more items (SR-0199). Every item named is checked before any
+    is rendered or signed, so a run that cannot complete writes nothing; the
+    ratifier is asked once; each item is then shown and confirmed on its own,
+    because the signature is per item (UR-0029)."""
     try:
         project = load_project(args.path)
     except ProjectError as e:
         return _err(str(e))
-    # A proposed item is the usual target, but ratify tolerates any item (the
-    # grounding layer decides what it means), so the picker lists all live items.
-    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.
+    uids = list(args.uids)
+    if not uids:
+        # A proposed item is the usual target, but ratify tolerates any item (the
+        # grounding layer decides what it means), so the picker lists all live items.
+        uid = _resolve_uid(project, None, "ratify", "UID")
+        if uid is None:
+            return USAGE
+        uids = [uid]
+    # Refuse before rendering anything or asking anyone (SR-0195), and for the
+    # whole run before any item in it (SR-0199). 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 writes below read the same graph.
     idx = Index.build(project)
-    obstacle = ratification_obstacle(project.schema, idx, item,
-                                     replacing=args.replacing)
-    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.
+    items = []
+    for uid in uids:
+        item = project.get(uid)
+        if item is None:
+            return _err(f"{uid} does not exist")
+        obstacle = ratification_obstacle(project.schema, idx, item,
+                                         replacing=args.replacing)
+        if obstacle is not None:
+            return _err(obstacle if len(uids) == 1
+                        else f"{obstacle} — nothing in this run was ratified")
+        items.append(item)
     # Resolved once, before anything is shown, so the difference put in front of
     # the ratifier and the gate below are the same answer (SR-0165).
-    change = change_since_ratification(project, item)
+    changes = {item.uid: change_since_ratification(project, item) for item in items}
     interactive = _interactive()
-    if interactive:
-        _render_for_ratification(
-            project, item, emit=lambda line: print(line, file=sys.stderr))
+    if not interactive:
+        for item in items:
+            if changes[item.uid].stale and not args.accept_change:
+                return _err(
+                    f"{item.uid} has changed since "
+                    f"{item.attrs.get(RATIFIED_BY_ATTR, 'a human')} ratified it and this "
+                    "session cannot show you what changed — pass --accept-change to "
+                    "record a signature over a change accepted unseen, or run this on "
+                    "a terminal to see it first")
     # 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.
-    by = _resolve_value(args.by, "ratifier", "--by",
-                        default=default_ratifier(args.path))
-    if by is None:
-        return USAGE
-    # Re-ratifying is taking accountability afresh, so what moved since the last
-    # signature goes in the path of this one (SR-0167). Placed after the item and
-    # immediately before the stop, because that is where a reader is deciding.
-    # Unresolvable stops harder rather than passing quietly: letting the least
-    # knowable case through would make it the easiest one to sign, which is the
-    # failure this guards, arriving by the back door.
-    if change.stale:
+    # Asked once for the run — the person does not change between items — and on a
+    # terminal not until the first item has been shown, so the reader knows what
+    # they are being asked about while they are being asked (UR-0029, SR-0195).
+    by = None
+    if not interactive:
+        by = _resolve_value(args.by, "ratifier", "--by",
+                            default=default_ratifier(args.path))
+        if by is None:
+            return USAGE
+    rc = OK
+    for item in items:
+        uid = item.uid
+        change = changes[uid]
+        # Ratifying is taking accountability, so the content comes before the
+        # signature (UR-0029). Non-interactive runs render nothing: there is no
+        # reader to serve, and output nobody reads is noise in CI.
         if interactive:
-            # Painted as git would paint it: colour on a terminal, none when the
-            # reader has asked for none (NO_COLOR, https://no-color.org).
-            for line in render_change(
-                    change, ratifier=item.attrs.get(RATIFIED_BY_ATTR),
-                    columns=shutil.get_terminal_size((80, 24)).columns,
-                    colour=not os.environ.get("NO_COLOR")):
-                print(line, file=sys.stderr)
-            print("", file=sys.stderr)
-        elif not args.accept_change:
-            return _err(
-                f"{uid} has changed since {item.attrs.get(RATIFIED_BY_ATTR, 'a human')} "
-                "ratified it and this session cannot show you what changed — pass "
-                "--accept-change to record a signature over a change accepted "
-                "unseen, or run this on a terminal to see it first")
-    # 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.
-    question = (f"replace the ratifier recorded on {uid} with {by}?"
-                if args.replacing else f"ratify {uid} as {by}?")
-    if interactive and not _confirm(question):
-        print("not ratified", file=sys.stderr)
-        return OK
-    try:
-        item = ratify(project, uid, by=by, index=idx,
-                      by_id=getattr(args, "by_id", None),
-                      replacing=args.replacing)
-    except IdentityError as e:
-        return _err(str(e))
-    except (ProjectError, GroundingError, SchemaError) as e:
-        return _err(str(e))
-    write_item(item, project.register_of(item.uid))
-    identifier = item.attrs.get(RATIFIED_ID_ATTR)
-    print(f"{uid} ratified by {by}" + (f" ({identifier})" if identifier else ""))
-    return OK
+            _render_for_ratification(
+                project, item, emit=lambda line: print(line, file=sys.stderr))
+            # Re-ratifying is taking accountability afresh, so what moved since the
+            # last signature goes in the path of this one (SR-0167). Placed after the
+            # item and immediately before the stop, because that is where a reader
+            # is deciding. Painted as git would paint it: colour on a terminal, none
+            # when the reader has asked for none (NO_COLOR, https://no-color.org).
+            if change.stale:
+                for line in render_change(
+                        change, ratifier=item.attrs.get(RATIFIED_BY_ATTR),
+                        columns=shutil.get_terminal_size((80, 24)).columns,
+                        colour=not os.environ.get("NO_COLOR")):
+                    print(line, file=sys.stderr)
+                print("", file=sys.stderr)
+            # 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 for this item and is not an error; the user was asked and
+            # answered, and the run goes on to the next item (SR-0199).
+            if by is None:
+                by = _resolve_value(args.by, "ratifier", "--by",
+                                    default=default_ratifier(args.path))
+                if by is None:
+                    return USAGE
+            question = (f"replace the ratifier recorded on {uid} with {by}?"
+                        if args.replacing else f"ratify {uid} as {by}?")
+            if not _confirm(question):
+                print(f"{uid} not ratified", file=sys.stderr)
+                continue
+        try:
+            item = ratify(project, uid, by=by, index=idx,
+                          by_id=getattr(args, "by_id", None),
+                          replacing=args.replacing)
+        except IdentityError as e:
+            return _err(str(e))
+        except (ProjectError, GroundingError, SchemaError) as e:
+            return _err(str(e))
+        write_item(item, project.register_of(item.uid))
+        identifier = item.attrs.get(RATIFIED_ID_ATTR)
+        print(f"{uid} ratified by {by}" + (f" ({identifier})" if identifier else ""))
+    return rc
 
 
 def cmd_invalidate(args) -> int:
@@ -2329,8 +2353,12 @@ def build_parser() -> argparse.ArgumentParser:
     s.set_defaults(func=cmd_subgraph)
 
     s = sub.add_parser("ratify", help="a human takes accountability for an item")
-    s.add_argument("uid", nargs="?", default=None,
-                   help="UID to ratify (omit on a terminal to pick one)")
+    # A list, as withdraw's is (SR-0197): several proposed items are the usual
+    # shape of a machine-authored batch, and each is still shown and confirmed on
+    # its own (SR-0199). A front end that read the single `uid` by name must now
+    # read `uids`.
+    s.add_argument("uids", nargs="*", metavar="UID",
+                   help="item(s) to ratify, in order (omit on a terminal to pick one)")
     s.add_argument("--by", default=None,
                    help="ratifier name (omit on a terminal to be prompted; "
                         "defaults to the identity this repository signs with)")

{throughline-3.2.0 → throughline-3.3.0/src/throughline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.2.0
+Version: 3.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' -->
-164
+165
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
-28
+29
 <!-- tl:end --> user requirements, and
 <!-- tl:count type == 'nfr' -->
 21

{throughline-3.2.0 → throughline-3.3.0}/src/throughline.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ tests/test_filters.py
 tests/test_ratification_change.py
 tests/test_ratification_withdrawal.py
 tests/test_ratifier_correction.py
+tests/test_ratify_several.py
 tests/test_ratify_status.py
 tests/test_schema_ops.py
 tests/test_yaml_loader.py

throughline-3.3.0/tests/test_ratify_several.py

@@ -0,0 +1,94 @@
+"""Ratify takes several items in one run (UR-0032, SR-0199): every item is checked
+before any is signed, the ratifier is asked once, and each item is signed on its own.
+These run without a terminal, so the per-item rendering and stop are not exercised
+here; the single-item tests that cover them are unchanged in meaning."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from throughline.cli import main as cli_main
+from throughline.storage import load_project
+
+CONFIG_EXTRA = '''
+[types.intent]
+attrs.origin = { type = "enum", values = ["human", "ai", "hybrid"] }
+'''
+
+
+def _cli(argv) -> int:
+    return cli_main([str(a) for a in argv])
+
+
+@pytest.fixture
+def graph(tmp_path) -> Path:
+    """An intent and three proposed requirements grounded on it."""
+    root = tmp_path / "proj"
+    assert _cli(["-C", root, "init", "--no-demo"]) == 0
+    cfg = root / "throughline.toml"
+    cfg.write_text(cfg.read_text(encoding="utf-8") + CONFIG_EXTRA, encoding="utf-8")
+    assert _cli(["-C", root, "new", "INT", "--type", "intent", "--title", "Why",
+                 "--text", "V.", "--origin", "human", "--no-interactive"]) == 0
+    for n in ("R1", "R2", "R3"):
+        assert _cli(["-C", root, "new", "REQ", "--title", n, "--text",
+                     f"The Tool shall do {n}.", "--ground", "INT-0001",
+                     "--ground-type", "implements", "--origin", "ai",
+                     "--no-interactive"]) == 0
+    return root
+
+
+def _ratifiers(root: Path) -> dict[str, str | None]:
+    p = load_project(root)
+    return {u: p.get(u).attrs.get("ratified_by") for u in ("REQ-0001", "REQ-0002", "REQ-0003")}
+
+
+def test_several_items_are_ratified_in_one_run_in_the_order_given(graph, capsys):
+    assert _cli(["-C", graph, "ratify", "REQ-0002", "REQ-0001", "--by", "Ada Lovelace"]) == 0
+    out = capsys.readouterr().out.splitlines()
+    assert out == ["REQ-0002 ratified by Ada Lovelace", "REQ-0001 ratified by Ada Lovelace"]
+    assert _ratifiers(graph) == {"REQ-0001": "Ada Lovelace", "REQ-0002": "Ada Lovelace",
+                                 "REQ-0003": None}
+
+
+def test_one_item_still_works_as_before(graph, capsys):
+    assert _cli(["-C", graph, "ratify", "REQ-0003", "--by", "Ada Lovelace"]) == 0
+    assert capsys.readouterr().out.strip() == "REQ-0003 ratified by Ada Lovelace"
+
+
+def test_an_unknown_item_refuses_the_whole_run_before_anything_is_written(graph, capsys):
+    rc = _cli(["-C", graph, "ratify", "REQ-0001", "REQ-0009", "REQ-0002", "--by", "Ada"])
+    assert rc != 0
+    assert "REQ-0009 does not exist" in capsys.readouterr().err
+    assert _ratifiers(graph) == {"REQ-0001": None, "REQ-0002": None, "REQ-0003": None}
+
+
+def test_an_item_that_cannot_be_ratified_refuses_the_whole_run(graph, capsys):
+    """The obstacle is found for every item before any is signed (SR-0195 for the
+    run, not just the first item): here REQ-0002 is already signed by the same
+    content, which a plain re-ratification refuses."""
+    assert _cli(["-C", graph, "ratify", "REQ-0002", "--by", "Ada Lovelace"]) == 0
+    capsys.readouterr()
+    rc = _cli(["-C", graph, "ratify", "REQ-0001", "REQ-0002", "REQ-0003", "--by", "Ada Lovelace"])
+    assert rc != 0
+    err = capsys.readouterr().err
+    assert "REQ-0002" in err and "nothing in this run was ratified" in err
+    assert _ratifiers(graph) == {"REQ-0001": None, "REQ-0002": "Ada Lovelace", "REQ-0003": None}
+
+
+def test_a_stale_item_in_the_batch_refuses_the_run_without_accept_change(graph, capsys):
+    assert _cli(["-C", graph, "ratify", "REQ-0002", "--by", "Ada Lovelace"]) == 0
+    assert _cli(["-C", graph, "amend", "REQ-0002", "--text", "The Tool shall do R2 twice."]) == 0
+    capsys.readouterr()
+    rc = _cli(["-C", graph, "ratify", "REQ-0001", "REQ-0002", "--by", "Ada Lovelace"])
+    assert rc != 0
+    assert "--accept-change" in capsys.readouterr().err
+    assert _ratifiers(graph)["REQ-0001"] is None
+    assert _cli(["-C", graph, "ratify", "REQ-0001", "REQ-0002", "--by", "Ada Lovelace",
+                 "--accept-change"]) == 0
+    assert _ratifiers(graph)["REQ-0001"] == "Ada Lovelace"
+
+
+def test_no_item_off_a_terminal_is_a_usage_error(graph, capsys):
+    assert _cli(["-C", graph, "ratify", "--by", "Ada"]) == 2
+    assert "no item given to ratify" in capsys.readouterr().err