reqctl 0.1.38__py3-none-any.whl

reqctl/portal.py

@@ -0,0 +1,131 @@
+import base64
+import hashlib
+import json
+import re
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from . import fields as _fields
+from . import settings as _settings
+from . import write as _write
+from .baseline import _git
+from .corpus import ReqctlError
+
+PAGE = Path(__file__).resolve().parent / "portal.html"
+SCRIPT = re.compile(rb"<script>(.*?)</script>", re.S)
+FIELDS_AT = b'<script type="application/json" id="kind-fields">'
+PERMISSIONS_AT = b'<script type="application/json" id="token-permissions">'
+UNSAFE = {ord(char): f"\\u{ord(char):04x}" for char in "<>&"}
+HOST, PORT = "127.0.0.1", 8374
+GITHUB = re.compile(r"(?:(?:https?|ssh|git)://(?:[^@/]+@)?|[^@/:]+@)"
+                    r"(?i:github\.com)[:/]([A-Za-z0-9-]+/[A-Za-z0-9._-]+?)"
+                    r"(?:\.git)?/?")
+USERINFO = re.compile(r"(?<=//)[^@/]+@")
+
+
+def repository(where):
+    # @req+ REQ-95796962@u8QGW_upRZM7 2v7p2v
+    if _git(where, "rev-parse", "--git-dir").returncode:
+        # @req> REQ-30898926@Vu28eWaG_1mE ikwiin
+        raise ReqctlError("not inside a git repository, so no origin remote "
+                          "names the portal's repository -- run `reqctl "
+                          "portal` inside the repository")
+    url = _git(where, "remote", "get-url", "origin").stdout.strip()
+    if not url:
+        # @req> REQ-30898926@Vu28eWaG_1mE ajkroh
+        raise ReqctlError("no origin remote names the portal's repository -- "
+                          "add one naming a GitHub owner/repo")
+    found = GITHUB.fullmatch(url)
+    if found is None:
+        # @req> REQ-30898926@Vu28eWaG_1mE cpeug2
+        raise ReqctlError(f"origin is {USERINFO.sub('', url)}, not a GitHub "
+                          "owner/repo -- set it with `git remote set-url "
+                          "origin https://github.com/OWNER/REPO`")
+    # @req- 2v7p2v
+    # @req> REQ-53764133@s638VvRMfEgi mbl5cu
+    return found.group(1)
+
+
+# @req+ REQ-87847146@3MkrB9EtSIEF avcfk3
+# @req> REQ-69283350@vYYldulaXQvc cgzp5c
+# @req> REQ-14679866@V0QsDEPmgOq3 357tly
+def _offered(kind, field):
+    once = kind == "parameter" and field.name == _fields.ENTRIES
+    return {"name": field.name, "flag": field.flag[2:], "required": field.required,
+            "repeated": field.repeated and not once, "prose": field.prose,
+            "choices": list(field.choices), "parts": list(field.parts),
+            "clears": field.clears and field.clears[2:],
+            "drops": field.drops and field.drops[2:],
+            "form": _write.FORMS.get(field.name)}
+
+
+# @req> REQ-21522236@jupFEITq3Nms vldi2d
+def forms(root):
+    offered = {}
+    for kind in _write.KINDS:
+        own = _fields.of(root, kind)
+        offered[kind] = {"new": [_offered(kind, field) for field in own],
+                         "revise": [_offered(kind, field) for field
+                                    in _write.revisable_fields(own, kind)
+                                    if not field.address]}
+    return offered
+
+
+def with_forms(page, root):
+    before, after = page.split(FIELDS_AT)
+    return before + FIELDS_AT + json.dumps(forms(root)).translate(UNSAFE).encode() + after
+# @req- avcfk3
+
+
+# @req> REQ-40447106@_7d9O2HDnoPr uwkxa6
+# @req> REQ-84459416@ZlrZpYNBUh8Q ufhxxr
+def with_permissions(page, root):
+    _, stated = _settings.read(root)
+    before, after = page.split(PERMISSIONS_AT)
+    return (before + PERMISSIONS_AT + json.dumps(_settings.table(
+        stated, "portal_token_permissions")).translate(UNSAFE).encode() + after)
+
+
+# @req> REQ-56725181@knOj5NP_RuL_ 52i7vh
+def policy_of(page):
+    script = SCRIPT.search(page).group(1).replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+    held = base64.b64encode(hashlib.sha256(script).digest())
+    return (f"default-src 'none'; script-src 'sha256-{held.decode()}'; "
+            "style-src 'unsafe-inline'; connect-src https://api.github.com; "
+            "form-action 'none'")
+
+
+# @req> REQ-49576265@pFihs7WdIwGS 6hnjpw
+class Page(BaseHTTPRequestHandler):
+    body = b""
+    policy = ""
+
+    def do_GET(self):
+        if urlsplit(self.path).path != "/":
+            self.send_error(404)
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        # @req> REQ-56725181@knOj5NP_RuL_ fml6m3
+        self.send_header("Content-Security-Policy", self.policy)
+        self.send_header("Content-Length", str(len(self.body)))
+        self.end_headers()
+        self.wfile.write(self.body)
+
+    def log_message(self, *_):
+        pass
+
+
+# @req> REQ-49576265@pFihs7WdIwGS uor45m
+def server():
+    root = _fields.root()
+    Page.body = with_permissions(with_forms(PAGE.read_bytes(), root), root)
+    Page.policy = policy_of(Page.body)
+    try:
+        return ThreadingHTTPServer((HOST, PORT), Page)
+    except OSError as busy:
+        # @req> REQ-30898926@Vu28eWaG_1mE g5ihnj
+        raise ReqctlError(f"cannot serve the portal at {HOST}:{PORT}: "
+                          f"{busy.strerror} -- stop whatever holds the port, "
+                          "then retry") from busy

reqctl/reach.py

@@ -0,0 +1,425 @@
+import ast
+import io
+import keyword
+import posixpath
+import re
+import tokenize
+
+from . import corpus, typescript
+
+SCRIPTED = (".js", ".html", *typescript.SUFFIXES)
+CLASSIC = re.compile(r"<script(?=[\s/>])(?P<attrs>[^>]*)>(?P<body>[\s\S]*?)"
+                     r"(?:</script(?=[\s/>])|\Z)", re.IGNORECASE)
+TYPED = re.compile(r"""\btype\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))""", re.IGNORECASE)
+JAVASCRIPT = {"", "text/javascript", "application/javascript", "text/ecmascript",
+              "application/ecmascript"}
+LEXED = re.compile(r""""(?:\\[\s\S]|[^"\\\n])*"|'(?:\\[\s\S]|[^'\\\n])*'"""
+                   r"|(?P<tick>`)|(?P<brace>[{}])"
+                   r"|(?P<remark>//[^\n]*|/\*[\s\S]*?(?:\*/|\Z)|<!--[^\n]*|^[ \t]*-->[^\n]*)"
+                   r"|(?P<pattern>/(?![*/])(?:\\.|\[(?:\\.|[^\]\\\n])*\]|[^/\\\n\[])+/[A-Za-z]*)",
+                   re.MULTILINE)
+PATTERN_AFTER = set("(,=:[!&|?{};+-*%<>~^")
+PATTERN_WORDS = {"return", "typeof", "case", "do", "else", "in", "of", "new", "delete", "void",
+                 "throw", "yield", "await", "instanceof"}
+PIECE = re.compile(r"[A-Za-z_$][\w$]*|\d[\w.]*|\.\.\.|[-+*/%&|^!<>=?:~]+|[{}()\[\];,.]")
+IDENTIFIER = re.compile(r"[A-Za-z_$][\w$]*\Z")
+CONTINUING = re.compile(r"(?!\+\+\Z|--\Z)[-+*/%&|^!<>=?:~]+\Z|[(\[,.]\Z|\.\.\.\Z")
+OPENS, CLOSES = "{([", "})]"
+BINDINGS = ("const", "let", "var")
+
+# @req+ REQ-59827868@eeHZvhZPFhD3 4pmkcf
+DEFINED = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+ASSIGNED = (ast.Assign, ast.AnnAssign)
+NESTED = (ast.If, ast.Try, ast.TryStar)
+UNREAD = (tokenize.COMMENT, tokenize.NL, tokenize.ENDMARKER, tokenize.INDENT,
+          tokenize.DEDENT)
+
+
+def _statements(body):
+    for node in body:
+        yield node
+        if isinstance(node, NESTED):
+            for branch in ("body", "orelse", "finalbody"):
+                yield from _statements(getattr(node, branch, []))
+            for handler in getattr(node, "handlers", []):
+                yield from _statements(handler.body)
+
+
+def _bound(target):
+    if isinstance(target, ast.Name):
+        yield target.id
+    elif isinstance(target, (ast.Tuple, ast.List)):
+        for element in target.elts:
+            yield from _bound(element)
+
+
+def _span(node):
+    first = min([node.lineno, *(d.lineno for d in getattr(node, "decorator_list", []))])
+    return first, node.end_lineno or node.lineno
+
+
+class Reach:
+    def __init__(self, texts):
+        # @req> REQ-22608177@cdmX9Aqh6XXC 2ap6ns
+        self.texts = {path.replace("\\", "/"): text for path, text in texts.items()
+                      if text is not None and path.endswith((".py", *SCRIPTED))}
+        packages = {posixpath.dirname(path) for path in self.texts
+                    if posixpath.basename(path) == "__init__.py"}
+        self.roots = [".", *sorted({posixpath.dirname(folder) or "." for folder in packages
+                                    if posixpath.dirname(folder) not in packages})]
+        self.tables, self.streams, self.edges, self.digests = {}, {}, {}, {}
+        self.scripts = {}
+
+    # @req> REQ-22608177@cdmX9Aqh6XXC upntcv
+    # @req> REQ-45330509@y34lW04HzVzy ad2sq3
+    # @req> REQ-71419978@R9LaJT-ldfB9 eci2zb
+    def _scripted(self, path):
+        if path not in self.scripts:
+            self.scripts[path] = (_typed(path, self.texts[path]) if path.endswith(typescript.SUFFIXES)
+                                  else _script(path, self.texts[path]))
+        return self.scripts[path]
+
+    def _module(self, base):
+        base = posixpath.normpath(base)
+        for found in (base + ".py", posixpath.join(base, "__init__.py")):
+            if found in self.texts:
+                return found
+        return None
+
+    def _absolute(self, dotted, near):
+        for root in (posixpath.dirname(near) or ".", *self.roots):
+            found = self._module(posixpath.join(root, *dotted.split(".")))
+            if found:
+                return found
+        return None
+
+    def _relative(self, near, level, dotted):
+        base = posixpath.dirname(near)
+        for _ in range(level - 1):
+            base = posixpath.dirname(base)
+        return self._module(posixpath.join(base or ".", *(dotted or "").split(".")))
+
+    def _table(self, path):
+        if path in self.tables:
+            return self.tables[path]
+        # @req> REQ-22608177@cdmX9Aqh6XXC wgjme7
+        # @req> REQ-45330509@y34lW04HzVzy egzrhu
+        if path.endswith(SCRIPTED):
+            self.tables[path] = (_reading(path, self.texts[path]).table
+                                 if path.endswith(typescript.SUFFIXES)
+                                 else _declarations(self._scripted(path)[0]))
+            return self.tables[path]
+        table = self.tables[path] = {}
+        try:
+            tree = ast.parse(self.texts[path])
+        except (SyntaxError, ValueError):
+            return table
+        for node in _statements(tree.body):
+            if isinstance(node, DEFINED):
+                table.setdefault(node.name, []).append(("def", _span(node)))
+            elif isinstance(node, ASSIGNED):
+                targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+                for target in targets:
+                    for name in _bound(target):
+                        table.setdefault(name, []).append(("def", _span(node)))
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    dotted = alias.name if alias.asname else alias.name.split(".")[0]
+                    found = self._absolute(dotted, path)
+                    if found:
+                        table.setdefault(alias.asname or dotted, []).append(("module", found))
+            elif isinstance(node, ast.ImportFrom):
+                source = (self._relative(path, node.level, node.module) if node.level
+                          else self._absolute(node.module or "", path))
+                for alias in node.names:
+                    if source and alias.name != "*":
+                        table.setdefault(alias.asname or alias.name, []).append(
+                            ("from", (source, alias.name)))
+        return table
+
+    def _within(self, module, rest, seen):
+        if not rest:
+            return []
+        held = self._resolve(module, rest, seen)
+        if held or not module.endswith("__init__.py"):
+            return held
+        below = self._module(posixpath.join(posixpath.dirname(module), rest[0]))
+        return self._within(below, rest[1:], seen) if below else []
+
+    def _resolve(self, path, chain, seen=frozenset()):
+        head, rest = chain[0], chain[1:]
+        found = []
+        for kind, what in self._table(path).get(head, []):
+            if kind == "def":
+                found.append((path, head))
+            elif kind == "module":
+                found += self._within(what, rest, seen)
+            elif kind == "from" and what not in seen:
+                source, name = what
+                found += self._within(source, (name, *rest), seen | {what})
+        return found
+
+    def _stream(self, path):
+        if path not in self.streams:
+            held, depth = [], 0
+            try:
+                for token in tokenize.generate_tokens(io.StringIO(self.texts[path]).readline):
+                    depth += {tokenize.INDENT: 1, tokenize.DEDENT: -1}.get(token.type, 0)
+                    held.append((token.start[0], token.type, depth, token.string))
+            except (tokenize.TokenError, IndentationError, SyntaxError):
+                held = []
+            self.streams[path] = held
+        return self.streams[path]
+
+    def _chains(self, path, lines):
+        chains, chain, after_dot = [], [], False
+        for line, kind, _, text in self._stream(path):
+            if line not in lines or kind in UNREAD:
+                continue
+            if kind == tokenize.NAME and not keyword.iskeyword(text):
+                if after_dot:
+                    if chain:
+                        chain.append(text)
+                else:
+                    if chain:
+                        chains.append(tuple(chain))
+                    chain = [text]
+                after_dot = False
+                continue
+            after_dot = kind == tokenize.OP and text == "."
+            if not after_dot and chain:
+                chains.append(tuple(chain))
+                chain = []
+        if chain:
+            chains.append(tuple(chain))
+        return chains
+
+    def _lines(self, key):
+        path, name = key
+        return {line for kind, span in self._table(path).get(name, []) if kind == "def"
+                for line in range(span[0], span[1] + 1)}
+
+    def _calls(self, path, lines):
+        # @req> REQ-22608177@cdmX9Aqh6XXC um45e2
+        # @req> REQ-71419978@R9LaJT-ldfB9 oyqqn7
+        if path.endswith(SCRIPTED):
+            pieces, table = self._scripted(path)[0], self._table(path)
+            return [(path, name) for name in dict.fromkeys(
+                piece for at, (line, piece) in enumerate(pieces)
+                if line in lines and piece in table and (at == 0 or pieces[at - 1][1] != "."))]
+        return [found for chain in dict.fromkeys(self._chains(path, lines))
+                for found in self._resolve(path, chain)]
+
+    def _digest(self, key):
+        # @req> REQ-22608177@cdmX9Aqh6XXC g2mzok
+        if key not in self.digests and key[0].endswith(SCRIPTED):
+            said, remarks = self.texts[key[0]].split("\n"), self._scripted(key[0])[1]
+            self.digests[key] = corpus.digest([said[n - 1].rstrip() for n in sorted(self._lines(key))
+                                               if n not in remarks])
+        if key not in self.digests:
+            lines = self._lines(key)
+            held, first = [], None
+            for line, kind, depth, text in self._stream(key[0]):
+                if line in lines and kind not in UNREAD:
+                    first = depth if first is None else first
+                    held.append([tokenize.tok_name[kind], depth - first,
+                                 "" if kind == tokenize.NEWLINE else text])
+            self.digests[key] = corpus.digest(
+                held or [self.texts[key[0]].splitlines()[n - 1] for n in sorted(lines)])
+        return self.digests[key]
+
+    def _closure(self, path, lines):
+        path = path.replace("\\", "/")
+        if path not in self.texts:
+            return set()
+        todo, seen = self._calls(path, set(lines)), set()
+        while todo:
+            key = todo.pop()
+            if key in seen:
+                continue
+            seen.add(key)
+            if key not in self.edges:
+                self.edges[key] = self._calls(key[0], self._lines(key))
+            todo += self.edges[key]
+        return seen
+
+    def taken(self, path, lines):
+        return [[held, name, self._digest((held, name))]
+                for held, name in sorted(self._closure(path, lines))]
+
+    def reached(self, path, lines):
+        return {(key[0], line) for key in self._closure(path, lines)
+                for line in self._lines(key)}
+# @req- 4pmkcf
+
+
+def _reading(path, text):
+    return typescript.read(posixpath.splitext(path)[1], text)
+
+
+def remarked(text, spans):
+    chars = list(text)
+    for start, end, kept in spans:
+        if not kept:
+            _blanked(chars, start, end)
+    return {number for number, (said, kept) in
+            enumerate(zip(text.split("\n"), "".join(chars).split("\n")), start=1)
+            if said.strip() and not kept.strip()}
+
+
+def _typed(path, text):
+    reading = _reading(path, text)
+    return reading.names, remarked(text, reading.spans)
+
+
+def _blanked(chars, start, end):
+    for at in range(start, end):
+        if chars[at] != "\n":
+            chars[at] = " "
+
+
+def _bodies(path, text):
+    if path.endswith(".js"):
+        return [(0, len(text))]
+    held = []
+    for script in CLASSIC.finditer(text):
+        typed = TYPED.search(script["attrs"])
+        kind = next((one for one in typed.groups() if one is not None), "") if typed else ""
+        if kind.strip().lower() in JAVASCRIPT:
+            held.append(script.span("body"))
+    return held
+
+
+def _opens_pattern(text, at):
+    back = at - 1
+    while back >= 0 and text[back].isspace():
+        back -= 1
+    if back < 0 or text[back] in PATTERN_AFTER:
+        return True
+    word = back
+    while word >= 0 and (text[word].isalnum() or text[word] in "_$"):
+        word -= 1
+    return text[word + 1:back + 1] in PATTERN_WORDS
+
+
+def _lexed(text, at, end, code, bare, closing):
+    depth = 0
+    while (found := LEXED.search(text, at, end)) is not None:
+        start, at = found.start(), found.end()
+        if found["brace"] is not None:
+            if closing and found[0] == "{":
+                depth += 1
+            elif closing and depth:
+                depth -= 1
+            elif closing:
+                return at
+        elif found["tick"] is not None:
+            at = _template(text, at, end, code, bare)
+            code[start] = "0"
+        elif found["pattern"] is not None and not _opens_pattern(text, start):
+            at = start + 1
+        else:
+            _blanked(code, start, at)
+            if found["remark"] is not None:
+                _blanked(bare, start, at)
+            else:
+                code[start] = "0"
+    return end
+
+
+def _template(text, at, end, code, bare):
+    start = at - 1
+    while at < end:
+        if text[at] == "\\":
+            at += 2
+        elif text[at] == "`":
+            _blanked(code, start, at + 1)
+            return at + 1
+        elif text.startswith("${", at):
+            _blanked(code, start, at + 2)
+            at = _lexed(text, at + 2, end, code, bare, closing=True)
+            start = at - 1
+        else:
+            at += 1
+    _blanked(code, start, end)
+    return end
+
+
+def _script(path, text):
+    code, bare, at = list(text), list(text), 0
+    for start, end in [*_bodies(path, text), (len(text), len(text))]:
+        for chars in (code, bare):
+            _blanked(chars, at, start)
+        _lexed(text, start, end, code, bare, closing=False)
+        at = end
+    pieces, line, last = [], 1, 0
+    joined = "".join(code)
+    for found in PIECE.finditer(joined):
+        line += joined.count("\n", last, found.start())
+        last = found.start()
+        pieces.append((line, found[0]))
+    remarks = {number for number, (said, kept) in
+               enumerate(zip(text.split("\n"), "".join(bare).split("\n")), start=1)
+               if said.strip() and not kept.strip()}
+    return pieces, remarks
+
+
+def _declared(pieces, at):
+    names, depth, kind = [], 0, pieces[at][1]
+    at += 1
+    if kind == "function":
+        while at < len(pieces) and pieces[at][1] == "*":
+            at += 1
+        if at < len(pieces) and IDENTIFIER.match(pieces[at][1]):
+            names.append(pieces[at][1])
+        opened = False
+        while at < len(pieces):
+            line, piece = pieces[at]
+            opened = opened or (piece == "{" and depth == 0)
+            depth += (piece in OPENS) - (piece in CLOSES)
+            at += 1
+            if opened and depth == 0:
+                return names, line, at
+        return names, pieces[-1][0], at
+    expecting, patterned = True, False
+    while at < len(pieces):
+        line, piece = pieces[at]
+        if depth == 0 and (piece in BINDINGS or piece == "function" and _starts(pieces, at)):
+            return names, pieces[at - 1][0], at
+        at += 1
+        opening = depth == 0 and expecting and piece in ("{", "[")
+        if IDENTIFIER.match(piece) and (depth == 0 and expecting or patterned):
+            names.append(piece)
+        if depth == 0:
+            expecting = piece == ","
+            if piece == ";":
+                return names, line, at
+        depth += (piece in OPENS) - (piece in CLOSES)
+        patterned = (patterned or opening) and depth > 0
+    return names, pieces[-1][0], at
+
+
+def _starts(pieces, at):
+    if at == 0:
+        return True
+    line, before = pieces[at - 1]
+    if before in ("async", "export", "default") and (at < 2 or pieces[at - 2][1] != "."):
+        return _starts(pieces, at - 1)
+    return before in (";", "}") or (line < pieces[at][0] and not CONTINUING.match(before))
+
+
+def _declarations(pieces):
+    table, depth, at = {}, 0, 0
+    while at < len(pieces):
+        line, piece = pieces[at]
+        if depth == 0 and (piece in BINDINGS and (at == 0 or pieces[at - 1][1] != ".")
+                           or piece == "function" and _starts(pieces, at)):
+            first = (pieces[at - 1][0] if piece == "function" and at
+                     and pieces[at - 1][1] == "async" else line)
+            names, last, at = _declared(pieces, at)
+            for name in names:
+                table.setdefault(name, []).append(("def", (first, last)))
+            continue
+        depth += (piece in OPENS) - (piece in CLOSES)
+        at += 1
+    return table

reqctl/resolve.py

@@ -0,0 +1,74 @@
+from .corpus import (CITATION_LIST, CONFLICTED, Item, ReqctlError, loads,
+                     mapping, path_for, read_text, same, save, sides)
+
+PINS = "assessed"
+GONE = object()
+
+
+def _side(text, where):
+    # @req> REQ-49870454@KKNV-vdY6oM1 ilmqvb
+    held = loads(text, where, aliases=False)
+    if not isinstance(held, dict):
+        # @req> REQ-30898926@Vu28eWaG_1mE hjcyzp
+        raise ReqctlError(
+            f"{where.stem} holds an unresolved merge, and a side of it does "
+            "not read as an item -- settle it by hand"
+        )
+    return held
+
+
+def _reached(path, text):
+    ours, theirs = (_side(side, path) for side in sides(text))
+    pinned = all(isinstance(held.get(PINS), dict) for held in (ours, theirs))
+    skipped = ({PINS} if pinned else set()) | {CITATION_LIST}
+    spoken = {key: value for key, value in ours.items() if key not in skipped}
+    answered = {key: value for key, value in theirs.items() if key not in skipped}
+    return ours, theirs, skipped, spoken, sorted(
+        str(key) for key in set(spoken) | set(answered)
+        if not same(spoken.get(key, GONE), answered.get(key, GONE)))
+
+
+# @req> REQ-38498011@eJXtv0pwMf-A rm5na2
+def merged(path, text):
+    # @req+ REQ-38498011@eJXtv0pwMf-A 3sjv5b
+    try:
+        reached = _reached(path, text)[-1]
+    except ReqctlError:
+        # @req> REQ-30898926@Vu28eWaG_1mE damfks
+        return f"{path} holds an unresolved merge -- settle it by hand"
+    if not reached:
+        return (f"{path} holds an unresolved merge within its pins and citation "
+                f"list -- `reqctl resolve {path.stem}` settles it")
+    # @req> REQ-30898926@Vu28eWaG_1mE zsxafm
+    return (f"{path} holds an unresolved merge reaching {', '.join(reached)}, "
+            "outside its pins and citation list -- settle it by hand")
+    # @req- 3sjv5b
+
+
+def resolve(store, uid):
+    # @req+ REQ-95299157@dJzPK-VOKyQG w4qjbn
+    path = path_for(store.root, uid)
+    text = read_text(path)
+    if not CONFLICTED.search(text):
+        # @req> REQ-30898926@Vu28eWaG_1mE wlfoj4
+        raise ReqctlError(f"{uid} holds no unresolved merge -- nothing to resolve")
+    ours, theirs, skipped, spoken, reached = _reached(path, text)
+    if reached:
+        # @req> REQ-30898926@Vu28eWaG_1mE vxs7av
+        raise ReqctlError(
+            f"{uid}: the merge reaches {', '.join(reached)}, outside its pins "
+            f"and citation list -- settle {'it' if len(reached) == 1 else 'them'}"
+            " by hand"
+        )
+    held = dict(spoken)
+    dropped = {}
+    for key in sorted(skipped):
+        mine, yours = mapping(ours, key), mapping(theirs, key)
+        kept = {name: value for name, value in mine.items()
+                if same(yours.get(name, GONE), value)}
+        if kept or key == PINS:
+            held[key] = kept
+        dropped[key] = sorted((set(mine) | set(yours)) - set(kept))
+    save(store, Item(uid, path, held))
+    return path, dropped.get(PINS, []), dropped[CITATION_LIST]
+# @req- w4qjbn

reqctl/schemas/baseline.schema.yaml

@@ -0,0 +1,42 @@
+# @req> REQ-97751594@BwWOFlFOjjyU dlcdx3
+$schema: "https://json-schema.org/draft/2020-12/schema"
+# @req> REQ-83218477@nthDaUhwd58l ch4k3s
+$id: "reqctl/baseline.schema.yaml"
+# @req> REQ-52846482@4k8T0YLN4n97 uuo4su
+type: object
+# @req> REQ-20678879@c210nefD6kHQ 3jp6m3
+additionalProperties: false
+
+# @req> REQ-10511199@UQZ6Ch88aIpW ucy2b5
+# @req> REQ-85783763@3jU8EBlXjjXR u3vnla
+# @req> REQ-14619822@tGPby0EQMjQz h5lv42
+# @req> REQ-54257918@2pAThuxToYwU dvuoot
+required: [baseline, commit, items, supersedes]
+
+# @req> REQ-20678879@c210nefD6kHQ qke5hh
+properties:
+
+  # @req> REQ-10511199@UQZ6Ch88aIpW zv72fc
+  baseline:
+    type: integer
+    minimum: 1
+
+  # @req> REQ-85783763@3jU8EBlXjjXR er6rq5
+  commit:
+    type: string
+    pattern: "^[0-9a-f]{40}$"
+
+  # @req> REQ-14619822@tGPby0EQMjQz zpbdvj
+  supersedes:
+    type: [integer, "null"]
+
+  # @req> REQ-54257918@2pAThuxToYwU cpbxhm
+  items:
+    type: object
+    minProperties: 1
+    # @req> REQ-64078604@z4ggvy8qxGN6 bwtwmt
+    propertyNames:
+      pattern: "^((REQ|GUARD|PARAM|TERM|DATA)-[0-9]{8}|[a-z][a-z0-9_]*)$"
+    additionalProperties:
+      type: string
+      minLength: 1