throughline 3.3.0__tar.gz → 3.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.3.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,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' -->
-165
+166
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 29

{throughline-3.3.0 → throughline-3.4.0}/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' -->
-165
+166
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 29

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "throughline"
-version = "3.3.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.3.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}"
@@ -2229,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")

{throughline-3.3.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.3.0 → throughline-3.4.0/src/throughline.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: throughline
-Version: 3.3.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,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' -->
-165
+166
 <!-- tl:end --> system requirements,
 <!-- tl:count type == 'user_requirement' -->
 29

{throughline-3.3.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.3.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):