darnlink 0.6.0__py3-none-any.whl

darnlink/__init__.py

@@ -0,0 +1,11 @@
+"""darnlink — auto-healing Markdown links.
+
+Anchor Markdown links to a UUID so they survive file moves:
+- repair: rewrite a robust link's path to wherever its UUID now lives.
+- robustify: upgrade a plain link to a robust one.
+
+Plain Markdown, no database, no editor lock-in. Dry-run by default.
+See the project Constitution in .specify/memory/constitution.md.
+"""
+
+__version__ = "0.5.0"

darnlink/cli.py

@@ -0,0 +1,262 @@
+"""darnlink CLI. Default is a read-only report; `--write` applies.
+
+    darnlink [PATH]                              # dry-run: what repair would do
+    darnlink [PATH] --write                      # apply path repairs
+    darnlink [PATH] --robustify [--write] [--create-frontmatter]
+    darnlink [PATH] --robustify --create-frontmatter --no-create-frontmatter-for content.md
+    darnlink [PATH] --exclude external_repos --json
+    darnlink check [PATH]                        # report-only gate: BOTH checks, exit 0/2/3 (1 on usage)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from .frontmatter_index import DEFAULT_EXCLUDES, build_index
+from .repair import apply_repairs, plan_repairs
+from .report import Finding, Kind
+from .robustify import apply_robustify, plan_robustify
+
+
+def _findings_json(
+    findings: List[Finding],
+    wrote: int,
+    write: bool,
+    ignored: Optional[List[Path]] = None,
+    invalid: Optional[List[Path]] = None,
+    link_ignored: Optional[List[Path]] = None,
+) -> str:
+    return json.dumps(
+        {
+            "wrote": wrote,
+            "applied": write,
+            "ignored_files": [str(p) for p in (ignored or [])],
+            # feature 006: opted out as a SOURCE only — still indexed as a target
+            "link_ignored_files": [str(p) for p in (link_ignored or [])],
+            "invalid_frontmatter_files": [str(p) for p in (invalid or [])],
+            "findings": [{"kind": f.kind.value, "file": str(f.file), "detail": f.detail} for f in findings],
+        },
+        indent=2,
+    )
+
+
+def _run_repair(root: Path, write: bool, excludes: set, as_json: bool, block_markers: tuple) -> int:
+    index = build_index(root, excludes)
+    result = plan_repairs(root, index, excludes, block_markers)
+    repairs = [f for f in result.findings if f.kind is Kind.REPAIR]
+    conflicts = [f for f in result.findings if f.kind is Kind.CONFLICT]
+    unresolved = [f for f in result.findings if f.kind in (Kind.UNRESOLVABLE, Kind.AMBIGUOUS)]
+    wrote = len(apply_repairs(result)) if write else 0
+
+    if as_json:
+        print(_findings_json(result.findings, wrote, write, result.ignored, index.invalid,
+                             result.link_ignored))
+    else:
+        print(f"darnlink repair — root: {root}")
+        print(f"  indexed uuids: {len(index.by_uuid)} | duplicate uuids: {len(index.duplicates)}")
+        print(f"  links to repair: {len(repairs)} | conflicts: {len(conflicts)} | unresolved: {len(unresolved)} | ignored files: {len(result.ignored)} | link-ignored: {len(result.link_ignored)} | invalid frontmatter: {len(index.invalid)}")
+        for f in repairs:
+            print(f"  [repair] {f.file}: {f.detail}")
+        for f in conflicts:
+            print(f"  [conflict] {f.file}: {f.detail}")
+        for f in unresolved:
+            print(f"  [{f.kind.value}] {f.file}: {f.detail}")
+        for f in [x for x in result.findings if x.kind is Kind.IGNORED_LINKS]:
+            print(f"  [link-ignored] {f.file}: {f.detail}")
+        for p in index.invalid:
+            print(f"  [invalid-frontmatter] {p}: not valid YAML; not indexed (fix the file)")
+        if write:
+            print(f"  WROTE {wrote} file(s).")
+        elif repairs:
+            print("  (dry-run — nothing written. Re-run with --write to apply.)")
+
+    return 1 if conflicts or unresolved or index.invalid or (repairs and not write) else 0
+
+
+def _run_robustify(root: Path, write: bool, create_frontmatter: bool, excludes: set, as_json: bool, block_markers: tuple, no_create_globs: tuple) -> int:
+    result = plan_robustify(root, create_frontmatter=create_frontmatter, excludes=excludes, block_markers=block_markers, no_create_globs=no_create_globs)
+    upgrades = [f for f in result.findings if f.kind is Kind.ROBUSTIFY]
+    skipped = [f for f in result.findings if f.kind is Kind.NO_FRONTMATTER]
+    denied = [f for f in result.findings if f.kind is Kind.DENY_LISTED]
+    wrote = len(apply_robustify(result)) if write else 0
+
+    if as_json:
+        print(_findings_json(result.findings, wrote, write, result.ignored, result.invalid,
+                             result.link_ignored))
+    else:
+        print(f"darnlink robustify — root: {root}")
+        print(f"  plain links to robustify: {len(upgrades)} | skipped (no frontmatter): {len(skipped)} | deny-listed: {len(denied)} | ignored files: {len(result.ignored)} | link-ignored: {len(result.link_ignored)} | invalid frontmatter: {len(result.invalid)}")
+        for f in upgrades:
+            print(f"  [robustify] {f.file}: {f.detail}")
+        for f in skipped:
+            print(f"  [no-frontmatter] {f.file}: {f.detail} (use --create-frontmatter to allow)")
+        for f in denied:
+            print(f"  [deny-listed] {f.file}: {f.detail}")
+        for f in [x for x in result.findings if x.kind is Kind.IGNORED_LINKS]:
+            print(f"  [link-ignored] {f.file}: {f.detail}")
+        for p in result.invalid:
+            print(f"  [invalid-frontmatter] {p}: not valid YAML; left untouched (fix the file)")
+        if write:
+            print(f"  WROTE {wrote} file(s).")
+        elif upgrades:
+            print("  (dry-run — nothing written. Re-run with --write to apply.)")
+
+    return 1 if result.invalid or (upgrades and not write) else 0
+
+
+def _run_check(root: Path, excludes: set, as_json: bool, block_markers: tuple) -> int:
+    """Feature 007: report-only gate. Run BOTH checks (integrity + strict) in one invocation and
+    return a distinguishable exit code. Never writes. `--robustify` alone does not catch a broken
+    robust link, and plain `darnlink .` does not catch an un-anchored plain link — a gate that runs
+    only one is blind to the other; `check` runs both so a consumer cannot forget a half.
+
+    Exit: 0 clean · 2 integrity failure (broken/unresolvable robust links or invalid frontmatter) ·
+    3 strict-only failure (anchorable plain links un-anchored). Integrity takes precedence over
+    strict when both fail (a broken link is more urgent than an un-anchored one).
+    """
+    # Integrity axis (repair, dry-run): robust links whose path is stale/unresolvable, plus invalid YAML.
+    index = build_index(root, excludes)
+    rep = plan_repairs(root, index, excludes, block_markers)
+    repairs = [f for f in rep.findings if f.kind is Kind.REPAIR]
+    conflicts = [f for f in rep.findings if f.kind is Kind.CONFLICT]
+    unresolved = [f for f in rep.findings if f.kind in (Kind.UNRESOLVABLE, Kind.AMBIGUOUS)]
+    integrity_fail = bool(repairs or conflicts or unresolved or index.invalid)
+
+    # Strict axis (robustify, dry-run): plain links to an anchorable target left un-anchored.
+    rob = plan_robustify(root, create_frontmatter=False, excludes=excludes, block_markers=block_markers)
+    upgrades = [f for f in rob.findings if f.kind is Kind.ROBUSTIFY]
+    strict_fail = bool(upgrades or rob.invalid)
+
+    code = 2 if integrity_fail else (3 if strict_fail else 0)
+
+    if as_json:
+        print(json.dumps({
+            "check": True,
+            "exit_code": code,
+            "integrity": {
+                "failed": integrity_fail,
+                "repairs": len(repairs), "conflicts": len(conflicts),
+                "unresolved": len(unresolved), "invalid_frontmatter": len(index.invalid),
+                "invalid_frontmatter_files": [str(p) for p in index.invalid],
+                "findings": [{"kind": f.kind.value, "file": str(f.file), "detail": f.detail}
+                             for f in (repairs + conflicts + unresolved)]
+                + [{"kind": Kind.INVALID_FRONTMATTER.value, "file": str(p),
+                    "detail": "frontmatter present but not valid YAML; not indexed"}
+                   for p in index.invalid],
+            },
+            "strict": {
+                "failed": strict_fail,
+                "robustify": len(upgrades), "invalid_frontmatter": len(rob.invalid),
+                "invalid_frontmatter_files": [str(p) for p in rob.invalid],
+                "findings": [{"kind": f.kind.value, "file": str(f.file), "detail": f.detail}
+                             for f in upgrades]
+                + [{"kind": Kind.INVALID_FRONTMATTER.value, "file": str(p),
+                    "detail": "frontmatter present but not valid YAML; left untouched (fix the file)"}
+                   for p in rob.invalid],
+            },
+        }, indent=2))
+    else:
+        outcome = {0: "clean", 2: "integrity failure", 3: "strict failure"}[code]
+        print(f"darnlink check — root: {root}")
+        print(f"  [integrity] repair: {len(repairs)} | conflicts: {len(conflicts)} | "
+              f"unresolved: {len(unresolved)} | invalid frontmatter: {len(index.invalid)} "
+              f"→ {'FAIL' if integrity_fail else 'ok'}")
+        print(f"  [strict]    to robustify: {len(upgrades)} | invalid frontmatter: {len(rob.invalid)} "
+              f"→ {'FAIL' if strict_fail else 'ok'}")
+        for f in repairs + conflicts + unresolved:
+            print(f"  [integrity/{f.kind.value}] {f.file}: {f.detail}")
+        for p in index.invalid:
+            print(f"  [integrity/invalid-frontmatter] {p}: not valid YAML; not indexed (fix the file)")
+        for f in upgrades:
+            print(f"  [strict/robustify] {f.file}: {f.detail}")
+        for p in rob.invalid:
+            print(f"  [strict/invalid-frontmatter] {p}: not valid YAML; left untouched (fix the file)")
+        print(f"  → exit {code} ({outcome})")
+
+    return code
+
+
+class _CheckArgParser(argparse.ArgumentParser):
+    # Exit 1 (usage) on a bad flag/arg, not argparse's default 2 — 2 means "integrity failure" here.
+    def error(self, message: str):  # noqa: D401
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _run_check_cli(argv: List[str]) -> int:
+    """Parse `darnlink check [PATH] [--exclude … --ignore-block … --json]` (report-only: no --write)."""
+    parser = _CheckArgParser(
+        prog="darnlink check",
+        description="report-only gate: run BOTH the repair (integrity) and robustify (strict) checks "
+        "over PATH and exit 0 (clean) / 2 (integrity) / 3 (strict). Never writes.",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="root directory to scan (default: .)")
+    parser.add_argument("--exclude", action="append", default=[], metavar="PATTERN", help="directory-name glob to skip (fnmatch, case-sensitive; a plain name matches exactly) (repeatable)")
+    parser.add_argument("--ignore-block", action="append", default=[], metavar="NAME",
+                        help="ignore links inside <!-- NAME-start --> … <!-- NAME-end --> blocks (repeatable)")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+    root = Path(args.path).resolve()
+    if not root.is_dir():
+        print(f"error: not a directory: {root}", file=sys.stderr)
+        return 1
+    excludes = set(DEFAULT_EXCLUDES) | set(args.exclude)
+    return _run_check(root, excludes, args.json, tuple(args.ignore_block))
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    if raw and raw[0] == "check":  # feature 007: report-only gate subcommand
+        return _run_check_cli(raw[1:])
+
+    parser = argparse.ArgumentParser(
+        prog="darnlink",
+        description="auto-healing Markdown links: repair links whose target moved, "
+        "or robustify plain links (anchored by UUID).",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="root directory to scan (default: .)")
+    parser.add_argument("--write", action="store_true", help="apply changes (default: dry-run report)")
+    parser.add_argument("--robustify", action="store_true", help="upgrade plain links to robust (default op: repair)")
+    parser.add_argument("--create-frontmatter", action="store_true", help="(robustify) allow creating frontmatter where missing")
+    parser.add_argument(
+        "--no-create-frontmatter-for",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="(robustify) basename glob whose targets are never given a uuid — no frontmatter block "
+        "created and no uuid line inserted into existing frontmatter — regardless of "
+        "--create-frontmatter (repeatable; e.g. --no-create-frontmatter-for content.md). For files a "
+        "pipeline regenerates. Reusing a uuid the target already has is unaffected.",
+    )
+    parser.add_argument("--exclude", action="append", default=[], metavar="PATTERN", help="directory-name glob to skip (fnmatch, case-sensitive; a plain name matches exactly) (repeatable)")
+    parser.add_argument(
+        "--ignore-block",
+        action="append",
+        default=[],
+        metavar="NAME",
+        help="ignore links inside generated blocks <!-- NAME-start --> ... <!-- NAME-end --> "
+        "(repeatable; e.g. --ignore-block autogrid)",
+    )
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+
+    root = Path(args.path).resolve()
+    if not root.is_dir():
+        print(f"error: not a directory: {root}", file=sys.stderr)
+        return 2
+
+    excludes = set(DEFAULT_EXCLUDES) | set(args.exclude)
+    block_markers = tuple(args.ignore_block)
+    if args.robustify:
+        return _run_robustify(
+            root, args.write, args.create_frontmatter, excludes, args.json, block_markers,
+            tuple(args.no_create_frontmatter_for),
+        )
+    return _run_repair(root, args.write, excludes, args.json, block_markers)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

darnlink/frontmatter_edit.py

@@ -0,0 +1,75 @@
+"""Surgical frontmatter edits: read/insert a `uuid` without reformatting the rest of the file.
+
+We deliberately avoid re-dumping YAML (which would reorder keys and create noisy diffs and risks
+the truncation bug seen in the predecessor). Instead we textually insert a `uuid:` line.
+"""
+from __future__ import annotations
+
+import re
+import uuid as _uuid
+from typing import Optional, Tuple
+
+# A leading YAML frontmatter block: ---\n <body> \n---\n <rest>
+_FM_BLOCK_RE = re.compile(r"\A(---\s*\n)(.*?\n?)(---\s*\n)(.*)\Z", re.DOTALL)
+_UUID_LINE_RE = re.compile(r"^uuid:\s*(.+)$", re.MULTILINE)
+
+
+def new_uuid() -> str:
+    return str(_uuid.uuid4())
+
+
+def detect_newline(content: str) -> str:
+    r"""The file's dominant line ending: '\r\n' if any CRLF is present, else '\n'."""
+    return "\r\n" if "\r\n" in content else "\n"
+
+
+def read_text_keep_newlines(path) -> str:
+    """Read text WITHOUT universal-newline translation, so CRLF/LF are preserved verbatim.
+
+    Uses utf-8-sig so a leading UTF-8 BOM (common on Windows-authored files) is stripped on read —
+    otherwise it would sit before the `---` and break frontmatter detection. Files with no BOM are
+    read identically to plain utf-8.
+    """
+    with open(path, encoding="utf-8-sig", newline="") as f:
+        return f.read()
+
+
+def write_text_keep_newlines(path, content: str) -> None:
+    r"""Write text verbatim — do NOT translate '\n' to the platform's os.linesep."""
+    with open(path, "w", encoding="utf-8", newline="") as f:
+        f.write(content)
+
+
+def read_uuid_from_content(content: str) -> Optional[str]:
+    """Return the lowercased `uuid` from a leading frontmatter block, or None."""
+    m = _FM_BLOCK_RE.match(content)
+    if not m:
+        return None
+    um = _UUID_LINE_RE.search(m.group(2))
+    if not um:
+        return None
+    return um.group(1).strip().strip("'\"").lower() or None
+
+
+def has_frontmatter(content: str) -> bool:
+    return _FM_BLOCK_RE.match(content) is not None
+
+
+def add_uuid_to_content(
+    content: str, uuid_value: str, create_frontmatter: bool
+) -> Optional[str]:
+    """Return content with `uuid: <uuid_value>` inserted into the frontmatter.
+
+    - If a frontmatter block exists, insert the line just after the opening `---`.
+    - If none exists, create a minimal block only when `create_frontmatter` is True.
+    - Returns None when there is no frontmatter and creation is not allowed (caller skips).
+    Assumes the file does not already have a uuid (caller checks).
+    """
+    nl = detect_newline(content)
+    m = _FM_BLOCK_RE.match(content)
+    if m:
+        head, body, sep, rest = m.groups()
+        return f"{head}uuid: {uuid_value}{nl}{body}{sep}{rest}"
+    if create_frontmatter:
+        return f"---{nl}uuid: {uuid_value}{nl}---{nl}{nl}{content}"
+    return None

darnlink/frontmatter_index.py

@@ -0,0 +1,108 @@
+"""Build a `uuid -> file` index by scanning Markdown frontmatter.
+
+This plain dictionary replaces the predecessor's heavy entity model
+(`csv_data_manager`/`MarkdownRepoIndex`) — it is the core of the L1 split.
+"""
+from __future__ import annotations
+
+import fnmatch
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterator, List
+
+import frontmatter
+
+DEFAULT_EXCLUDES = {".git", "node_modules", ".venv", "__pycache__", "_build", ".tox", "dist", "build"}
+
+
+def _dir_excluded(name: str, excludes) -> bool:
+    """A directory name is excluded if it matches any pattern by glob (fnmatch, case-sensitive).
+    A pattern with no wildcards matches exactly, so plain names (`node_modules`) still work — the
+    glob is purely additive. Lets a repo exclude a family with one line, e.g. `old`, `old_*`, `*_old`."""
+    return any(fnmatch.fnmatchcase(name, pat) for pat in excludes)
+
+
+@dataclass
+class FrontmatterIndex:
+    by_uuid: Dict[str, Path] = field(default_factory=dict)
+    duplicates: Dict[str, List[Path]] = field(default_factory=dict)
+    invalid: List[Path] = field(default_factory=list)  # files whose frontmatter is not valid YAML
+
+    def get(self, uuid: str) -> Path | None:
+        return self.by_uuid.get(uuid.lower())
+
+    def is_ambiguous(self, uuid: str) -> bool:
+        return uuid.lower() in self.duplicates
+
+
+def iter_markdown_files(root: Path, excludes: set[str] = DEFAULT_EXCLUDES) -> Iterator[Path]:
+    """Yield all `.md` files under `root`, skipping excluded directory names."""
+    root = root.resolve()
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if not _dir_excluded(d, excludes)]
+        for fn in filenames:
+            if fn.lower().endswith(".md"):
+                yield Path(dirpath) / fn
+
+
+def read_frontmatter_uuid(content: str) -> tuple[str, str | None]:
+    """Canonical uuid reader, used by EVERY operation (index, repair, robustify).
+
+    Returns `(status, uuid)`:
+      - `("none", None)`    no leading frontmatter block at all.
+      - `("invalid", None)` a frontmatter block that is NOT valid YAML — reported, never read/written.
+      - `("valid", uuid)`   well-formed YAML; `uuid` is the lowercased value or None if absent.
+
+    Parsing is delegated to `python-frontmatter` (PyYAML) — the standard for the format (FORMAT.md).
+    A tolerant regex MUST NOT be used here: it would accept what YAML rejects (FR-023/FR-024)."""
+    from .frontmatter_edit import has_frontmatter  # regex presence-check; no cycle (links-free module)
+
+    if not has_frontmatter(content):
+        return ("none", None)
+    try:
+        meta = frontmatter.loads(content).metadata
+    except Exception:
+        return ("invalid", None)
+    if not isinstance(meta, dict):
+        return ("invalid", None)
+    u = meta.get("uuid")
+    if u is None:
+        return ("valid", None)
+    if not isinstance(u, str):
+        return ("invalid", None)  # uuid present but not a string scalar (list/dict/number): malformed
+    return ("valid", u.strip().lower() or None)
+
+
+def build_index(root: Path, excludes: set[str] = DEFAULT_EXCLUDES) -> FrontmatterIndex:
+    """Scan `root` and map each frontmatter `uuid` to its file. Records duplicates separately.
+
+    Files carrying the `<!-- darnlink-ignore-file -->` marker are skipped: an opted-out file is not
+    a resolvable target, so a robust link pointing at its uuid is reported unresolvable (FR-019)."""
+    from .links import file_is_ignored  # local import: links has no package deps, but keep it lazy
+
+    index = FrontmatterIndex()
+    for path in iter_markdown_files(root, excludes):
+        try:
+            # utf-8-sig strips a leading UTF-8 BOM (common on Windows-authored files) so it doesn't
+            # sit before the `---` and hide the frontmatter from the index. Same as the write path.
+            content = path.read_text(encoding="utf-8-sig")  # read once: marker + uuid both come from it
+        except Exception:
+            continue
+        if file_is_ignored(content):
+            continue
+        status, u = read_frontmatter_uuid(content)
+        if status == "invalid":
+            index.invalid.append(path)  # report; an invalid file is never a resolvable target (FR-024)
+            continue
+        if not u:
+            continue
+        if u in index.duplicates:
+            index.duplicates[u].append(path)
+        elif u in index.by_uuid:
+            # second sighting: promote to duplicate, drop from the unambiguous map
+            first = index.by_uuid.pop(u)
+            index.duplicates[u] = [first, path]
+        else:
+            index.by_uuid[u] = path
+    return index

darnlink/links.py

@@ -0,0 +1,205 @@
+"""Robust-link grammar: detect, parse and emit.
+
+Grammar (ported from the predecessor `tx_aiready_mdlink`):
+    [text](href) <!-- uuid: <36-char-uuid> -->
+Detection tolerates any whitespace between `)` and the comment; emission uses a single space.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Sequence, Tuple
+
+# A robust link: a Markdown link immediately followed (any whitespace) by a uuid HTML comment.
+ROBUST_LINK_RE = re.compile(
+    r"\[(?P<text>[^\]]+)\]\((?P<href>[^)]+)\)\s*<!--\s*uuid:\s*(?P<uuid>[0-9a-fA-F-]{36})\s*-->"
+)
+# Any inline Markdown link.
+MD_LINK_RE = re.compile(r"\[(?P<text>[^\]]+)\]\((?P<href>[^)]+)\)")
+# A uuid comment that immediately follows a link (used to tell plain from robust).
+# No `^`: it is applied with .match(content, pos), which already anchors at pos.
+_TRAILING_UUID_RE = re.compile(r"\s*<!--\s*uuid:\s*[0-9a-fA-F-]{36}\s*-->")
+
+Span = Tuple[int, int]
+
+
+def ignored_spans(content: str, block_markers: Sequence[str]) -> List[Span]:
+    """Spans of generated blocks to ignore: between `<!-- NAME-start -->` and `<!-- NAME-end -->`.
+
+    Lets darnlink leave machine-generated regions (e.g. a generator's auto-built tables) untouched
+    so it only operates on hand-authored prose links.
+    """
+    spans: List[Span] = []
+    for name in block_markers:
+        pat = re.compile(
+            rf"<!--\s*{re.escape(name)}-start\s*-->.*?<!--\s*{re.escape(name)}-end\s*-->",
+            re.DOTALL,
+        )
+        spans.extend((m.start(), m.end()) for m in pat.finditer(content))
+    return spans
+
+
+def _in_spans(pos: int, spans: Sequence[Span]) -> bool:
+    return any(s <= pos < e for s, e in spans)
+
+
+def _fenced_code_spans(content: str) -> List[Span]:
+    """Spans of fenced code blocks: ```` ``` ````/`~~~` (indent <=3), closed by the same fence char
+    of equal-or-greater length. An info string after the opener is allowed. An unclosed fence
+    extends to EOF (over-ignoring is safe; corrupting code is not -- FR-016)."""
+    spans: List[Span] = []
+    pos = 0
+    fence: Tuple[str, int, int] | None = None  # (char, length, start offset)
+    for line in content.splitlines(keepends=True):
+        stripped = line.lstrip(" ")
+        indent = len(line) - len(stripped)
+        if fence is None:
+            if indent <= 3 and stripped[:3] in ("```", "~~~"):
+                ch = stripped[0]
+                run = len(stripped) - len(stripped.lstrip(ch))
+                if run >= 3:
+                    fence = (ch, run, pos)
+        else:
+            ch, run, start = fence
+            body = stripped.rstrip()
+            # a closing fence is only fence chars, of the same kind, length >= the opener
+            if indent <= 3 and body and set(body) == {ch} and len(body) >= run:
+                spans.append((start, pos + len(line)))
+                fence = None
+        pos += len(line)
+    if fence is not None:
+        spans.append((fence[2], len(content)))  # unclosed -> to EOF
+    return spans
+
+
+def _inline_code_spans(content: str, skip: Sequence[Span]) -> List[Span]:
+    """Spans of inline code: a run of N backticks closed by the next run of exactly N backticks
+    (FR-017). An unterminated run is not code. Positions inside `skip` (fenced blocks) are not
+    scanned, so backticks inside a fence never pair with backticks outside it."""
+    spans: List[Span] = []
+    n = len(content)
+    i = 0
+    while i < n:
+        if content[i] != "`" or _in_spans(i, skip):
+            i += 1
+            continue
+        j = i
+        while j < n and content[j] == "`":
+            j += 1
+        run = j - i
+        # look for a closing run of exactly `run` backticks
+        k = j
+        closed = False
+        while k < n:
+            if _in_spans(k, skip):
+                break  # reached a fenced block; an inline span cannot cross it -> unterminated
+            if content[k] == "`":
+                m = k
+                while m < n and content[m] == "`":
+                    m += 1
+                if m - k == run:
+                    spans.append((i, m))
+                    i = m
+                    closed = True
+                    break
+                k = m
+            else:
+                k += 1
+        if not closed:
+            i = j  # unterminated opener; not a code span
+    return spans
+
+
+def code_spans(content: str) -> List[Span]:
+    """All spans that are code (fenced blocks + inline code). Links starting inside any of these
+    are examples, not navigational links, and must never be rewritten (FR-015). Pure & deterministic."""
+    fenced = _fenced_code_spans(content)
+    return fenced + _inline_code_spans(content, fenced)
+
+
+def _carries_marker(content: str, keyword: str, marker_re: "re.Pattern[str]") -> bool:
+    """True if `marker_re` matches outside a code span (so a file documenting the marker as an
+    example does not opt itself out). Pure & deterministic.
+
+    The `keyword` substring test is a cheap reject: markers are rare, and `code_spans()` parses the
+    whole file, so the common case (no marker at all) must not pay for it. It is safe because every
+    marker regex requires that keyword literally — a file that lacks the substring cannot match."""
+    if keyword not in content:
+        return False
+    code = code_spans(content)
+    return any(not _in_spans(m.start(), code) for m in marker_re.finditer(content))
+
+
+# A whole-file opt-out: a file carrying this marker is removed from the darnlink graph entirely.
+IGNORE_FILE_MARKER = "<!-- darnlink-ignore-file -->"
+_IGNORE_FILE_RE = re.compile(r"<!--\s*darnlink-ignore-file\s*-->")
+
+
+def file_is_ignored(content: str) -> bool:
+    """True if the file opts out of darnlink via a `<!-- darnlink-ignore-file -->` marker that is
+    NOT inside a code span (so a file documenting the marker as an example does not self-ignore).
+    FR-019..FR-021; composes with code_spans (feature 002). Pure & deterministic."""
+    return _carries_marker(content, "darnlink-ignore-file", _IGNORE_FILE_RE)
+
+
+# A SOURCE-only opt-out: darnlink never rewrites the links inside this file, but the file stays a
+# first-class target (its uuid is indexed, so inbound robust links resolve and heal). This is the
+# axis `darnlink-ignore-file` fuses: that one also drops the file as a target (FR-019), which the
+# motivating case — a generated, heavily-linked INDEX.md — cannot afford. Feature 006.
+IGNORE_LINKS_MARKER = "<!-- darnlink-ignore-links -->"
+_IGNORE_LINKS_RE = re.compile(r"<!--\s*darnlink-ignore-links\s*-->")
+
+
+def file_ignores_links(content: str) -> bool:
+    """True if the file opts its OWN links out via a `<!-- darnlink-ignore-links -->` marker that is
+    NOT inside a code span. Says nothing about the target axis: the file keeps its uuid indexed.
+    FR-033/FR-036/FR-037; composes with code_spans (feature 002). Pure & deterministic.
+
+    Note (FR-040): the marker must not precede the frontmatter block — the canonical reader only
+    recognises a *leading* `---`, so a marker on line 1 would hide the file's own uuid and silently
+    cost it the target axis. Detection itself is position-free; the ordering is a property of the
+    frontmatter format, not of this check."""
+    return _carries_marker(content, "darnlink-ignore-links", _IGNORE_LINKS_RE)
+
+
+@dataclass(frozen=True)
+class RobustLink:
+    text: str
+    href: str
+    uuid: str
+    start: int  # span of the whole robust link (link + comment) in the source
+    end: int
+
+
+@dataclass(frozen=True)
+class PlainLink:
+    text: str
+    href: str
+    start: int  # span of just the [text](href) in the source
+    end: int
+
+
+def find_robust_links(content: str, ignore: Sequence[Span] = ()) -> List[RobustLink]:
+    """All robust links in the content, in document order, skipping any inside `ignore` spans."""
+    return [
+        RobustLink(m.group("text"), m.group("href"), m.group("uuid").lower(), m.start(), m.end())
+        for m in ROBUST_LINK_RE.finditer(content)
+        if not _in_spans(m.start(), ignore)
+    ]
+
+
+def find_plain_links(content: str, ignore: Sequence[Span] = ()) -> List[PlainLink]:
+    """All Markdown links that are NOT already robust, skipping any inside `ignore` spans."""
+    out: List[PlainLink] = []
+    for m in MD_LINK_RE.finditer(content):
+        if _TRAILING_UUID_RE.match(content, m.end()):
+            continue  # this link is part of a robust link; skip
+        if _in_spans(m.start(), ignore):
+            continue  # inside a generated block (e.g. autogrid); leave it alone
+        out.append(PlainLink(m.group("text"), m.group("href"), m.start(), m.end()))
+    return out
+
+
+def emit_robust_link(text: str, href: str, uuid: str) -> str:
+    """Canonical robust-link rendering: a single space before the comment."""
+    return f"[{text}]({href}) <!-- uuid: {uuid} -->"