linecite 0.1.1__py3-none-any.whl

linecite/__init__.py

@@ -0,0 +1,3 @@
+"""linecite — code citations in docs that re-derive their line numbers from the source."""
+
+__version__ = "0.1.1"

linecite/adopt.py

@@ -0,0 +1,195 @@
+"""Convert number-only citations into citations that name their code, using the history `audit` reads.
+
+Markdown gets the link form; every other document a hidden anchor right after the number:
+
+    orders.py:10  ->  [orders.py:12](../app/orders.py#L12 "OrderService.create_order: row.lock()")
+    orders.py:10  ->  orders.py:12<!--@ app/orders.py::OrderService.create_order `row.lock()` -->
+
+The number written into the new citation is where the cited line is now by audit's trace — never
+line N of today's code, which would freeze a number that is already stale. Only ok and stale
+citations are converted; gone, unknown and unverifiable ones are left for a human. Every proposal
+is read back through `extract` and resolved before it is offered, so an applied proposal passes `check`.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .audit import OK, STALE, Traced, Tracer, number_only, renumber
+from .config import Config
+from .errors import RefError
+from .repo import Repo
+from .scan import MARKDOWN_SUFFIXES, Syntax, code_spans, extract, line_of
+from .spec import describe, resolve
+
+# [bracketed text] on one line, one level of nesting: link texts (inline or reference-style) and the like
+BRACKETS_RE = re.compile(r"\[(?:[^\[\]\n]|\[[^\[\]\n]*\])*\]")
+
+
+@dataclass
+class Proposal:
+    traced: Traced
+    start: int
+    end: int
+    new: str
+
+
+@dataclass
+class DocPlan:
+    """What adopt would do to one document."""
+
+    path: Path
+    text: str
+    proposals: list[Proposal] = field(default_factory=list)
+    left: list[tuple[Traced, str]] = field(default_factory=list)  # (citation, why)
+
+    def converted(self) -> str:
+        out, last = [], 0
+        for p in sorted(self.proposals, key=lambda p: p.start):
+            out += [self.text[last : p.start], p.new]
+            last = p.end
+        out.append(self.text[last:])
+        return "".join(out)
+
+
+def link_url(doc: Path, repo: Repo, path: str) -> str:
+    """How a link from DOC names PATH: relative when the doc lives in the code repo, else from the code root."""
+    doc = doc.resolve()
+    if not doc.is_relative_to(repo.root):
+        return path
+    rel = Path(os.path.relpath(repo.root / path, doc.parent)).as_posix()
+    kept = "/".join(p for p in rel.split("/") if p not in ("", ".", ".."))
+    return (
+        rel if kept == path else "/" + path
+    )  # links resolve by suffix; keep the whole path
+
+
+def title_attr(title: str, in_table: bool = False) -> str:
+    title = title.replace("\\", "\\\\").replace('"', '\\"')
+    if in_table:  # an unescaped | ends a table cell, even inside a link title
+        title = title.replace("|", "\\|")
+    return f'"{title}"'
+
+
+def _line_at(text: str, pos: int) -> str:
+    start = text.rfind("\n", 0, pos) + 1
+    end = text.find("\n", pos)
+    return text[start : end if end >= 0 else len(text)]
+
+
+@dataclass
+class _Doc:
+    path: Path
+    text: str
+    brackets: list[tuple[int, int]]  # [bracketed] spans: text of other links
+    code: list[tuple[int, int]]  # markdown inline `code` spans
+
+    @classmethod
+    def of(cls, path: Path, text: str) -> _Doc:
+        markdown = path.suffix.lower() in MARKDOWN_SUFFIXES
+        return cls(
+            path,
+            text,
+            [m.span() for m in BRACKETS_RE.finditer(text)] if markdown else [],
+            code_spans(text) if markdown else [],
+        )
+
+
+def _check(
+    d: _Doc,
+    start: int,
+    end: int,
+    new: str,
+    syntax: Syntax,
+    repo: Repo,
+    want: tuple[int, int],
+) -> None:
+    """Read the document back with the replacement in place, as `check` will: the replaced region must
+    hold exactly one link or anchor, resolving to WANT with nothing to sync. In place matters —
+    `!` before a link makes it an image, a surrounding code span makes it literal text."""
+    after = d.text[:start] + new + d.text[end:]
+    lo, hi = start, start + len(new)
+    cites = [
+        c for c in extract(after, d.path, syntax)[0] if c.start < hi and lo < c.end
+    ]
+    if len(cites) != 1 or cites[0].kind not in ("link", "anchor") or cites[0].error:
+        raise RefError("the converted citation would not read back as a citation here")
+    _, a, b = resolve(repo, cites[0].spec)
+    if (a, b) != want or any(s.render(a, b) != s.old for s in cites[0].slots):
+        raise RefError(
+            f"the converted citation would resolve to {a}-{b}, not {want[0]}-{want[1]}"
+        )
+
+
+def _within(pos: int, spans: list[tuple[int, int]]) -> tuple[int, int] | None:
+    return next(((s, e) for s, e in spans if s <= pos < e), None)
+
+
+def propose(d: _Doc, t: Traced, repo: Repo, syntax: Syntax) -> Proposal:
+    """The replacement for one traced citation; RefError says why there is none."""
+    if t.status not in (OK, STALE):
+        raise RefError(t.note or t.status)
+    if len(t.spans) != 1:
+        raise RefError("a list of lines: give each line its own citation first")
+    (a, b), c, text = t.spans[0], t.citation, d.text
+    naming = describe(repo, t.path, a, b)
+    frag = f"#L{a}" if a == b else f"#L{a}-L{b}"
+    title = title_attr(naming.title(), _line_at(text, c.start).lstrip().startswith("|"))
+    start, end = c.start, c.end
+
+    if c.kind == "bare-link":
+        # the author's own text and url, renumbered; the url is replaced only if the file moved
+        body, _, url = renumber(text, c, t.spans)[1:].partition("](")
+        url = url.partition("#")[0]
+        try:
+            same_file = repo.resolve_path(c.cited.path, None) == t.path
+        except RefError:
+            same_file = False
+        if not same_file:
+            url = link_url(d.path, repo, t.path)
+        new = f"[{body}]({url}{frag} {title})"
+    elif d.path.suffix.lower() in MARKDOWN_SUFFIXES:
+        if _within(c.start, d.brackets):
+            raise RefError("inside [brackets], such as another link's text")
+        # a link inside inline code renders as literal text: the whole code span becomes the link text
+        start, end = _within(c.start, d.code) or (start, end)
+        label = text[start : c.start] + t.now + text[c.end : end]
+        new = f"[{label}]({link_url(d.path, repo, t.path)}{frag} {title})"
+    else:
+        spec = naming.spec()
+        if "-->" in spec:
+            raise RefError("the quoted code contains `-->`, which would end the anchor")
+        new = f"{t.now}<!--@ {spec} -->"
+    _check(d, start, end, new, syntax, repo, (a, b))
+    return Proposal(t, start, end, new)
+
+
+def plan(files: list[Path], repo: Repo, cfg: Config) -> list[DocPlan]:
+    tracer = Tracer(repo)
+    syntax = Syntax(cfg)
+    docs = number_only(files, syntax)
+    tracer.prefetch([(h, [line_of(text, c.start) for c in cs]) for h, text, cs in docs])
+    plans = []
+    for history, text, cites in docs:
+        d = _Doc.of(history.path, text)
+        p = DocPlan(history.path, text)
+        for c in cites:
+            t = tracer.trace(history, text, c)
+            try:
+                prop = propose(d, t, repo, syntax)
+                if any(q.start < prop.end and prop.start < q.end for q in p.proposals):
+                    raise RefError("shares its inline code with another citation")
+                p.proposals.append(prop)
+            except RefError as e:
+                p.left.append((t, str(e)))
+        plans.append(p)
+    return plans
+
+
+def write(p: DocPlan) -> None:
+    p.path.write_bytes(
+        p.converted().encode("utf-8")
+    )  # bytes: keep the file's own line endings

linecite/affected.py

@@ -0,0 +1,198 @@
+"""After a code change, list the doc lines whose citations point into the changed code.
+
+`sync` keeps the numbers right; whether the prose around them is still true needs a human.
+This narrows the re-read to the citations whose code actually changed.
+"""
+
+from __future__ import annotations
+
+import codecs
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Config
+from .errors import RefError
+from .repo import Repo
+from .scan import LINK_RE, Syntax, display, extract, line_of
+from .spec import format_quote, parse_target, resolve
+
+HUNK_RE = re.compile(r"\+(\d+)(?:,(\d+))?")
+# what a reader sees of a doc line: links reduced to their text, anchors dropped
+ANCHOR_RE = re.compile(r"<!--@.*?-->")
+EXCERPT_CHARS = 120
+
+
+def require_commit(repo: Repo, rev: str) -> None:
+    """Fail with the fix when REV (or an end of A..B / A...B) is missing — in CI, usually a shallow clone."""
+    for end in filter(None, re.split(r"\.\.\.?", rev, maxsplit=1)):
+        try:
+            repo.git(
+                "rev-parse",
+                "--verify",
+                "--quiet",
+                "--end-of-options",
+                end + "^{commit}",
+            )
+        except RefError:
+            hint = ""
+            if repo.git("rev-parse", "--is-shallow-repository").strip() == "true":
+                name = end.removeprefix(
+                    "origin/"
+                )  # the refspec names the remote's branch
+                hint = (
+                    f"; this is a shallow clone: fetch it (git fetch --depth=1 origin {name})"
+                    " or check out full history (actions/checkout with fetch-depth: 0)"
+                )
+            raise RefError(f"{end!r} is not a commit in {repo.root}{hint}") from None
+
+
+def _diff_path(line: str) -> str | None:
+    """The new-side path of a `+++ ` line; git C-quotes paths with unusual characters."""
+    path = line[4:]
+    if path.startswith('"') and path.endswith('"'):
+        path = codecs.escape_decode(path[1:-1])[0].decode("utf-8", "replace")
+    return path[2:] if path.startswith("b/") else None
+
+
+def changed_lines(repo: Repo, rev: str) -> dict[str, set[int]]:
+    """Working-tree line numbers changed since REV, per file (committed, staged and unstaged edits).
+
+    REV may be a range (A..B, A...B): then git compares commits, not the working tree.
+    """
+    require_commit(repo, rev)
+    out: dict[str, set[int]] = {}
+    current = None
+    for line in repo.git(
+        "-c",
+        "core.quotepath=false",
+        "diff",
+        "-U0",
+        "--no-color",
+        "--relative",
+        rev,
+        "--",
+    ).splitlines():
+        if line.startswith("+++ "):
+            current = _diff_path(line)
+        elif line.startswith("@@") and current:
+            m = HUNK_RE.search(line)
+            start, count = int(m.group(1)), int(m.group(2) or 1)
+            if count == 0:  # pure deletion between line `start` and `start + 1`
+                out.setdefault(current, set()).update((start, start + 1))
+            else:
+                out.setdefault(current, set()).update(range(start, start + count))
+    return out
+
+
+@dataclass
+class Hit:
+    doc: str
+    line: int
+    path: str
+    span: tuple[int, int]
+    touched: list[int]
+    error: str | None = None
+    source: Path | None = None  # the document
+    excerpt: str = ""  # its citing line, as a reader sees it
+
+
+def affected(files: list[Path], repo: Repo, cfg: Config, rev: str) -> list[Hit]:
+    changed = changed_lines(repo, rev)
+    syntax = Syntax(cfg)
+    hits: list[Hit] = []
+    for f in files:
+        text = f.read_bytes().decode("utf-8")
+        cites, _ = extract(text, f, syntax)
+        seen = set()
+        for c in cites:
+            spec = c.spec
+            if (
+                c.kind not in ("anchor", "link", "symref")
+                or c.error
+                or spec.startswith("@")
+            ):
+                continue  # not code, malformed (check reports it), or pinned history that cannot change
+            ln = line_of(text, c.start)
+            where = {"source": f, "excerpt": excerpt(text, c.start)}
+            try:
+                target, rest = parse_target(repo, spec)
+                # the whole enclosing symbol counts: a change next to the quoted line can change its meaning;
+                # without a symbol only the quoted lines count — a whole-file span would flag every change
+                a, b = target.span
+                if "::" not in spec and rest:
+                    _, a, b = resolve(repo, spec)
+            except RefError as e:
+                hits.append(Hit(display(f), ln, "", (0, 0), [], str(e), **where))
+                continue
+            touched = sorted(n for n in changed.get(target.path, ()) if a <= n <= b)
+            key = (ln, target.path, a, b)
+            if touched and key not in seen:
+                seen.add(key)
+                hits.append(Hit(display(f), ln, target.path, (a, b), touched, **where))
+    return hits
+
+
+def excerpt(text: str, pos: int) -> str:
+    """The document line holding POS, as a reader sees it, cut to EXCERPT_CHARS."""
+    start = text.rfind("\n", 0, pos) + 1
+    end = text.find("\n", pos)
+    line = text[start : end if end >= 0 else len(text)]
+    line = " ".join(ANCHOR_RE.sub("", LINK_RE.sub(r"\g<text>", line)).split())
+    return line if len(line) <= EXCERPT_CHARS else line[: EXCERPT_CHARS - 1] + "…"
+
+
+def _lines(ns: list[int] | tuple[int, int]) -> str:
+    a, b = ns[0], ns[-1]
+    return str(a) if a == b else f"{a}-{b}"
+
+
+def _runs(ns: list[int], most: int = 4) -> str:
+    """Sorted line numbers as runs: `7, 11`, `10-12, 20`; more than MOST runs end in a count."""
+    runs: list[list[int]] = []
+    for n in ns:
+        if runs and n == runs[-1][-1] + 1:
+            runs[-1].append(n)
+        else:
+            runs.append([n])
+    shown = ", ".join(_lines(r) for r in runs[:most])
+    return shown if len(runs) <= most else f"{shown}, … ({len(ns)} lines)"
+
+
+def markdown(
+    hits: list[Hit], rev: str, link: Callable[[Hit], str | None] = lambda h: None
+) -> str:
+    """The re-read list as markdown, for a pull request comment or a CI summary.
+
+    LINK gives a URL for a hit's doc line, when there is one to give.
+    """
+    if re.fullmatch(r"[0-9a-f]{40}", rev):
+        rev = rev[:12]
+    if not hits:
+        return f"No doc citation points into code changed since `{rev}`.\n"
+    found = [h for h in hits if not h.error]
+    out = [
+        f"**{len(found)} doc citation(s) point into code changed since `{rev}`.** "
+        "Re-read the sentences around them: `linecite sync` keeps line numbers right, "
+        "not what the prose says about the code."
+    ]
+    by_doc: dict[str, list[Hit]] = {}
+    for h in found:
+        by_doc.setdefault(h.doc, []).append(h)
+    for doc, rows in by_doc.items():
+        out.append(f"\n`{doc}`\n")
+        for h in rows:
+            url = link(h)
+            where = f"[line {h.line}]({url})" if url else f"line {h.line}"
+            out.append(
+                f"- {where}: {format_quote(h.excerpt)}"
+                f" — cites `{h.path}:{_lines(h.span)}`, changed {_runs(h.touched)}"
+            )
+    broken = [h for h in hits if h.error]
+    if broken:
+        out.append(
+            "\nCitations that no longer resolve (`linecite check` reports them):\n"
+        )
+        out += [f"- `{h.doc}:{h.line}`: {format_quote(h.error)}" for h in broken]
+    return "\n".join(out) + "\n"