throughline 3.2.0__tar.gz → 3.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.2.0
+Version: 3.4.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
+166
 <!-- 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.4.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
+166
 <!-- 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.4.0}/pyproject.toml

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

@@ -629,6 +629,21 @@ def cmd_link(args) -> int:
         print(f"retyped {src_uid} {dst_uid}: --{old_type}--> is now --{ltype}-->"
               + (" (stamped)" if args.stamp else ""))
         return OK
+    # The same edge twice is never wanted: with --stamp it is the re-confirm
+    # command SR-0034 promises, refreshing the stored fingerprint in place;
+    # without it there is nothing to add, and a parallel duplicate would hide
+    # a stale stamp behind a fresh one.
+    same = [ln for ln in src.links if ln.target == dst_uid and ln.type == ltype]
+    if same:
+        if not args.stamp:
+            return _err(f"{src_uid} --{ltype}--> {dst_uid} already exists "
+                        f"(add --stamp to refresh its stamp, or --retype to "
+                        f"change its type)")
+        for ln in same:
+            ln.stamp = stamp
+        write_item(src, project.register_of(src.uid))
+        print(f"restamped {src_uid} --{ltype}--> {dst_uid}")
+        return OK
     src.links.append(Link(target=dst_uid, type=ltype, stamp=stamp))
     write_item(src, project.register_of(src.uid))
     print(f"linked {src_uid} --{ltype}--> {dst_uid}"
@@ -1784,91 +1799,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:
@@ -2205,7 +2244,7 @@ def build_parser() -> argparse.ArgumentParser:
     s.add_argument("--type", default=None,
                    help="link type (omit on a terminal to choose one)")
     s.add_argument("--stamp", action="store_true",
-                   help="record target fingerprint (suspect tracking)")
+                   help="record the target's fingerprint, or refresh it on an edge that already exists (suspect tracking)")
     s.add_argument("--retype", action="store_true",
                    help="change the type of the existing SRC -> DST link in "
                         "place instead of adding a new one")
@@ -2329,8 +2368,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.4.0}/src/throughline/ratification.py

@@ -26,7 +26,9 @@ and each of those deserves to be named rather than smoothed over.
 Results are returned as structured data, with rendering kept separate
 (:func:`render_change`). Every other surface that must show this — a composing
 consumer, a review cockpit — would otherwise re-parse formatted text, which is a
-second copy of the rule, drifting from the first.
+second copy of the rule, drifting from the first. The same holds one level down:
+a changed prose field's diff is data too (:func:`diff_prose`, SR-0200), and the
+terminal rendering here is one reader of it among others.
 """
 from __future__ import annotations
 
@@ -400,20 +402,46 @@ def _units(value: str) -> list[str]:
     return _SENTENCE_END.split(value) if value else [""]
 
 
-def _prose(was: object, now: object) -> bool:
+def is_prose(was: object, now: object) -> bool:
+    """Whether a changed field is shown as a diff (SR-0198): both values are
+    strings and at least one holds whitespace. A token — a priority, a flag — is
+    shown as before and after on one line instead."""
     return (isinstance(was, str) and isinstance(now, str)
             and any(ch.isspace() for ch in was + now))
 
 
 #: A word of a unit and whether it is among the words that moved.
-_Word = tuple[str, bool]
+Word = tuple[str, bool]
 
+#: The marks a unit of a prose diff carries, as a git diff marks its lines.
+KEPT, REMOVED, ADDED = " ", "-", "+"
 
-def _plain(unit: str) -> list[_Word]:
+
+@dataclass(frozen=True)
+class DiffUnit:
+    """One unit of a prose diff (SR-0200): a sentence, or a line where the value
+    has lines, marked :data:`KEPT`, :data:`REMOVED` or :data:`ADDED`, with each
+    word and whether it is among the words that moved. Words are marked only
+    between a removed sentence and the added one it plainly became; a unit
+    deleted, added or rewritten outright carries no marks."""
+    mark: str
+    words: tuple[Word, ...]
+
+    @property
+    def text(self) -> str:
+        return " ".join(w for w, _moved in self.words)
+
+    @property
+    def marked(self) -> bool:
+        """Whether any word of the unit is among the words that moved."""
+        return any(moved for _w, moved in self.words)
+
+
+def _plain(unit: str) -> list[Word]:
     return [(w, False) for w in unit.split()]
 
 
-def _word_marks(removed: str, added: str) -> tuple[list[_Word], list[_Word]]:
+def _word_marks(removed: str, added: str) -> tuple[list[Word], list[Word]]:
     """Both sides of a replaced sentence with the words that differ marked."""
     a, b = removed.split(), added.split()
     keep_a, keep_b = [False] * len(a), [False] * len(b)
@@ -433,7 +461,7 @@ _SAME_SENTENCE = 0.5
 
 
 def _pair_words(removed: list[str],
-                added: list[str]) -> tuple[list[list[_Word]], list[list[_Word]]]:
+                added: list[str]) -> tuple[list[list[Word]], list[list[Word]]]:
     """The units of one hunk with the words that moved marked, wherever a removed
     sentence has a successor it plainly became. Each removed sentence takes the
     most similar added one still free; a sentence with no counterpart — deleted
@@ -456,12 +484,36 @@ def _pair_words(removed: list[str],
     return marks_r, marks_a
 
 
-def _wrap(words: list[_Word], *, first: str, rest: str,
-          width: int) -> list[list[_Word]]:
-    """Greedy word wrap that never breaks a word, measured on the words alone
+def diff_prose(was: str, now: str) -> tuple[DiffUnit, ...]:
+    """The difference between two prose values as data (SR-0200). Kept units stay
+    in place, so a removed sentence sits above its replacement inside the
+    paragraph it belongs to, and removed units precede added ones within a hunk,
+    as they do in a git diff (SR-0198).
+
+    This is the one place the comparison is made. :func:`render_change` reads it
+    to paint a terminal, and a consumer with a screen of its own reads it too,
+    so the two can never disagree about what moved."""
+    a, b = _units(was), _units(now)
+    units: list[DiffUnit] = []
+    matcher = difflib.SequenceMatcher(None, a, b, autojunk=False)
+    for op, i1, i2, j1, j2 in matcher.get_opcodes():
+        if op == "equal":
+            units.extend(DiffUnit(KEPT, tuple(_plain(u))) for u in a[i1:i2])
+            continue
+        marks_r, marks_a = _pair_words(a[i1:i2], b[j1:j2])
+        units.extend(DiffUnit(REMOVED, tuple(w)) for w in marks_r)
+        units.extend(DiffUnit(ADDED, tuple(w)) for w in marks_a)
+    return tuple(units)
+
+
+def wrap_words(words: list[Word] | tuple[Word, ...], *, first: str, rest: str,
+               width: int) -> list[list[Word]]:
+    """Greedy word wrap of a unit's words that never breaks a word and keeps each
+    word's mark. ``first`` and ``rest`` are the prefixes the caller will draw
+    before the first and the later lines; the wrap is measured on the words alone
     so that painting a line afterwards cannot lengthen it past ``width``."""
-    lines: list[list[_Word]] = []
-    line: list[_Word] = []
+    lines: list[list[Word]] = []
+    line: list[Word] = []
     used = len(first)
     for word, moved in words:
         need = len(word) + (1 if line else 0)
@@ -478,14 +530,13 @@ def _wrap(words: list[_Word], *, first: str, rest: str,
 def _render_prose(field: str, was: str, now: str, *, pad: str,
                   columns: int, colour: bool) -> list[str]:
     """One field's change as its kept, removed and added units, each wrapped to
-    the terminal (SR-0198). Kept units stay in place so the reader sees the
-    removed sentence above its replacement, inside the paragraph it belongs to.
-    Removed units precede added ones within a hunk, as they do in a git diff."""
+    the terminal (SR-0198). Built from :func:`diff_prose` and nothing else
+    (SR-0200): what is painted here is exactly what the data says."""
     lines = [f"{pad}{field}:"]
     indent = pad * 2
     width = max(columns, 40)
 
-    def painted(wrapped: list[_Word]) -> str:
+    def painted(wrapped: list[Word]) -> str:
         # Consecutive moved words share one run, spaces included, so a reworded
         # phrase reads as a phrase and not as a row of blinking words.
         out: list[str] = []
@@ -506,27 +557,14 @@ def _render_prose(field: str, was: str, now: str, *, pad: str,
             out.append(_UNEMPHASIS)
         return "".join(out)
 
-    def emit(mark: str, words: list[_Word]) -> None:
-        first, rest = f"{indent}{mark} ", f"{indent}  "
-        paint = _PAINT[mark] if colour else ""
-        for n, wrapped in enumerate(_wrap(words, first=first, rest=rest,
-                                          width=width)):
+    for unit in diff_prose(was, now):
+        first, rest = f"{indent}{unit.mark} ", f"{indent}  "
+        paint = _PAINT[unit.mark] if colour else ""
+        for n, wrapped in enumerate(wrap_words(unit.words, first=first, rest=rest,
+                                               width=width)):
             head = first if n == 0 else rest
             line = f"{head}{painted(wrapped)}".rstrip()
             lines.append(f"{paint}{line}{_RESET}" if paint else line)
-
-    a, b = _units(was), _units(now)
-    matcher = difflib.SequenceMatcher(None, a, b, autojunk=False)
-    for op, i1, i2, j1, j2 in matcher.get_opcodes():
-        if op == "equal":
-            for unit in a[i1:i2]:
-                emit(" ", _plain(unit))
-            continue
-        marks_r, marks_a = _pair_words(a[i1:i2], b[j1:j2])
-        for words in marks_r:
-            emit("-", words)
-        for words in marks_a:
-            emit("+", words)
     return lines
 
 
@@ -555,7 +593,7 @@ def render_change(change: RatificationChange, *, ratifier: str | None = None,
              f"(stamp {change.stamp}, ratified content at {change.revision[:9]}"
              f"{', cached' if change.cached else ''}):"]
     for c in change.changes:
-        if _prose(c.was, c.now):
+        if is_prose(c.was, c.now):
             lines.extend(_render_prose(c.field, c.was, c.now, pad=pad,
                                        columns=columns, colour=colour))
         else:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.2.0
+Version: 3.4.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
+166
 <!-- 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.4.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.2.0 → throughline-3.4.0}/tests/test_engine.py

@@ -4376,6 +4376,36 @@ def _linked_pair(tmp_path):
     return root
 
 
+def test_link_same_edge_twice_is_an_error(tmp_path, capsys):
+    """Adding an edge that already exists with the same type is refused rather
+    than duplicated (SR-0143 names the single matching edge; SR-0034)."""
+    root = _linked_pair(tmp_path)
+    assert _cli(["-C", str(root), "link", "FR-0002", "FR-0001",
+                 "--type", "relates"]) != 0
+    assert "already exists" in capsys.readouterr().err
+    links = [ln for ln in load_project(str(root)).get("FR-0002").links
+             if ln.target == "FR-0001"]
+    assert len(links) == 1
+
+
+def test_link_stamp_refreshes_existing_edge_in_place(tmp_path):
+    """`tl link --stamp` on an existing edge is the re-confirm command SR-0034
+    promises: the stamp is refreshed on that edge and no second edge appears."""
+    root = _linked_pair(tmp_path)
+    assert _cli(["-C", str(root), "link", "FR-0002", "FR-0001",
+                 "--type", "relates", "--stamp"]) == 0
+    links = [ln for ln in load_project(str(root)).get("FR-0002").links
+             if ln.target == "FR-0001"]
+    assert len(links) == 1 and links[0].stamp
+    first = links[0].stamp
+    assert _cli(["-C", str(root), "amend", "FR-0001", "--text", "changed"]) == 0
+    assert _cli(["-C", str(root), "link", "FR-0002", "FR-0001",
+                 "--type", "relates", "--stamp"]) == 0
+    links = [ln for ln in load_project(str(root)).get("FR-0002").links
+             if ln.target == "FR-0001"]
+    assert len(links) == 1 and links[0].stamp and links[0].stamp != first
+
+
 def test_link_retype_changes_type_in_place(tmp_path):
     """`tl link --retype` changes an existing edge's type rather than adding a
     parallel one, so a semantic-link review needs no YAML hand-editing (SR-0143)."""

{throughline-3.2.0 → throughline-3.4.0}/tests/test_ratification_change.py

@@ -16,7 +16,10 @@ import pytest
 
 from throughline.cli import main as cli_main
 from throughline.ratification import (
+    ADDED,
     CHANGED,
+    KEPT,
+    REMOVED,
     REVISION_ATTR,
     UNCHANGED,
     UNRATIFIED,
@@ -24,6 +27,9 @@ from throughline.ratification import (
     change_since_ratification,
     render_change,
     resolve_revision,
+    diff_prose,
+    is_prose,
+    wrap_words,
 )
 from throughline.storage import load_project
 
@@ -332,6 +338,63 @@ def test_a_sentence_replaced_by_two_pairs_with_the_one_it_became(graph):
     assert wholly_new.startswith("\033[32m") and "\033[7m" not in wholly_new
 
 
+# --------------------------------------------- the diff offered as data (SR-0200)
+
+def test_the_diff_is_offered_as_units_with_the_moved_words_marked():
+    """A consumer with a screen of its own reads the kept, removed and added units
+    in order, each word carrying whether it moved, and derives nothing (SR-0200)."""
+    units = diff_prose(PARAGRAPH, REWORDED)
+    assert [u.mark for u in units] == [REMOVED, ADDED, KEPT, KEPT]
+    removed, added, kept, _last = units
+    assert removed.text == "The Tool shall evict a cached widget after 3600 seconds."
+    assert added.text == "The Tool shall evict a cached widget when it is an hour old."
+    assert [w for w, moved in removed.words if moved] == ["after", "3600", "seconds."]
+    assert [w for w, moved in added.words if moved] == ["when", "it", "is", "an", "hour", "old."]
+    assert kept.text.startswith("It shall record") and not kept.marked
+
+
+def test_the_terminal_rendering_is_built_from_the_same_data(graph):
+    """What tl ratify paints and what the data says are one account: every unit
+    the rendering shows is a unit the data names, in the same order with the same
+    words, and the words it highlights are the words the data marks (SR-0200)."""
+    _ratified_paragraph(graph)
+    project = load_project(graph)
+    change = change_since_ratification(project, project.get("REQ-0002"))
+    (field,) = change.changes
+    units = diff_prose(field.was, field.now)
+
+    plain = render_change(change, columns=400)[2:]           # one line per unit
+    assert [ln.strip()[0] if ln.strip()[0] in "-+" else " " for ln in plain] \
+        == [u.mark for u in units]
+    assert [ln.strip().lstrip("-+ ") for ln in plain] == [u.text for u in units]
+
+    painted = render_change(change, columns=400, colour=True)[2:]
+    for line, unit in zip(painted, units):
+        marked_words = " ".join(w for w, moved in unit.words if moved)
+        assert _marked(line) == ([marked_words] if marked_words else [])
+
+
+def test_only_prose_is_diffed():
+    """A token — a priority, a flag — is before and after on one line, so the
+    consumer asks the same question the renderer does before drawing a diff."""
+    assert not is_prose("should", "must")
+    assert not is_prose(None, "must")
+    assert is_prose("The Tool shall.", "The Tool must.")
+    assert is_prose("", "Two words.")
+
+
+def test_a_unit_wraps_without_losing_a_word_or_its_mark():
+    """The wrap a consumer draws with keeps every word once, keeps each word's
+    mark, and never runs past the width once the prefixes are counted (SR-0200)."""
+    (removed, *_rest) = diff_prose(PARAGRAPH, REWORDED)
+    lines = wrap_words(removed.words, first="    - ", rest="      ", width=30)
+    assert len(lines) > 1
+    assert [w for ln in lines for w in ln] == list(removed.words)
+    for n, ln in enumerate(lines):
+        prefix = "    - " if n == 0 else "      "
+        assert len(prefix) + len(" ".join(w for w, _m in ln)) <= 30
+
+
 # ------------------------------------------------------ the revision cache (SR-0166)
 
 def test_migrate_caches_the_resolved_revision(graph):

throughline-3.4.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