reqctl 0.1.38__py3-none-any.whl

reqctl/settings.py

@@ -0,0 +1,183 @@
+import re
+from pathlib import Path
+
+from .baseline import _default_ref, _git
+from .corpus import ReqctlError, loads, mapping
+
+SETTINGS = Path("requirements") / "settings.yml"
+PINNED = re.compile(r"claude-[a-z]+-([0-9]{1,2})(?:-([0-9]{1,2}))?(-[0-9]{8})?")
+DATELESS_FROM = (4, 6)
+AGENTS = "elucidate_agents"
+NESTED = ("nest each value under its data item, entry and field, as "
+          "review_limits: {page_bytes: {quantity: 10485760}}")
+# @req+ REQ-87066486@AtzPEAcAbJ1v 7yxrtp
+# @req> review_limits@m0AH5ohPl52k ulaguu
+REVIEW_LIMITS = {
+    "fetch_attempts": {"quantity": 3},
+    "fetch_seconds": {"quantity": 60},
+    "page_bytes": {"quantity": 5242880},
+    "redirects": {"quantity": 5},
+    "summary_lines": {"quantity": 10},
+}
+# @req> challenge_bounds@M9O-R5iFxL52 j6wvnl
+CHALLENGE_BOUNDS = {
+    "agent_ceiling": {"quantity": 150},
+    "floor_k": {"quantity": 10},
+    "judge_bound": {"quantity": 45},
+    "judge_group": {"quantity": 20},
+    "recall_batch": {"quantity": 40},
+}
+# @req> elucidate_agents@n9BNBtOe7I6g uyqkbs
+ELUCIDATE_AGENTS = {
+    "best_in_class": {"model": "claude-sonnet-5-5", "effort": "high"},
+    "coverage": {"model": "claude-sonnet-5-5", "effort": "high"},
+    "recall": {"model": "claude-sonnet-5-5", "effort": "medium"},
+    "judge": {"model": "claude-opus-5-5", "effort": "high"},
+}
+# @req> portal_token_permissions@vjGyU5xrFJwz xjvwbq
+PORTAL_TOKEN_PERMISSIONS = {
+    "actions": {"access": "read and write"},
+    "contents": {"access": "read"},
+    "pull_requests": {"access": "read"},
+}
+# @req> uncited_code@unpaxg37rwqQ ishqik
+UNCITED_CODE = {
+    "check": {"mode": "off"},
+}
+SHIPPED = {"review_limits": REVIEW_LIMITS, "challenge_bounds": CHALLENGE_BOUNDS,
+           AGENTS: ELUCIDATE_AGENTS,
+           "portal_token_permissions": PORTAL_TOKEN_PERMISSIONS,
+           "uncited_code": UNCITED_CODE}
+# @req- 7yxrtp
+MODES = ("off", "all", "changed_lines", "ratchet")
+
+
+def path(root):
+    return Path(root) / SETTINGS
+
+
+def pinned(value):
+    found = PINNED.fullmatch(value)
+    return bool(found) and ((int(found[1]), int(found[2] or 0)) >= DATELESS_FROM) != bool(found[3])
+
+
+# @req> REQ-42769459@j_YdEMFBAA1J ipg3lp
+def _default(root):
+    try:
+        # @req> REQ-32331515@Nn3qX9jMrAU- myaobz
+        return _default_ref(root)
+    except ReqctlError:
+        return None
+
+
+def _leaves(held, shipped, at):
+    if not isinstance(held, dict) or not isinstance(shipped, dict):
+        yield at, held, shipped
+        return
+    # @req> REQ-99278123@vBQXVC8aZZp3 moafaq
+    if not held and at:
+        yield at, held, shipped
+    for key, value in held.items():
+        yield from _leaves(value, shipped.get(key, {}), (*at, key))
+
+
+def faults(document):
+    if document is None:
+        return []
+    # @req> REQ-99278123@vBQXVC8aZZp3 fv2afe
+    if not isinstance(document, dict):
+        return [f"{document!r} names no value a settings file may replace -- "
+                f"{NESTED}"]
+    found = []
+    for at, value, shipped in _leaves(document, SHIPPED, ()):
+        key = ".".join(map(str, at))
+        # @req> REQ-99278123@vBQXVC8aZZp3 ck7iqy
+        if isinstance(shipped, dict):
+            found.append(f"{key} names no value a settings file may replace -- "
+                         f"{NESTED}")
+        # @req> REQ-78887253@ZroFZuS_zv0q 33gi6b
+        elif type(value) is not type(shipped):
+            # @req> REQ-30898926@Vu28eWaG_1mE aq4jso
+            found.append(f"{key}: {value!r} is not of the YAML type of the "
+                         f"{shipped!r} the product ships -- state a value of "
+                         "that type, on the default branch")
+        # @req> REQ-96727029@rK6NcCslzP2S hrxovc
+        elif at == ("uncited_code", "check", "mode") and value not in MODES:
+            found.append(f"{key}: {value!r} is not a mode -- state off, all, "
+                         "changed_lines or ratchet")
+        # @req> REQ-21585959@QkioE_Ciddeh q7jgw2
+        elif at[-1] == "quantity" and value < 1:
+            # @req> REQ-30898926@Vu28eWaG_1mE c6k5gb
+            found.append(f"{key}: {value!r} is not a whole number of at least "
+                         "one -- state one, on the default branch")
+        # @req> REQ-15362279@YwMnA4sMLpfF 5pi6tp
+        # @req> REQ-82356895@juJepJj5Wt1K rtqqce
+        elif at[-1] == "model" and not pinned(value):
+            found.append(f"{key}: {value!r} is not a pinned model ID, such as "
+                         "claude-opus-5-5")
+    # @req+ REQ-59792666@dkbVbhN0Y4FS sspl2m
+    # @req> REQ-96661837@HbvreaRTySWH 4iahip
+    for entry, fields in mapping(document, AGENTS).items():
+        if (isinstance(fields, dict) and {"model", "effort"} & fields.keys()
+                and not (fields.get("model") and fields.get("effort"))):
+            found.append(f"{AGENTS}.{entry} states a model without an effort, "
+                         "or an effort without a model -- state both")
+    # @req- sspl2m
+    return found
+
+
+# @req> REQ-34403718@OXYW6pAY1oxO 7tnuse
+def read(root):
+    # @req+ REQ-32331515@Nn3qX9jMrAU- 7jdohw
+    ref = _default(root)
+    # @req> REQ-42769459@j_YdEMFBAA1J mfrzc7
+    if ref is None:
+        return None, {}
+    named = SETTINGS.as_posix()
+    where = f"{ref.removeprefix('refs/remotes/')}:{named}"
+    listed = _git(root, "ls-tree", ref, "--", named)
+    # @req> REQ-29005932@BIHyox0VxBlI v2mmft
+    if listed.returncode:
+        # @req> REQ-30898926@Vu28eWaG_1mE 2omnbm
+        raise ReqctlError(f"cannot read the tree {ref} names, so whether it "
+                          f"holds {named} cannot be told: "
+                          f"{listed.stderr.strip()} -- run `git fetch origin`, "
+                          "then retry")
+    # @req> REQ-31526771@dzOAej5vGh2Y wa4iuz
+    if not listed.stdout.strip():
+        return where, {}
+    shown = _git(root, "show", f"{ref}:{named}")
+    # @req> REQ-29005932@BIHyox0VxBlI s4pa57
+    if shown.returncode:
+        # @req> REQ-30898926@Vu28eWaG_1mE vocmcm
+        raise ReqctlError(f"{where} cannot be read: {shown.stderr.strip()} -- "
+                          "restore the file on the default branch")
+    # @req> REQ-29005932@BIHyox0VxBlI mgfbvw
+    document = loads(shown.stdout, where)
+    # @req- 7jdohw
+    found = faults(document)
+    # @req> REQ-99278123@vBQXVC8aZZp3 lcnls5
+    # @req> REQ-78887253@ZroFZuS_zv0q iywc46
+    # @req> REQ-21585959@QkioE_Ciddeh blmk44
+    # @req> REQ-15362279@YwMnA4sMLpfF fxnobd
+    # @req> REQ-59792666@dkbVbhN0Y4FS txoz2e
+    if found:
+        # @req> REQ-30898926@Vu28eWaG_1mE jg7ukv
+        raise ReqctlError(f"{where} cannot be used -- correct it on the "
+                          "default branch:\n"
+                          + "\n".join(f"  {fault}" for fault in found))
+    return where, {".".join(at): value
+                   for at, value, _ in _leaves(document or {}, SHIPPED, ())}
+
+
+# @req> REQ-40447106@_7d9O2HDnoPr jyttul
+# @req> REQ-31526771@dzOAej5vGh2Y ncvzwe
+def table(stated, item):
+    return {entry: {field: stated.get(f"{item}.{entry}.{field}", value)
+                    for field, value in fields.items()}
+            for entry, fields in SHIPPED[item].items()}
+
+
+def quantities(stated, item):
+    return {entry: fields["quantity"]
+            for entry, fields in table(stated, item).items()}

reqctl/typescript.py

@@ -0,0 +1,143 @@
+import functools
+from dataclasses import dataclass, field
+
+import tree_sitter
+import tree_sitter_typescript
+
+GRAMMARS = {".ts": tree_sitter.Language(tree_sitter_typescript.language_typescript()),
+            ".tsx": tree_sitter.Language(tree_sitter_typescript.language_tsx())}
+SUFFIXES = tuple(GRAMMARS)
+KEPT = ("string", "template_string", "regex", "jsx_text")
+TYPED = ("type_annotation", "type_arguments", "type_parameters", "type_alias_declaration",
+         "interface_declaration", "type_query", "implements_clause", "extends_type_clause",
+         "nested_type_identifier", "type_predicate_annotation", "asserts_annotation",
+         "ambient_declaration", "import_statement")
+NAMED = ("identifier", "shorthand_property_identifier")
+TAGS = ("jsx_opening_element", "jsx_closing_element", "jsx_self_closing_element")
+EMBEDDING = ("jsx_expression", "jsx_opening_element", "jsx_self_closing_element")
+DECLARED = ("function_declaration", "generator_function_declaration", "enum_declaration")
+BINDING = ("lexical_declaration", "variable_declaration")
+
+
+@dataclass
+class Reading:
+    spans: list = field(default_factory=list)
+    literals: dict = field(default_factory=dict)
+    regions: list = field(default_factory=list)
+    table: dict = field(default_factory=dict)
+    names: list = field(default_factory=list)
+    imports: set = field(default_factory=set)
+    broken: int | None = None
+
+
+def _bound(node):
+    if node is None:
+        return []
+    if node.type in ("identifier", "shorthand_property_identifier_pattern"):
+        return [node.text.decode()]
+    if node.type == "pair_pattern":
+        return _bound(node.child_by_field_name("value"))
+    if node.type in ("object_assignment_pattern", "assignment_pattern"):
+        return _bound(node.child_by_field_name("left"))
+    if node.type in ("object_pattern", "array_pattern", "rest_pattern"):
+        return [name for child in node.named_children for name in _bound(child)]
+    return []
+
+
+# @req> REQ-45330509@y34lW04HzVzy u54ghq
+def _declarations(root):
+    table = {}
+    for outer in root.named_children:
+        inner = outer.child_by_field_name("declaration") if outer.type == "export_statement" else outer
+        if inner is None:
+            continue
+        span = (outer.start_point.row + 1, outer.end_point.row + 1)
+        if inner.type in DECLARED:
+            names = _bound(inner.child_by_field_name("name"))
+        elif inner.type in BINDING:
+            names = [name for child in inner.named_children if child.type == "variable_declarator"
+                     for name in _bound(child.child_by_field_name("name"))]
+        else:
+            names = []
+        for name in names:
+            table.setdefault(name, []).append(("def", span))
+    return table
+
+
+def _intrinsic(node):
+    parent = node.parent
+    return (parent is not None and parent.type in TAGS
+            and parent.child_by_field_name("name") == node and node.text[:1].islower())
+
+
+def _region(node):
+    if node.type == "jsx_element":
+        opened, closed = node.child_by_field_name("open_tag"), node.child_by_field_name("close_tag")
+        return (opened.end_point if opened else node.start_point,
+                closed.start_point if closed else node.end_point, True)
+    if node.type in EMBEDDING:
+        return node.start_point, node.end_point, False
+    return None
+
+
+def _among(regions, at):
+    held = [region for region in regions if region[0] <= at < region[1]]
+    return bool(held) and max(held, key=lambda region: region[0])[2]
+
+
+def _offsets(text):
+    lines = text.split("\n")
+    starts, at = [], 0
+    for line in lines:
+        starts.append(at)
+        at += len(line) + 1
+    return lambda point: starts[point.row] + len(
+        lines[point.row].encode()[:point.column].decode(errors="ignore"))
+
+
+# @req+ REQ-60833823@pdX0Xr4bVNDt n7el7s
+# @req+ REQ-71419978@R9LaJT-ldfB9 v46n7n
+@functools.cache
+def read(suffix, text):
+    tree = tree_sitter.Parser(GRAMMARS[suffix]).parse(text.encode())
+    reading, offset = Reading(), _offsets(text)
+    reading.table = _declarations(tree.root_node)
+    every, todo = [], [tree.root_node]
+    while todo:
+        node = todo.pop()
+        every.append(node)
+        todo += reversed(node.children)
+    reading.regions = [region for node in every if (region := _region(node)) is not None]
+    reading.broken = next((node.start_point.row + 1 for node in every
+                           if node.is_error or node.is_missing), None)
+    held_until = typed_until = -1
+    for node in every:
+        if node.start_byte >= held_until and (node.type == "comment" or node.type in KEPT):
+            rendered = node.type != "comment" or _among(reading.regions, node.start_point)
+            reading.spans.append((offset(node.start_point), offset(node.end_point), rendered))
+            held_until = node.end_byte
+            if node.type == "template_string":
+                reading.literals.update(dict.fromkeys(
+                    range(node.start_point.row + 2, node.end_point.row + 1), "template literal"))
+        if node.type == "import_statement":
+            reading.imports.update(range(node.start_point.row + 1, node.end_point.row + 2))
+        if node.type in TYPED or node.type.endswith("_type"):
+            typed_until = max(typed_until, node.end_byte)
+        if node.type in NAMED and node.start_byte >= typed_until and not _intrinsic(node):
+            reading.names.append((node.start_point.row + 1, node.text.decode()))
+    return reading
+# @req- v46n7n
+# @req- n7el7s
+
+
+# @req> REQ-62110789@XlGrbQnAd80g 3nom7d
+# @req> REQ-29782682@vNwe2DOIu-N0 ckfd4o
+def blanked(text, marked):
+    return "\n".join(" " * len(line) if number in marked else line
+                     for number, line in enumerate(text.split("\n"), start=1))
+
+
+def embedded(suffix, text, marked):
+    reading = read(suffix, blanked(text, marked))
+    return {**reading.literals, **{number: "JSX element" for number in marked
+                                   if _among(reading.regions, (number - 1, 0))}}

reqctl/uncited.py

@@ -0,0 +1,257 @@
+import ast
+import difflib
+import io
+import re
+import tokenize
+from pathlib import Path, PurePosixPath
+
+from . import cite, corpus, settings, typescript
+from .reach import Reach
+
+RECORD = PurePosixPath("requirements") / "uncited.yml"
+
+# @req> REQ-27534660@OcqGUyoB-NOR zu7qeg
+MODES = settings.MODES[1:]
+# @req> uncited_code_exemptions@UTuKr6P-FxU0 7z5oma
+EXEMPTIONS = {
+    "claude_md": {"files": "any file named CLAUDE.md in any folder"},
+    "claude_rules": {"files": "every file under a .claude/rules folder"},
+    "gitignore": {"files": "any file named .gitignore in any folder"},
+    "license": {"files": "any file whose name begins LICENSE in any folder"},
+    "readme": {"files": "any file named README or README.* in any folder"},
+}
+EXEMPT_FILES = {
+    "claude_md": re.compile(r"(?:^|/)CLAUDE\.md$"),
+    "claude_rules": re.compile(r"(?:^|/)\.claude/rules/"),
+    "gitignore": re.compile(r"(?:^|/)\.gitignore$"),
+    "license": re.compile(r"(?:^|/)LICENSE[^/]*$"),
+    "readme": re.compile(r"(?:^|/)README(?:\.[^/]*)?$"),
+}
+HASHED = (".yml", ".yaml", ".toml", ".sh", ".cfg", ".txt")
+# @req> commentless_formats.json@zjmZ8jE-Au2_ yjmqbb
+COMMENTLESS = (".json",)
+SCRIPT = (("//", None), ("/*", "*/"))
+MARKUP = (("<!--", "-->"),)
+UNREAD = (tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE, tokenize.INDENT,
+          tokenize.DEDENT, tokenize.ENDMARKER)
+IMPORT = re.compile(r"^[ \t]*import\b(?!\s*\()[^;]*?(['\"])[^'\"\n]*\1[ \t]*;?",
+                    re.MULTILINE | re.DOTALL)
+
+
+def _lines(text):
+    return io.StringIO(text).readlines()
+
+
+def _fenced(text, pairs, quoted):
+    quiet, inside = set(), None
+    for number, line in enumerate(_lines(text), 1):
+        code, at = False, 0
+        while at < len(line):
+            if inside:
+                end = line.find(inside, at)
+                at, inside = (len(line), inside) if end < 0 else (end + len(inside), None)
+                continue
+            if quoted and line[at] in "'\"`":
+                close = line.find(line[at], at + 1)
+                code, at = True, len(line) if close < 0 else close + 1
+                continue
+            opened = next((pair for pair in pairs if line.startswith(pair[0], at)), None)
+            if opened and opened[1] is None:
+                break
+            if opened:
+                inside, at = opened[1], at + len(opened[0])
+                continue
+            code = code or not line[at].isspace()
+            at += 1
+        if line.strip() and not code:
+            quiet.add(number)
+    return quiet
+
+
+def _python(text):
+    held = set()
+    try:
+        for token in tokenize.generate_tokens(io.StringIO(text).readline):
+            if token.type not in UNREAD:
+                held.update(range(token.start[0], token.end[0] + 1))
+        tree = ast.parse(text)
+    except (tokenize.TokenError, IndentationError, SyntaxError, ValueError):
+        return set()
+    imports = {line for node in ast.walk(tree) if isinstance(node, (ast.Import, ast.ImportFrom))
+               for line in range(node.lineno, (node.end_lineno or node.lineno) + 1)}
+    return imports | {number for number, line in enumerate(_lines(text), 1)
+                      if line.strip() and number not in held}
+
+
+def _script(text):
+    imports = {line for found in IMPORT.finditer(text)
+               for line in range(text.count("\n", 0, found.start()) + 1,
+                                 text.count("\n", 0, found.end()) + 2)}
+    return imports | _fenced(text, SCRIPT, True)
+
+
+# @req> REQ-58348893@GQ3L2sQGRlkW yvnqdz
+def code_lines(path, text):
+    suffix = PurePosixPath(path).suffix
+    lines = _lines(text)
+    quiet = {number for number, line in enumerate(lines, 1) if not line.strip()}
+    if suffix == ".py":
+        quiet |= _python(text)
+    elif suffix == ".js":
+        quiet |= _script(text)
+    elif suffix in typescript.SUFFIXES:
+        quiet |= typescript.read(suffix, text).imports | cite.remarks(suffix, text)
+    elif suffix == ".sql":
+        quiet |= cite.remarks(suffix, text)
+    elif suffix in (".md", ".html"):
+        quiet |= _fenced(text, MARKUP, False)
+        close = cite._front(text)
+        quiet |= {number for number, line in enumerate(lines, 1)
+                  if 1 < number < close and line.lstrip().startswith("#")}
+        quiet |= {1, close} if close else set()
+    elif suffix in HASHED:
+        quiet |= {number for number, line in enumerate(lines, 1)
+                  if line.lstrip().startswith("#")}
+    return [number for number in range(1, len(lines) + 1) if number not in quiet]
+
+
+# @req> REQ-97409889@RWCU92P-iWbp 2c3ddu
+def exempt(path):
+    return corpus.is_test(path) or any(EXEMPT_FILES[entry].search(path)
+                                       for entry in EXEMPTIONS)
+
+
+def unknown_syntax(path):
+    return PurePosixPath(path).suffix not in (*cite.COMMENTS, *HASHED, *COMMENTLESS)
+
+
+def _moved(path, was, now):
+    before, after = code_lines(path, was), code_lines(path, now)
+    was_lines, now_lines = _lines(was), _lines(now)
+    matcher = difflib.SequenceMatcher(None, [was_lines[n - 1].rstrip("\r\n") for n in before],
+                                      [now_lines[n - 1].rstrip("\r\n") for n in after],
+                                      autojunk=False)
+    return {after[at] for tag, _, _, first, last in matcher.get_opcodes() if tag != "equal"
+            for at in range(first, last)}
+
+
+# @req> REQ-27097724@WuK_Hn1OEs1s a5rd75
+def _changed(root, base, texts):
+    fork = cite._git(root, "merge-base", "HEAD", base).strip()
+    named = cite._git(root, "-c", "core.quotePath=false", "diff", "--name-only",
+                      "--no-renames", "-z", fork, "--").split("\0")
+    named += cite._git(root, "ls-files", "--others", "--exclude-standard", "-z").split("\0")
+    held = set(filter(None, cite._git(root, "ls-tree", "-r", "--name-only", "-z",
+                                      fork).split("\0")))
+    changed = {}
+    for path in filter(None, named):
+        if texts.get(path) is None:
+            continue
+        was = cite._git(root, "show", f"{fork}:{path}") if path in held else ""
+        changed[path] = _moved(path, was, texts[path])
+    return changed
+
+
+def _spans(numbers):
+    spans = []
+    for number in numbers:
+        if spans and spans[-1][1] == number - 1:
+            spans[-1][1] = number
+        else:
+            spans.append([number, number])
+    return spans
+
+
+def _remedy(path, first, last):
+    if PurePosixPath(path).suffix in cite.COMMENTS:
+        return f"cite it with reqctl tag {path} --from {first} --to {last} --req UID"
+    return f"have the item governing it hold the whole file with reqctl tag {path} --req UID"
+
+
+def _uncited(tree, root, citations):
+    texts = {path.replace("\\", "/"): text for path, text in cite._sources(root)}
+    reach = Reach(texts)
+    covered = {(citation["path"], line) for citation in citations
+               for line in citation["lines"]}
+    for citation in citations:
+        covered |= reach.reached(citation["path"], citation["lines"])
+    whole = {path for item in corpus.items(tree)
+             for path in corpus.mapping(item.data, corpus.WHOLE_FILES)}
+    return texts, {path: [line for line in code_lines(path, text) if (path, line) not in covered]
+                   for path, text in sorted(texts.items())
+                   if text is not None and path not in whole and not exempt(path)}
+
+
+def counts(tree, root, citations):
+    return {path: len(lines) for path, lines in _uncited(tree, root, citations)[1].items()
+            if lines}
+
+
+def recorded(root):
+    path = Path(root) / RECORD
+    if not path.exists():
+        return {}
+    held = corpus.read(path)
+    if held is None:
+        return {}
+    if not isinstance(held, dict) or not all(
+            isinstance(key, str) and type(count) is int and count > 0
+            for key, count in held.items()):
+        raise corpus.ReqctlError(f"{RECORD.as_posix()} is not a mapping of file paths to "
+                                 "counts of at least one -- record the uncited counts "
+                                 "with reqctl trace --record")
+    return held
+
+
+# @req> REQ-21635723@CvxpeHCRTgGz arkc4u
+def record(tree, root, citations):
+    corpus.write_all([(Path(root) / RECORD, corpus.dump(counts(tree, root, citations)))])
+
+
+def _ratchet(root, uncited):
+    held, found = recorded(root), []
+    # @req> REQ-91618546@X04wZs4bpj5D 7ckhhs
+    for path, lines in uncited.items():
+        if len(lines) > (was := held.get(path, 0)):
+            found.append(f"{path}: {len(lines)} uncited line(s), above the "
+                         f"{was} {RECORD.as_posix()} states -- cite them with "
+                         f"reqctl tag {path} --from N --to M --req UID, or delete them")
+    # @req> REQ-56849355@Ko7rmWqVFjxy vwtwkp
+    for path, count in sorted(held.items()):
+        if count > (now := len(uncited.get(path, ()))):
+            found.append(f"{path}: {RECORD.as_posix()} states {count} uncited line(s), above "
+                         f"the {now} the file holds -- record the "
+                         "uncited counts with reqctl trace --record")
+    return found
+
+
+# @req> REQ-27534660@OcqGUyoB-NOR tml2jy
+def problems(tree, root, citations, base=None):
+    mode = settings.table(settings.read(root)[1], "uncited_code")["check"]["mode"]
+    if mode not in MODES or (mode == "changed_lines" and not base):
+        return []
+    texts, uncited = _uncited(tree, root, citations)
+    # @req> REQ-91618546@X04wZs4bpj5D u5c2ay
+    # @req> REQ-56849355@Ko7rmWqVFjxy m4cztr
+    if mode == "ratchet":
+        return _ratchet(root, uncited)
+    # @req> REQ-27097724@WuK_Hn1OEs1s jo2uxv
+    changed = _changed(root, base, texts) if mode == "changed_lines" else None
+    found = []
+    for path, uncovered in uncited.items():
+        # @req> REQ-27097724@WuK_Hn1OEs1s x7jy55
+        if changed is not None:
+            uncovered = [line for line in uncovered if line in changed.get(path, ())]
+        # @req+ REQ-33946954@dE-TCnSywwn3 u54yfr
+        # @req+ REQ-46463201@KQkxvX2fdJ1W aoss24
+        if uncovered and unknown_syntax(path):
+            found.append(f"{path}: reqctl knows no comment syntax for this file -- have the "
+                         f"item governing it hold the whole file with reqctl tag {path} "
+                         "--req UID, or add its comment syntax to reqctl")
+            continue
+        # @req- aoss24
+        # @req- u54yfr
+        for first, last in _spans(uncovered):
+            found.append(f"{path}:{first}-{last}: no statement citation covers this code "
+                         f"-- {_remedy(path, first, last)}, or delete it")
+    return found