reqctl 0.1.38__py3-none-any.whl

reqctl/cite.py

@@ -0,0 +1,1229 @@
+import ast
+import difflib
+import functools
+import io
+import os
+import subprocess
+import re
+import secrets
+import stat
+import tokenize
+from pathlib import Path
+
+import yaml
+
+from . import corpus, typescript
+from .corpus import ReqctlError
+from .reach import SCRIPTED, Reach, remarked
+
+OPEN, CLOSE, SINGLE = "+", "-", ">"
+EVERY = object()
+SIGN = re.compile(r"@req([+>-])(?=\s|$)")
+TIGHT = re.compile(r"@req[+>-](?=\S)")
+# @req> REQ-88203622@wlZ9orsr9c7q y644wh
+# @req> REQ-22755763@lFaaseccSg81 5upe6v
+MARKER = re.compile(
+    rf"\A@req(?P<sign>[+>-])(?:\s+(?P<uid>(?:{corpus.KINDS})-\d+"
+    rf"|{corpus.NAME}(?:\.{corpus.NAME})?(?=@))"
+    r"(?:@(?P<stamp>\S*))?)?(?:\s+(?P<id>\S+))?(?:\s+(?P<exclusive>exclusive))?\Z")
+FORMER = re.compile(rf"@req:\s*((?:{corpus.KINDS})-\d+)")
+# @req+ REQ-52925332@8dtaEN9KH9jO tup4w2
+MARKUP = re.compile(r"\A\s*<!--\s*|\s*-->\s*\Z")
+# @req> REQ-38033048@mKGzPYjyS_wD nvsgih
+# @req> REQ-21225852@RMA1Qtug7rzF kjbkap
+DELIMITERS = {**dict.fromkeys((".py", ".yml", ".yaml"), re.compile(r"\A\s*#+\s*")),
+              **dict.fromkeys((".js", *typescript.SUFFIXES), re.compile(r"\A\s*//\s*")),
+              ".sql": re.compile(r"\A\s*--\s*")}
+# @req- tup4w2
+ALPHABET = "abcdefghijklmnopqrstuvwxyz234567"
+# @req> REQ-60346603@FI4Rjvk1iDNp ulk4ve
+# @req> REQ-38033048@mKGzPYjyS_wD 4ei5xf
+# @req> REQ-21225852@RMA1Qtug7rzF e7bycn
+COMMENTS = {**dict.fromkeys((".py", ".yml", ".yaml"), ("# ", "")),
+            ".md": ("<!-- ", " -->"), ".html": ("<!-- ", " -->"),
+            **dict.fromkeys((".js", *typescript.SUFFIXES), ("// ", "")), ".sql": ("-- ", "")}
+BOM = "\ufeff"
+
+
+# @req> REQ-52925332@8dtaEN9KH9jO cczml5
+def _feed_lines(text):
+    return io.StringIO(text).readlines()
+
+
+@functools.cache
+def _front(text):
+    lines = _feed_lines(text)
+    if not lines or lines[0].rstrip("\r\n") != "---":
+        return 0
+    return next((number for number, line in enumerate(lines[1:], start=2)
+                 if line.rstrip("\r\n") == "---"), 0)
+
+
+@functools.cache
+def _matter(text):
+    close = _front(text)
+    return "".join(line if 1 < number < close else _ending(line)
+                   for number, line in enumerate(_feed_lines(text), start=1))
+
+
+def _view(suffix, text, number):
+    if suffix == ".md" and 1 < number < _front(text):
+        return ".yml", _matter(text)
+    return suffix, text
+
+
+def markers(text, suffix):
+    for number, line in enumerate(_feed_lines(text), start=1):
+        # @req+ REQ-52925332@8dtaEN9KH9jO yuyqhd
+        # @req+ REQ-12490145@aKVRSLNQy976 dsvgt4
+        if not SIGN.search(line):
+            continue
+        # @req> REQ-35587066@UWrbgGEbefJg g2x6cn
+        body = DELIMITERS.get(_view(suffix, text, number)[0], MARKUP).sub("", line).strip()
+        yield number, body, MARKER.match(body)
+        # @req- dsvgt4
+        # @req- yuyqhd
+
+
+@functools.cache
+def _depths(text):
+    depth, depths, starts, ends = 0, {}, set(), set()
+    fresh = True
+    for token in tokenize.generate_tokens(io.StringIO(text).readline):
+        kind, line = token.type, token.start[0]
+        if kind == tokenize.INDENT:
+            depth += 1
+        elif kind == tokenize.DEDENT:
+            depth -= 1
+        elif kind == tokenize.NEWLINE:
+            ends.add(line)
+            fresh = True
+        elif kind not in (tokenize.NL, tokenize.COMMENT, tokenize.ENDMARKER):
+            for spanned in range(token.start[0], token.end[0] + 1):
+                depths.setdefault(spanned, depth)
+            if fresh:
+                starts.add(line)
+                fresh = False
+    return depths, starts, ends
+
+
+@functools.cache
+def _indents(text):
+    spans, flows = [], []
+    for event in yaml.parse(text, Loader=corpus.Loader):
+        start, end = event.start_mark, event.end_mark
+        if isinstance(event, yaml.CollectionStartEvent) and event.flow_style:
+            flows.append(start)
+            continue
+        if isinstance(event, yaml.CollectionEndEvent) and flows:
+            start = flows.pop()
+        spans.append(range(start.line + 1, end.line + 1 + bool(end.column)))
+    inside = {n for span in spans for n in span[1:]}
+    depths = {}
+    for number, line in enumerate(_feed_lines(text), start=1):
+        body = line.strip()
+        if body and (number in inside or not body.startswith("#")):
+            depths[number] = len(_indent(line)) + (body == "-" or body.startswith("- "))
+    ends = set(depths)
+    for span in spans:
+        ends.difference_update([n for n in span if n in depths][:-1])
+    return depths, set(depths) - inside, ends
+
+
+NESTS = {".py": _depths, ".yml": _indents, ".yaml": _indents}
+
+
+def cut(path, text, spans):
+    suffix = Path(path).suffix
+    problems = []
+    # @req> REQ-55291596@DLuklmxajzSV 5hrvsm
+    if suffix == ".md":
+        close = _front(text)
+        problems = [(identity, f"{path}: citation {identity} crosses the edge of the "
+                               "front matter -- it must lie between its --- lines")
+                    for identity, first, last in spans if 1 < first - 1 < close <= last]
+        spans = [span for span in spans if 1 < span[1] and span[2] < close]
+        if not spans:
+            return problems
+        suffix, text = ".yml", _matter(text)
+    # @req+ REQ-60833823@pdX0Xr4bVNDt afaqnn
+    # @req+ REQ-20885376@eU3vxq0uOnB- dzfzmi
+    row = (typescript.read(suffix, typescript.blanked(text, _marked(text))).broken
+           if suffix in typescript.SUFFIXES else _sql(text)[1] if suffix == ".sql" else None)
+    if row:
+        # @req> REQ-30898926@Vu28eWaG_1mE ryp2vk
+        return [(path, f"{path}: cannot read it past line {row}, so no citation in it can "
+                       "be checked -- fix the file so it parses, then retry")]
+    # @req- dzfzmi
+    # @req- afaqnn
+    read = NESTS.get(suffix)
+    if read is None:
+        return []
+    try:
+        depths, starts, ends = read(text)
+    except (tokenize.TokenError, IndentationError, SyntaxError, yaml.YAMLError) as broken:
+        # @req> REQ-30898926@Vu28eWaG_1mE 4cfehc
+        return problems + [(path, f"{path}: cannot read its nest levels ({broken}), so no "
+                                  "citation in it can be checked -- fix the file so "
+                                  "its nest levels parse, then retry")]
+    for identity, first, last in spans:
+        code = [n for n in range(first, last + 1) if n in depths]
+        if not code:
+            continue
+        level = depths[code[0]]
+        after = [n for n in depths if n > last]
+        # @req> REQ-41552912@G_9UzXwu1WUL fu7y6n
+        if (code[0] not in starts or code[-1] not in ends
+                or any(depths[n] < level for n in code)
+                or (after and depths[min(after)] > level)):
+            # @req> REQ-30898926@Vu28eWaG_1mE whom5u
+            problems.append((identity,
+                             f"{path}: citation {identity} cuts a block, as it must "
+                             "cover whole statements at the nest level of its first "
+                             f"line -- reqctl untag {identity}, then reqctl tag lines "
+                             "that do"))
+    return problems
+
+
+# @req+ REQ-20885376@eU3vxq0uOnB- t3wbhh
+# @req+ REQ-69161009@gmE3x-nnaEYM awdr2c
+SQL_OPENS = re.compile(r"--|/\*|(?<![\w$])[Ee]'|'|\"|(?<![\w$])\$(?:[^\W\d]\w*)?\$")
+
+
+def _closed(text, at, quote, escaping):
+    while at < len(text):
+        if escaping and text[at] == "\\":
+            at += 2
+        elif text.startswith(quote * 2, at):
+            at += 2
+        elif text[at] == quote:
+            return at + 1
+        else:
+            at += 1
+    return None
+
+
+def _nested(text, at):
+    depth = 1
+    while depth and at < len(text):
+        step = text[at:at + 2]
+        depth += (step == "/*") - (step == "*/")
+        at += 2 if step in ("/*", "*/") else 1
+    return None if depth else at
+
+
+def _sql(text):
+    spans, at, unclosed = [], 0, None
+    while (found := SQL_OPENS.search(text, at)) is not None:
+        opener = found[0]
+        if opener == "--":
+            end = text.find("\n", found.start())
+            end = len(text) if end < 0 else end
+        elif opener == "/*":
+            end = _nested(text, found.end())
+        elif opener.startswith("$"):
+            close = text.find(opener, found.end())
+            end = None if close < 0 else close + len(opener)
+        else:
+            end = _closed(text, found.end(), opener[-1], opener[0] in "Ee")
+        if end is None:
+            unclosed, end = text.count("\n", 0, found.start()) + 1, len(text)
+        spans.append((found.start(), end, opener not in ("--", "/*")))
+        at = end
+    return spans, unclosed
+# @req- awdr2c
+# @req- t3wbhh
+
+
+def _spans(suffix, text):
+    if suffix == ".sql":
+        return _sql(text)[0]
+    if suffix in typescript.SUFFIXES:
+        return typescript.read(suffix, text).spans
+    return [(found.start(), found.end(), found.groupdict().get("kept") is not None)
+            for found in REMARKS[suffix].finditer(text)]
+
+
+def _remarked(suffix, text, spoken):
+    held, at = [], 0
+    for start, end, kept in _spans(suffix, text):
+        held += [text[at:start], spoken(text[start:end], kept)]
+        at = end
+    return "".join(held) + text[at:]
+
+
+def remarks(suffix, text):
+    return remarked(text, _spans(suffix, text))
+
+
+# @req+ REQ-82335572@EEu579sUxCO2 jflstj
+# @req+ REQ-79989567@oaSFUA9o3D48 6fth2x
+REMARKS = {**dict.fromkeys((".py", ".yml", ".yaml"), re.compile(r"#[^\n]*")),
+           **dict.fromkeys((".md", ".html"), re.compile(r"<!--[\s\S]*?(?:-->|\Z)")),
+           ".js": re.compile(r"""(?P<kept>"(?:\\[\s\S]|[^"\\\n])*"|'(?:\\[\s\S]|[^'\\\n])*'"""
+                             r"""|`(?:\\[\s\S]|[^`\\])*`)|//[^\n]*|/\*[\s\S]*?(?:\*/|\Z)""")}
+
+
+def hollow(path, text, first, last):
+    suffix, text = _view(Path(path).suffix, text, first)
+    bare = _remarked(suffix, text, lambda said, kept: said if kept else "\n" * said.count("\n"))
+    return not "".join(_feed_lines(bare)[first - 1:last]).strip()
+# @req- 6fth2x
+# @req- jflstj
+
+
+RAW = re.compile(REMARKS[".html"].pattern
+                 + r"|<style(?=[\s/>])[^>]*>(?P<style>[\s\S]*?)(?:</style(?=[\s/>])|\Z)"
+                 r"|<script(?=[\s/>])[^>]*>(?P<script>[\s\S]*?)(?:</script(?=[\s/>])|\Z)",
+                 re.IGNORECASE)
+
+
+def _row(text, offset):
+    return text.count("\n", 0, offset) + 1
+
+
+def _between(text, start, end, kind):
+    return dict.fromkeys(range(_row(text, start) + 1, _row(text, end)), kind)
+
+
+def _literals(text, start, end):
+    return {number: kind for found in REMARKS[".js"].finditer(text, start, end)
+            if (found["kept"] or "").startswith("`")
+            for number, kind in _between(text, found.start(), found.end() - 1,
+                                         "template literal").items()}
+
+
+def _marked(text):
+    return {number for number, line in enumerate(_feed_lines(text), start=1)
+            if SIGN.search(line)}
+
+
+@functools.cache
+def _embedded(suffix, text):
+    if suffix == ".js":
+        return _literals(text, 0, len(text))
+    if suffix in typescript.SUFFIXES:
+        return typescript.embedded(suffix, text, _marked(text))
+    if suffix != ".html":
+        return {}
+    held = {}
+    for found in RAW.finditer(text):
+        if found["style"] is not None:
+            held |= _between(text, found.start("style"), found.end("style"), "style element")
+        elif found["script"] is not None:
+            held |= _literals(text, found.start("script"), found.end("script"))
+    return held
+
+
+# @req+ REQ-12235023@uEMBe2x_2uwp njbuvc
+@functools.cache
+def _scalars(text):
+    return {number for event in yaml.parse(text, Loader=corpus.Loader)
+            if isinstance(event, yaml.ScalarEvent)
+            for number in range(event.start_mark.line + 1,
+                                event.end_mark.line + 1 + bool(event.end_mark.column))}
+
+
+def _alone(path, text):
+    suffix = Path(path).suffix
+    # @req+ REQ-35587066@UWrbgGEbefJg lds6u4
+    if suffix != ".md":
+        return _lone(suffix, text)
+    close = _front(text)
+    return ({number for number in _lone(suffix, text) if not 1 < number < close}
+            | _lone(".yml", _matter(text)))
+    # @req- lds6u4
+
+
+def _lone(suffix, text):
+    try:
+        spoken = (_depths(text)[0] if suffix == ".py"
+                  else _scalars(text) if suffix in (".yml", ".yaml") else {})
+    except (tokenize.TokenError, IndentationError, SyntaxError, yaml.YAMLError):
+        spoken = {}
+    bare = _remarked(suffix, text, lambda said, kept: said if "\n" in said or kept else "\0")
+    return {number for number, line in enumerate(_feed_lines(bare), start=1)
+            if number not in spoken and line.strip() == "\0"}
+# @req- njbuvc
+
+
+def read(root, digested=False, uid=None):
+    sources = list(_sources(root))
+    citations, faults = _parse(sources)
+    # @req+ REQ-64570886@Zckz3LzHUzXn g2iusc
+    owners = {parsed["id"]: parsed["uid"].partition(".")[0]
+              for relative, text in sources if uid and text is not None
+              for _, _, parsed in markers(text, Path(relative).suffix)
+              if parsed and parsed["id"] and parsed["uid"]}
+
+    def mine(owner):
+        return not uid or owner is None or owner == uid
+    problems = [fault for about, fault in faults if mine(owners.get(about))]
+    # @req- g2iusc
+    # @req> REQ-32191310@aZkvQ6hvIwPv yjp5s6
+    if digested:
+        texts = dict(sources)
+        # @req> REQ-59827868@eeHZvhZPFhD3 tsczoy
+        reach = Reach(texts)
+        for citation in citations:
+            citation["digest"] = digest(citation["path"], texts[citation["path"]],
+                                        citation["lines"], reach)
+    # @req+ REQ-79989567@oaSFUA9o3D48 bz6frh
+    texts = dict(sources)
+    # @req> REQ-64570886@Zckz3LzHUzXn o4sv56
+    # @req> REQ-30898926@Vu28eWaG_1mE ar62n7
+    problems += [f"{c['path']}: citation {c['id']} covers no code statement -- "
+                 f"reqctl untag {c['id']}, then reqctl tag a code statement"
+                 for c in citations if len(c["marks"]) == 2 and mine(c["uid"])
+                 and hollow(c["path"], texts[c["path"]], c["first"], c["last"])]
+    # @req- bz6frh
+    # @req> REQ-64570886@Zckz3LzHUzXn zeqhfc
+    return citations, problems + [fault for owner, fault in former(sources)
+                                  if mine(owner)]
+
+
+def former(sources):
+    # @req> REQ-44164687@2UxalfYloyMd q2mqfm
+    for relative, text in sources:
+        for number, line in enumerate(_feed_lines(text or ""), start=1):
+            for uid in FORMER.findall(line):
+                # @req> REQ-30898926@Vu28eWaG_1mE 2fo354
+                yield uid, (f"{relative}:{number}: names {uid} in a single-line "
+                            "tag -- remove that comment, then cite the code with "
+                            "reqctl tag")
+
+
+def cited(citations):
+    held = {}
+    for citation in citations:
+        held.setdefault(citation["uid"], []).append(
+            (citation["path"], citation["pinned"], citation["entry"]))
+    return held
+
+
+def parse(sources):
+    citations, faults = _parse(sources)
+    return citations, [fault for _, fault in faults]
+
+
+def _parse(sources, placed=True):
+    opened, faults, seen = [], [], {}
+    for relative, text in sources:
+        # @req> REQ-35805881@37XtC4gyD98k 5h3hpr
+        if text is None:
+            # @req> REQ-30898926@Vu28eWaG_1mE nltcdy
+            faults.append((EVERY, f"{relative}: unreadable while scanning for "
+                                  "statement citations -- make it readable (fix "
+                                  "its permissions), then retry"))
+            continue
+        # @req> REQ-25428163@jtztw34heeVp ap76fb
+        if TIGHT.search(text):
+            faults += [(None, f"{relative}:{number}: a citation marker has no "
+                              "space after its sign; put one between the sign "
+                              "and what follows")
+                       for number, line in enumerate(_feed_lines(text), start=1)
+                       if TIGHT.search(line)]
+        found = list(markers(text, Path(relative).suffix))
+        if not found:
+            continue
+        if Path(relative).suffix not in COMMENTS:
+            # @req> REQ-30898926@Vu28eWaG_1mE 3lg537
+            faults.append((None,
+                           f"{relative}: carries a statement citation, but citations "
+                           f"are read only in {', '.join(sorted(COMMENTS))} files -- "
+                           "reqctl untag each citation id it carries, or remove the "
+                           "comment by hand where it names none"))
+            continue
+        # @req> REQ-12235023@uEMBe2x_2uwp 4s3qrw
+        alone = _alone(relative, text)
+        # @req> REQ-78286717@Lol93VZlA61p ltsm7v
+        # @req> REQ-29782682@vNwe2DOIu-N0 zuqhai
+        embedded = _embedded(Path(relative).suffix, text)
+        live, spans, singles = {}, [], []
+        # @req+ REQ-73349683@BNT8xnMPL2bn gqpqj6
+        for number, body, parsed in found:
+            # @req+ REQ-78286717@Lol93VZlA61p eynr4h
+            # @req+ REQ-29782682@vNwe2DOIu-N0 67wjjk
+            kind = embedded.get(number)
+            if kind and placed:
+                # @req> REQ-30898926@Vu28eWaG_1mE 2ezs26
+                faults.append((parsed and parsed["id"],
+                               f"{relative}:{number}: holds a citation marker inside a "
+                               f"{kind}, where it is not read as a comment -- reqctl "
+                               f"untag its citation, then reqctl tag lines outside the "
+                               f"{kind}"))
+                continue
+            # @req- 67wjjk
+            # @req- eynr4h
+            # @req> REQ-12235023@uEMBe2x_2uwp sbc4do
+            if not kind and number not in alone:
+                # @req> REQ-30898926@Vu28eWaG_1mE nmx3xd
+                faults.append((None, f"{relative}:{number}: holds a citation marker "
+                                     "and more than white space and one single-line "
+                                     "comment, so no citation is read from it -- "
+                                     "reqctl untag its citation, then reqctl tag "
+                                     "again"))
+                continue
+            # @req> REQ-11268295@s4gX4poitxmM q7622j
+            if parsed is None or not parsed["id"]:
+                # @req> REQ-30898926@Vu28eWaG_1mE a7oxjp
+                faults.append((None, f"{relative}:{number}: `{body}` names no "
+                                     "citation identity -- remove the comment by "
+                                     "hand, or replace it by citing the code with "
+                                     "reqctl tag"))
+                continue
+            identity = parsed["id"]
+            if parsed["sign"] in (OPEN, SINGLE):
+                if not parsed["uid"]:
+                    # @req> REQ-30898926@Vu28eWaG_1mE aogklo
+                    faults.append((identity, f"{relative}:{number}: citation "
+                                             f"{identity} names no requirement -- "
+                                             f"reqctl untag {identity}, then reqctl "
+                                             "tag again"))
+                    continue
+                # @req> REQ-44424329@FMmHjrkfDEYR det3om
+                if identity in seen:
+                    # @req> REQ-30898926@Vu28eWaG_1mE k2nkiy
+                    faults.append((identity,
+                                   f"{relative}:{number}: citation {identity} is also "
+                                   f"opened at {seen[identity]}, though an identity "
+                                   "names one citation -- reqctl untag one of the "
+                                   "two, then reqctl tag again"))
+                seen.setdefault(identity, f"{relative}:{number}")
+                if parsed["sign"] == SINGLE:
+                    singles.append((number, parsed))
+                    continue
+                live[identity] = (number, parsed)
+            elif identity not in live:
+                # @req> REQ-30898926@Vu28eWaG_1mE mqimpm
+                faults.append((identity, f"{relative}:{number}: closes citation "
+                                         f"{identity}, which is not open here -- "
+                                         f"reqctl untag {identity}"))
+            else:
+                # @req+ REQ-52925332@8dtaEN9KH9jO wbbbtu
+                start, held = live.pop(identity)
+                spans.append((identity, start + 1, number - 1))
+                opened.append(_citation(held, relative, start, number,
+                                        start + 1, number - 1, [start, number]))
+                # @req- wbbbtu
+        for identity, (number, _) in live.items():
+            # @req> REQ-30898926@Vu28eWaG_1mE gf5tft
+            faults.append((identity, f"{relative}:{number}: opens citation "
+                                     f"{identity} and never closes it -- reqctl "
+                                     f"untag {identity}, then reqctl tag the lines "
+                                     "again"))
+        # @req- gqpqj6
+        for number, held in singles:
+            span = following(relative, text, number)
+            # @req> REQ-95865306@6u2XMnjDwlvR ytqmle
+            if span is None:
+                # @req> REQ-30898926@Vu28eWaG_1mE gt4zxq
+                faults.append((held["id"], f"{relative}:{number}: citation "
+                                           f"{held['id']} has no code statement after "
+                                           f"it -- reqctl untag {held['id']}"))
+                continue
+            opened.append(_citation(held, relative, number, span[1], *span,
+                                    [number]))
+        # @req> REQ-51709712@D0x4hZmSHgiW l3wdgx
+        faults += cut(relative, text, spans if placed else [])
+    return covered(opened), faults
+
+
+# @req> REQ-22755763@lFaaseccSg81 rafirp
+def _citation(held, relative, start, close, first, last, marks):
+    uid, _, entry = held["uid"].partition(".")
+    return {"id": held["id"], "uid": uid, "entry": entry or None,
+            "address": held["uid"], "pinned": held["stamp"] or "",
+            "exclusive": bool(held["exclusive"]), "path": relative,
+            "open": start, "close": close, "first": first, "last": last,
+            "marks": marks}
+
+
+def following(path, text, number, viewed=None):
+    suffix, text = _view(Path(path).suffix, text, viewed or number)
+    read = NESTS.get(suffix)
+    if read is not None:
+        try:
+            depths, starts, _ = read(text)
+        except (tokenize.TokenError, IndentationError, SyntaxError, yaml.YAMLError):
+            depths = None
+        # @req> REQ-42668747@CRvKDa_F_lxE cfabxh
+        if depths is not None:
+            later = sorted(n for n in starts if n > number)
+            if not later:
+                return None
+            first = later[0]
+            level = depths[first]
+            beyond = [n for n in later if n > first and depths[n] <= level]
+            last = max(n for n in depths
+                       if first <= n and (not beyond or n < beyond[0]))
+            return first, last
+    lines = _feed_lines(text)
+    # @req> REQ-37846580@oqAWJFdNHvDo lrybex
+    for at in range(number, len(lines)):
+        if lines[at].strip() and not SIGN.search(lines[at]):
+            return at + 1, at + 1
+    return None
+
+
+def covered(citations):
+    # @req> REQ-73495055@cPNC8izAHGTl lihjvk
+    marks = {(c["path"], line) for c in citations for line in c["marks"]}
+    # @req+ REQ-33202540@Y-kVcYdmW6zT r4lu24
+    # @req+ REQ-97852648@9PG_RRu-Iv2o cl74rk
+    exclusive = {}
+    for held in citations:
+        if held["exclusive"]:
+            exclusive.setdefault(held["path"], []).append(held)
+    # @req- cl74rk
+    # @req- r4lu24
+    for citation in citations:
+        lines = []
+        for line in range(citation["first"], citation["last"] + 1):
+            # @req> REQ-73495055@cPNC8izAHGTl jtgzg5
+            if (citation["path"], line) in marks:
+                continue
+            # @req+ REQ-33202540@Y-kVcYdmW6zT 6o76zm
+            # @req+ REQ-97852648@9PG_RRu-Iv2o fto5gh
+            claimed = [c for c in exclusive.get(citation["path"], [])
+                       if c["first"] <= line <= c["last"]]
+            # @req> REQ-17608335@ejFjhGoCg5c7 4makw7
+            owners = ([max(claimed, key=lambda c: c["open"])] if claimed
+                      else [citation])
+            # @req- fto5gh
+            # @req- 6o76zm
+            if citation in owners:
+                lines.append(line)
+        citation["lines"] = lines
+    return citations
+
+
+def _sources(root):
+    root = Path(root)
+    # @req+ REQ-35805881@37XtC4gyD98k ofycdw
+    unread = []
+    # @req> REQ-81857516@chYOQDPmuDuW ldlf2u
+    for folder, subdirs, files in os.walk(root, onerror=unread.append):
+        subdirs[:] = [name for name in subdirs
+                      if not corpus.skipped(root, Path(folder) / name)]
+        for name in files:
+            path = Path(folder) / name
+            try:
+                if not stat.S_ISREG(path.stat().st_mode):
+                    continue
+                raw = path.read_bytes()
+            except FileNotFoundError:
+                continue
+            except OSError:
+                yield str(path.relative_to(root)), None
+                continue
+            if b"\0" in raw:
+                continue
+            # @req> REQ-36103991@1sBO1pub0_IK xx3hop
+            yield str(path.relative_to(root)), raw.decode(errors="ignore").removeprefix(BOM)
+    for failure in unread:
+        yield str(Path(failure.filename).relative_to(root)), None
+    # @req- ofycdw
+
+
+def mint(held):
+    while True:
+        # @req+ REQ-92239556@4-oyw0syx-xA uprfcz
+        identity = "".join(secrets.choice(ALPHABET) for _ in range(6))
+        if identity not in held:
+            return identity
+        # @req- uprfcz
+
+
+def _ending(line):
+    return line[len(line.rstrip("\r\n")):]
+
+
+# @req> REQ-89706423@fyVHTsenA51D rkepcq
+def _indent(line):
+    body = line.rstrip("\r\n")
+    return body[:len(body) - len(body.lstrip())]
+
+
+# @req> REQ-89706423@fyVHTsenA51D 5nywje
+def _inserted(lines, before, after):
+    ending = next((_ending(line) for line in lines if _ending(line)), "\n")
+    out = []
+    for number, line in enumerate(lines, start=1):
+        out += [marker + (_ending(line) or ending)
+                for _, _, marker in sorted(before.get(number, []))]
+        closings = [marker for _, _, marker in sorted(after.get(number, []))]
+        if closings and not _ending(line):
+            out += [line + ending, ending.join(closings)]
+            continue
+        out.append(line)
+        out += [marker + (_ending(line) or ending) for marker in closings]
+    return "".join(out)
+
+
+# @req> REQ-73851379@CGbsH1UOrU8C 26lc4r
+def _duplicates(path, found, asked):
+    marks = {line for citation in found for line in citation["marks"]}
+    spanned = {citation["id"]: tuple(n for n in range(citation["first"],
+                                                     citation["last"] + 1)
+                                     if n not in marks)
+               for citation in found}
+    order = list(asked)
+    problems = []
+    for identity, (first, last, uid, _) in asked.items():
+        for other in found:
+            earlier = (other["id"] not in asked
+                       or order.index(other["id"]) < order.index(identity))
+            if (other["address"] == uid and earlier
+                    and spanned[other["id"]] == spanned[identity]):
+                # @req> REQ-30898926@Vu28eWaG_1mE dz352n
+                problems.append(
+                    f"{path}: lines {first}-{last} are already cited for {uid}"
+                    + (" by this command" if other["id"] in asked
+                       else f" by citation {other['id']}")
+                    + " -- reqctl untag the existing citation, or cite other lines")
+                break
+    return problems
+
+
+# @req> REQ-60346603@FI4Rjvk1iDNp e2efde
+def tagged(root, path, asked, exclusive=False):
+    target = Path(path)
+    if target.suffix not in COMMENTS:
+        # @req> REQ-30898926@Vu28eWaG_1mE z2sgqd
+        raise ReqctlError(f"{path}: citations are written only in "
+                          f"{', '.join(sorted(COMMENTS))} files -- cite a file of "
+                          "one of those types")
+    # @req> REQ-89706423@fyVHTsenA51D thl334
+    if not target.resolve().is_relative_to(Path(root).resolve()):
+        # @req> REQ-30898926@Vu28eWaG_1mE mh6b74
+        raise ReqctlError(f"{path}: not in the code base at {root} -- give a "
+                          "path inside it")
+    # @req+ REQ-71794830@YqhGXWh66eq_ tbkz5r
+    base = Path(root).resolve()
+    folder = next((up for up in target.resolve().parents
+                   if up != base and up.is_relative_to(base)
+                   and corpus.skipped(base, up)), None)
+    if folder is not None:
+        # @req> REQ-30898926@Vu28eWaG_1mE kn3gln
+        raise ReqctlError(f"{path}: {folder.relative_to(base)} is a folder the "
+                          "citation scan skips, so a citation there is never "
+                          "read -- cite code outside it")
+    # @req- tbkz5r
+    # @req+ REQ-36103991@1sBO1pub0_IK 6pharc
+    raw = target.read_bytes().decode()
+    text = raw.removeprefix(BOM)
+    # @req- 6pharc
+    lines = _feed_lines(text)
+    # @req> REQ-65738797@3jHtqzLVQUal msfg5w
+    for first, last, _, _ in asked:
+        if not 1 <= first <= last <= len(lines):
+            # @req> REQ-30898926@Vu28eWaG_1mE wnhqm4
+            raise ReqctlError(f"{path}: lines {first}-{last} are not in the file "
+                              "-- pass --from and --to within the file")
+    # @req+ REQ-55291596@DLuklmxajzSV 7nnmie
+    edge = _front(text) if target.suffix == ".md" else 0
+    crossing = [f"{path}: lines {first}-{last} cross the edge of the front matter -- "
+                "cite lines between its --- lines, or lines after them"
+                for first, last, _, _ in asked
+                if first <= edge and not 1 < first <= last < edge]
+    if crossing:
+        # @req> REQ-30898926@Vu28eWaG_1mE xqueam
+        raise ReqctlError("\n".join(crossing))
+    # @req- 7nnmie
+    sources = list(_sources(root))
+    held, problems = parse(sources)
+    # @req> REQ-35805881@37XtC4gyD98k kz4urn
+    if any(text is None for _, text in sources):
+        # @req> REQ-30898926@Vu28eWaG_1mE 2ejkra
+        raise ReqctlError("the code's citations do not read:\n" + "\n".join(problems))
+    taken = {c["id"] for c in held}
+    word = " exclusive" if exclusive else ""
+    # @req+ REQ-81417723@q6UfXsP6e-N7 kmbhnk
+    # @req+ REQ-62782894@x4o_oB5H0-tY k2lzwu
+    before, after, minted = {}, {}, []
+    for at, (first, last, uid, stamp) in enumerate(asked):
+        identity = mint(taken)
+        taken.add(identity)
+        minted.append(identity)
+        indent = _indent(lines[first - 1])
+        # @req> REQ-55291596@DLuklmxajzSV 7zqv4i
+        lead, tail = COMMENTS[_view(target.suffix, text, first)[0]]
+        # @req+ REQ-61906662@vIt4Qdb6Q01L 4z5goa
+        single = _statement(path, text, first, last)
+        sign = SINGLE if single else OPEN
+        # @req+ REQ-84469558@zZGF1hH7cNnc hp5jwl
+        before.setdefault(first, []).append(
+            (-last, at, f"{indent}{lead}@req{sign} {uid}@{stamp} {identity}{word}{tail}"))
+        if not single:
+            after.setdefault(last, []).append(
+                (-first, -at, f"{indent}{lead}@req{CLOSE} {identity}{tail}"))
+        # @req- hp5jwl
+        # @req- 4z5goa
+    written = _inserted(lines, before, after)
+    # @req- k2lzwu
+    # @req- kmbhnk
+    # @req+ REQ-69161009@gmE3x-nnaEYM n5z4vo
+    # @req+ REQ-20885376@eU3vxq0uOnB- 4wwahn
+    alone = _alone(path, written)
+    # @req+ REQ-39743451@3H-M6CvTxyI0 xasn2j
+    # @req+ REQ-62110789@XlGrbQnAd80g hczsn5
+    embedded = _embedded(target.suffix, written)
+    falling = {parsed["id"]: embedded.get(number, "multiline comment or string")
+               for number, _, parsed in markers(written, target.suffix)
+               if parsed and (number in embedded or number not in alone)}
+    # @req> REQ-30898926@Vu28eWaG_1mE 6tukfm
+    inside = [f"{path}: lines {first}-{last}: a comment carrying the citation would "
+              f"fall inside a {falling[identity]} -- choose lines outside the "
+              f"{falling[identity]}"
+              for identity, (first, last, _, _) in zip(minted, asked)
+              if identity in falling]
+    if inside:
+        # @req> REQ-30898926@Vu28eWaG_1mE dlokdg
+        raise ReqctlError("\n".join(inside))
+    # @req- hczsn5
+    # @req- xasn2j
+    # @req- 4wwahn
+    # @req- n5z4vo
+    found, dropped = parse([(path, written)])
+    new = [c for identity in minted for c in found if c["id"] == identity]
+    # @req> REQ-82335572@EEu579sUxCO2 stzuaz
+    if len(new) < len(minted):
+        # @req> REQ-30898926@Vu28eWaG_1mE dejtqm
+        raise ReqctlError("\n".join(dropped))
+    # @req+ REQ-65738797@3jHtqzLVQUal zkxsxx
+    problems = [problem for _, problem in cut(
+        path, written, [(c["id"], c["first"], c["last"])
+                        for c in new if len(c["marks"]) == 2])]
+    # @req> REQ-82335572@EEu579sUxCO2 5lq35y
+    # @req> REQ-30898926@Vu28eWaG_1mE 3pdc4x
+    problems += [f"{path}: lines {first}-{last} hold no code statement -- "
+                 "choose --from and --to lines that hold one"
+                 for first, last, _, _ in asked if hollow(path, text, first, last)]
+    problems += _duplicates(path, found, dict(zip(minted, asked)))
+    if problems:
+        # @req> REQ-30898926@Vu28eWaG_1mE c7h3c7
+        raise ReqctlError("\n".join(problems))
+    # @req- zkxsxx
+    # @req+ REQ-59827868@eeHZvhZPFhD3 entyuu
+    relative = target.resolve().relative_to(base).as_posix()
+    reach = Reach({**dict(sources), relative: written})
+    # @req- entyuu
+    # @req> REQ-36103991@1sBO1pub0_IK xfy5v4
+    return ((target, (raw[:len(raw) - len(text)] + written).encode()),
+            [(c["id"], c["uid"], digest(relative, written, c["lines"], reach))
+             for c in new])
+
+
+# @req> REQ-96580262@hSRVhY3ybYl9 nevicm
+def pinning(root, identities):
+    sources = dict(_sources(root))
+    found = {citation["id"]: citation for citation in _read(sources.items(), identities, True)}
+    missing = [identity for identity in identities if identity not in found]
+    # @req> REQ-41024637@JaitgDKH7S2S 2usjww
+    # @req> REQ-30898926@Vu28eWaG_1mE 3vmsym
+    if missing:
+        raise ReqctlError(f"no statement citation names {', '.join(missing)} -- reqctl "
+                          "trace UID lists the identities an item is cited by; nothing "
+                          "was re-pinned")
+    # @req+ REQ-64846889@TSG5uy3nM0nk wbaon5
+    # @req+ REQ-59827868@eeHZvhZPFhD3 unauut
+    reach = Reach(sources)
+    return [(citation, digest(citation["path"], sources[citation["path"]], citation["lines"], reach))
+            for citation in (found[identity] for identity in identities)]
+    # @req- unauut
+    # @req- wbaon5
+
+
+# @req+ REQ-62685242@nMlCr6nshoNZ yqdz42
+def _read(sources, identities, placed):
+    held, faults = _parse(sources, placed)
+    found = [citation for citation in held
+             if identities is EVERY or citation["id"] in identities]
+    named = () if identities is EVERY else (*identities, *(c["path"] for c in found))
+    against = [fault for about, fault in faults if about is EVERY or about in named]
+    # @req> REQ-30898926@Vu28eWaG_1mE z3j7ql
+    if against:
+        raise ReqctlError("the code's citations do not read:\n" + "\n".join(against))
+    return found
+
+
+def readable(root, identity=EVERY, placed=True):
+    return _read(_sources(root), identity if identity is EVERY else (identity,), placed)
+
+
+def named(root, identity, placed=True):
+    for citation in readable(root, identity, placed):
+        return citation
+    # @req> REQ-51778557@2aIQFI4KxvJ3 2j6t3u
+    # @req> REQ-41024637@JaitgDKH7S2S cdi6vq
+    # @req> REQ-30898926@Vu28eWaG_1mE bw5uk2
+    raise ReqctlError(f"no statement citation names {identity} -- reqctl "
+                      "trace UID lists the identities an item is cited by")
+# @req- yqdz42
+
+
+def _decoded(target, path):
+    try:
+        return target.read_bytes().decode()
+    except UnicodeDecodeError as error:
+        # @req> REQ-30898926@Vu28eWaG_1mE jfdla5
+        raise ReqctlError(f"cannot read {path}: not valid UTF-8 -- save the "
+                          "file as UTF-8") from error
+
+
+def _lines(root, citation):
+    target = Path(root) / citation["path"]
+    # @req+ REQ-36103991@1sBO1pub0_IK zibglc
+    text = _decoded(target, citation["path"])
+    held = text.removeprefix(BOM)
+    return target, text[:len(text) - len(held)], _feed_lines(held)
+    # @req- zibglc
+
+
+def repinned(root, pins):
+    # @req+ REQ-17757558@XeiCnIpn4RLV cnpmsp
+    target, mark, lines = _lines(root, pins[0][0])
+    for citation, stamp in pins:
+        at = citation["open"] - 1
+        pinned = re.compile(rf"(@req[{OPEN}{SINGLE}]\s+{re.escape(citation['address'])})(?:@\S*)?")
+        # @req> REQ-18833394@iNDqEsjKcVn- gvfbsp
+        lines[at] = pinned.sub(rf"\g<1>@{stamp}", lines[at], count=1)
+    # @req> REQ-36103991@1sBO1pub0_IK wu6oxx
+    return target, (mark + "".join(lines)).encode()
+    # @req- cnpmsp
+
+
+def every(root):
+    held, faults = parse(_sources(root))
+    if faults:
+        # @req> REQ-30898926@Vu28eWaG_1mE 3qmuhz
+        raise ReqctlError("the code's citations do not read:\n" + "\n".join(faults))
+    return held
+
+
+def renamed(root, citation, name):
+    # @req+ REQ-70208796@rx8OkxlDOpk4 4otwfp
+    target, mark, lines = _lines(root, citation)
+    at = citation["open"] - 1
+    address = f"{name}.{citation['entry']}" if citation["entry"] else name
+    pinned = re.compile(rf"(@req[{OPEN}{SINGLE}]\s+){re.escape(citation['address'])}(?=@)")
+    lines[at], done = pinned.subn(lambda found: f"{found.group(1)}{address}",
+                                  lines[at], count=1)
+    if not done:
+        # @req> REQ-30898926@Vu28eWaG_1mE 5hzcy3
+        raise ReqctlError(f"{citation['path']}:{citation['open']}: citation "
+                          f"{citation['id']} does not read as naming "
+                          f"{citation['address']}; nothing was renamed -- "
+                          f"reqctl untag {citation['id']}, then reqctl tag "
+                          "again")
+    return target, (mark + "".join(lines)).encode()
+    # @req- 4otwfp
+
+
+def untagged(root, citation):
+    target, mark, lines = _lines(root, citation)
+    marks = set(citation["marks"])
+    # @req> REQ-81275367@2q0tIHQCM4br 5gkn5k
+    # @req> REQ-26984738@2Cu-ngxaDd6z a4ywox
+    # @req> REQ-36103991@1sBO1pub0_IK vlp2ka
+    return target, (mark + "".join(line for number, line in enumerate(lines, start=1)
+                                   if number not in marks)).encode()
+
+
+def _statement(path, text, first, last):
+    lines = _feed_lines(text)
+    code = [n for n in range(first, last + 1) if lines[n - 1].strip()]
+    if not code or code[0] != first:
+        return False
+    return following(path, text, first - 1, first) == (first, code[-1])
+
+
+# @req> REQ-31471659@hKmNhTkU9xOA k3upi2
+UNREAD = (tokenize.NL, tokenize.ENDMARKER, tokenize.INDENT, tokenize.DEDENT)
+
+
+@functools.cache
+def _stream(text):
+    held, depth = [], 0
+    for token in tokenize.generate_tokens(io.StringIO(text).readline):
+        if token.type == tokenize.INDENT:
+            depth += 1
+        elif token.type == tokenize.DEDENT:
+            depth -= 1
+        held.append((token.start[0], token.type, depth, token.string))
+    return held
+
+
+# @req> REQ-31471659@hKmNhTkU9xOA 4hf3xj
+def _tokens(text, wanted):
+    held, first = [], None
+    for line, kind, depth, string in _stream(text):
+        if line not in wanted or kind in UNREAD:
+            continue
+        first = depth if first is None else first
+        held.append([tokenize.tok_name[kind], depth - first,
+                     "" if kind == tokenize.NEWLINE else string])
+    return held
+
+
+def digest(path, text, lines, reach=None):
+    wanted = set(lines)
+    held = None
+    if Path(path).suffix == ".py":
+        try:
+            # @req> REQ-31471659@hKmNhTkU9xOA suqekj
+            held = _tokens(text, wanted)
+        except (tokenize.TokenError, IndentationError, SyntaxError):
+            held = None
+        # @req+ REQ-59827868@eeHZvhZPFhD3 kwj4mx
+        taken = reach.taken(path, wanted) if held is not None and reach else []
+        if taken:
+            held = [held, taken]
+        # @req- kwj4mx
+    if held is None:
+        # @req+ REQ-15770866@PJj7anRT1m47 soehrs
+        split = [line.rstrip("\r\n") for line in _feed_lines(text)]
+        held = [split[n - 1] for n in sorted(wanted)]
+        # @req- soehrs
+        # @req+ REQ-22608177@cdmX9Aqh6XXC louba3
+        taken = reach.taken(path, wanted) if reach and Path(path).suffix in SCRIPTED else []
+        if taken:
+            held = [held, taken]
+        # @req- louba3
+    return corpus.digest(held)
+
+
+JSON_TOKEN = re.compile(r'(?P<string>"(?:\\.|[^"\\\n])*")'
+                        r"|(?P<number>-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)"
+                        r"|(?P<name>true|false|null)|(?P<op>[{}\[\]:,])"
+                        r"|(?P<space>[ \t\r\n]+)|(?P<other>.)", re.S)
+
+
+# @req> REQ-40478019@_dwqsOpSOQXA udeu7w
+def whole(path, text):
+    if Path(path).suffix == ".py":
+        return digest(path, text, range(1, len(_feed_lines(text)) + 1))
+    held = None
+    if Path(path).suffix == ".json":
+        held = [[found.lastgroup, found.group()] for found in JSON_TOKEN.finditer(text)
+                if found.lastgroup != "space"]
+        if any(kind == "other" for kind, _ in held):
+            held = None
+    return corpus.digest(held if held is not None
+                         else [line.rstrip("\r\n") for line in _feed_lines(text)])
+
+
+def spanned(path, name):
+    # @req> REQ-94119327@SaWRJkHCFkNi gcrrhf
+    if Path(path).suffix != ".py":
+        # @req> REQ-30898926@Vu28eWaG_1mE jmsg5p
+        raise ReqctlError(f"{path}: {name} names a definition only in a .py file -- "
+                          "cite lines of it with --from and --to")
+    source = Path(path).read_bytes().decode().removeprefix(BOM).replace("\r\n", "\n").replace("\r", " ")
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, RecursionError, MemoryError) as error:
+        # @req> REQ-30898926@Vu28eWaG_1mE mgkjni
+        raise ReqctlError(f"{path}: not Python that parses ({error}) -- fix it, or "
+                          "cite lines of it with --from and --to") from error
+    # @req+ REQ-74702510@gU2X5OnlUbY3 6r4imu
+    wanted = name.split(".")
+    found, unwalked = [], [(tree, [])]
+    while unwalked:
+        node, chain = unwalked.pop()
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                here = [*chain, child.name]
+                if here[-len(wanted):] == wanted:
+                    found.append(child)
+                unwalked.append((child, here))
+            elif isinstance(child, (ast.stmt, ast.excepthandler, ast.match_case)):
+                unwalked.append((child, chain))
+    # @req- 6r4imu
+    # @req> REQ-94119327@SaWRJkHCFkNi yvjo27
+    if not found:
+        # @req> REQ-30898926@Vu28eWaG_1mE 6w3pmt
+        raise ReqctlError(f"{path}: no function, class or method is named {name} -- "
+                          "name one the file defines, joining enclosing names with "
+                          "dots, or cite lines with --from and --to")
+    # @req> REQ-73249972@0ct6LD_NhZts 6qhks7
+    if len(found) > 1:
+        # @req> REQ-30898926@Vu28eWaG_1mE pxprub
+        raise ReqctlError(f"{path}: {name} names more than one definition, at lines "
+                          f"{', '.join(str(line) for line in sorted(node.lineno for node in found))} -- join "
+                          "the names enclosing the one meant with dots, or cite "
+                          "lines with --from and --to")
+    # @req+ REQ-74702510@gU2X5OnlUbY3 5jbxzz
+    node = found[0]
+    if not node.decorator_list:
+        return node.lineno, node.end_lineno
+    first = node.decorator_list[0]
+    return max(token.start[0] for token in tokenize.generate_tokens(io.StringIO(source).readline)
+               if token.string == "@" and token.start < (first.lineno, first.col_offset)
+               ), node.end_lineno
+    # @req- 5jbxzz
+
+
+def _rest(text, citation):
+    kept, before = [], 0
+    for number, line in enumerate(_feed_lines(text), start=1):
+        if citation["open"] <= number <= citation["close"] or not line.strip():
+            continue
+        kept.append(line.strip())
+        before += number < citation["open"]
+    return kept, before
+
+
+def crossed(was, was_text, now, now_text):
+    # @req+ REQ-56906371@wq3BL0IRTLVV vvu3g7
+    if was["path"] != now["path"]:
+        return True
+    old, old_before = _rest(was_text, was)
+    new, new_before = _rest(now_text, now)
+    matcher = difflib.SequenceMatcher(None, old, new, autojunk=False)
+    return any((i + k < old_before) != (j + k < new_before)
+               for i, j, size in matcher.get_matching_blocks()
+               for k in range(size))
+    # @req- vvu3g7
+
+
+def _git(root, *args):
+    found = subprocess.run(["git", *args], cwd=root, capture_output=True,
+                           text=True, check=False)
+    if found.returncode:
+        # @req> REQ-30898926@Vu28eWaG_1mE h7pbvo
+        raise ReqctlError(f"git {' '.join(args)}: {found.stderr.strip()} -- "
+                          "install git or put it on PATH, run reqctl inside the "
+                          "repository, or fetch the ref it names, then retry")
+    return found.stdout
+
+
+def _carried(root, commit):
+    # @req> REQ-56906371@wq3BL0IRTLVV q45z6w
+    listed = subprocess.run(
+        ["git", "grep", "-l", "-z", "-E", "@req[+>-]([[:space:]]|$)", commit, "--"],
+        cwd=root, capture_output=True, text=True, check=False)
+    if listed.returncode not in (0, 1):
+        # @req> REQ-30898926@Vu28eWaG_1mE eanwpu
+        raise ReqctlError(f"cannot read {commit}: {listed.stderr.strip()} -- "
+                          "run `git fetch origin`, then retry")
+    for named in filter(None, listed.stdout.split("\0")):
+        relative = named.split(":", 1)[1]
+        yield relative, _git(root, "show", f"{commit}:{relative}").removeprefix(BOM)
+
+
+# @req> REQ-59827868@eeHZvhZPFhD3 jwvhp4
+def _reached_at(root, commit):
+    blobs = [line.split("\t", 1)[1] for line in
+             _git(root, "ls-tree", "-r", "-z", commit).split("\0")
+             if "\t" in line and line.split()[1] == "blob"]
+    base = Path(root)
+    # @req> REQ-22608177@cdmX9Aqh6XXC s4aizn
+    return {path: _git(root, "show", f"{commit}:{path}").removeprefix(BOM)
+            for path in blobs if path.endswith((".py", *SCRIPTED)) and not any(
+                corpus.skipped(base, base / folder) for folder in Path(path).parents[:-1])}
+
+
+def compare(root, ref):
+    commit = _git(root, "merge-base", "HEAD", ref).strip()
+    was_texts = dict(_carried(root, commit))
+    # @req> REQ-35805881@37XtC4gyD98k wge7e5
+    now_texts = {relative: text for relative, text in _sources(root)
+                 if text is None or "@req" in text}
+    was, _ = parse(was_texts.items())
+    now, problems = parse(now_texts.items())
+    if problems:
+        # @req> REQ-30898926@Vu28eWaG_1mE 6swkkb
+        raise ReqctlError("the code's citations do not read:\n"
+                          + "\n".join(problems))
+    # @req+ REQ-36428128@pWyff7uDBZIK a5i7lc
+    before = {c["id"]: c for c in was}
+    after = {c["id"]: c for c in now}
+    # @req- a5i7lc
+    # @req> REQ-59827868@eeHZvhZPFhD3 5swpuo
+    was_reach, now_reach = Reach(_reached_at(root, commit)), Reach(dict(_sources(root)))
+    rows = []
+    for identity in sorted(set(before) | set(after)):
+        old, new = before.get(identity), after.get(identity)
+        # @req+ REQ-56906371@wq3BL0IRTLVV bicxbc
+        if old is None or new is None:
+            held = new or old
+            rows.append({"id": identity, "uid": held["uid"],
+                         "path": held["path"],
+                         "state": ["added"] if old is None else ["deleted"]})
+            continue
+        if (old["path"] == new["path"] and not old["path"].endswith(".py")
+                and was_texts[old["path"]] == now_texts[new["path"]]):
+            continue
+        state = []
+        if crossed(old, was_texts[old["path"]], new, now_texts[new["path"]]):
+            state.append("moved")
+        if (digest(old["path"], was_texts[old["path"]], old["lines"], was_reach)
+                != digest(new["path"], now_texts[new["path"]], new["lines"], now_reach)):
+            state.append("changed")
+        if state:
+            rows.append({"id": identity, "uid": new["uid"], "path": new["path"],
+                         "state": state})
+        # @req- bicxbc
+    # @req> REQ-33614084@XHPdW0ynnY4c ily3i7
+    files = _whole_rows(root, commit)
+    # @req> REQ-70581878@Oua6NaKONA27 w6qryd
+    touched = sorted({row["uid"] for row in rows if row["state"] != ["moved"]}
+                     | {row["uid"] for row in files})
+    return {"base": commit, "citations": rows, "files": files, "touches": touched}
+
+
+def _whole_held(root, commit):
+    listed = subprocess.run(
+        ["git", "grep", "-l", "-z", "-F", corpus.WHOLE_FILES, commit, "--",
+         "requirements"],
+        cwd=root, capture_output=True, text=True, check=False)
+    if listed.returncode not in (0, 1):
+        # @req> REQ-30898926@Vu28eWaG_1mE lxsrkt
+        raise ReqctlError(f"cannot read {commit}: {listed.stderr.strip()} -- "
+                          "run `git fetch origin`, then retry")
+    for named in filter(None, listed.stdout.split("\0")):
+        relative = named.split(":", 1)[1]
+        data = corpus.loads(_git(root, "show", f"{commit}:{relative}"), relative,
+                            aliases=False)
+        if isinstance(data, dict):
+            yield Path(relative).stem, corpus.mapping(data, corpus.WHOLE_FILES)
+
+
+def _whole_text(root, commit, relative):
+    if not _git(root, "ls-tree", "--name-only", commit, "--", relative).strip():
+        return None
+    return _git(root, "show", f"{commit}:{relative}").removeprefix(BOM)
+
+
+def _whole_digest(relative, text):
+    return None if text is None else whole(relative, text)
+
+
+def _whole_rows(root, commit):
+    # @req+ REQ-33614084@XHPdW0ynnY4c 53mrze
+    store, _ = corpus.load(root)
+    renamed_to = {old: item.uid for item in corpus.items(store)
+                  for old in corpus.carried_of(item.uid, item.data)}
+    was = {renamed_to.get(uid, uid): held
+           for uid, held in _whole_held(root, commit)}
+    now = {item.uid: held for item in corpus.items(store)
+           if (held := corpus.mapping(item.data, corpus.WHOLE_FILES))}
+    rows = []
+    for uid in sorted(set(was) | set(now)):
+        held, holds = was.get(uid, {}), now.get(uid, {})
+        for relative in sorted(set(held) | set(holds)):
+            if relative not in held or relative not in holds:
+                rows.append({"uid": uid, "path": relative,
+                             "state": ["added" if relative in holds else "deleted"]})
+                continue
+            target = Path(root) / relative
+            after = (target.read_bytes().decode().removeprefix(BOM)
+                     if target.is_file() else None)
+            if (held[relative] != holds[relative]
+                    or _whole_digest(relative, _whole_text(root, commit, relative))
+                    != _whole_digest(relative, after)):
+                rows.append({"uid": uid, "path": relative, "state": ["changed"]})
+    return rows
+    # @req- 53mrze