docs-drift 0.1.0__py3-none-any.whl

docs_drift/collaboration.py

@@ -0,0 +1,282 @@
+"""Reviewable PR comparisons, bounded support history and verified local fix branches."""
+
+import json
+import re
+from pathlib import Path
+from typing import Any, cast
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from docs_drift.analysis import changed_paths
+from docs_drift.config import Config
+from docs_drift.fix.edits import apply_file, unified_patch
+from docs_drift.fix.rules import plan_rule_fixes
+from docs_drift.git_safety import checkout_options
+from docs_drift.history import _run
+from docs_drift.history_cache import CACHE_DISABLED
+from docs_drift.llm.privacy import mask_secrets, redact_result, redact_value
+from docs_drift.models import Evidence, ScanResult
+from docs_drift.ownership import coverage_report
+from docs_drift.report import render
+from docs_drift.review import ReviewBook, review_status
+from docs_drift.scanning import run_scan
+from docs_drift.snapshots import materialize_snapshot, resolve_revision, scan_snapshot
+
+MAX_HISTORY_COMMITS = 50
+
+
+def static_scan(repo: Path, config: Config) -> ScanResult:
+    token = CACHE_DISABLED.set(True)
+    try:
+        return run_scan(repo, config, no_cache=True)
+    finally:
+        CACHE_DISABLED.reset(token)
+
+
+def pr_comparison(repo: Path, config: Config, base: str) -> tuple[ScanResult, ScanResult, dict[str, Any]]:
+    base_sha = resolve_revision(repo, base)
+    before = scan_snapshot(repo, base_sha, config)
+    current = static_scan(repo, config)
+    previous = {f.claim.claim_id: f for f in before.findings}
+    changed = changed_paths(repo, base_sha, "HEAD")
+    selected = []
+    observations = []
+    for finding in current.findings:
+        old = previous.get(finding.claim.claim_id)
+        if not finding.is_drift or (
+            old and (old.verdict, old.suggestion, old.reasons) == (finding.verdict, finding.suggestion, finding.reasons)
+        ):
+            continue
+        if old is None and finding.claim.doc_path not in changed:
+            continue
+        evidence = list(finding.evidence)
+        if old and old.matched_symbol:
+            symbol = old.matched_symbol
+            evidence.append(
+                Evidence(
+                    file=symbol.file,
+                    line=symbol.line,
+                    text=f"Statically supported at base {base_sha}: {symbol.qualified_name}",
+                )
+            )
+        selected.append(finding.model_copy(update={"evidence": evidence}))
+        observations.append(
+            {
+                "claim_id": finding.claim.claim_id,
+                "doc_path": finding.claim.doc_path,
+                "line": finding.claim.line,
+                "before": old.verdict.value if old else "not-present",
+                "after": finding.verdict.value,
+                "supported_at_base": bool(old and old.verdict == "ok"),
+                "divergence_range": {"after": base_sha, "through": current.head_sha},
+                "attributed_commit": finding.introduced_by.sha if finding.introduced_by else None,
+            }
+        )
+    return (
+        current,
+        current.model_copy(update={"findings": selected}),
+        {
+            "schema_version": 1,
+            "base_sha": base_sha,
+            "head_sha": current.head_sha,
+            "changed_paths": changed,
+            "observations": observations,
+            "warnings": [*before.warnings, *current.warnings],
+            "limits": "Only new/changed drift at the current checkout is selected. A base/head range is not an exact "
+            "breaking-commit attribution. Static support is not runtime behavior.",
+        },
+    )
+
+
+def write_pr_report(  # noqa: PLR0913 - report inputs and optional audit context.
+    result: ScanResult,
+    comparison: dict[str, Any],
+    output: Path,
+    reviews: ReviewBook | None = None,
+    *,
+    important: list[str] | None = None,
+    full_result: ScanResult | None = None,
+) -> dict[str, Any]:
+    if output.exists():
+        raise ValueError("Choose a new report directory; previous review artifacts are preserved.")
+    active = review_status(full_result or result, reviews) if reviews else {}
+    coverage = coverage_report(full_result or result, important)
+    owners = {row["path"]: row["owners"] for row in coverage["documents"]}
+    audit = {key: entry.model_dump(mode="json") for key, entry in active.items()}
+    actionable = result.model_copy(
+        update={
+            "findings": [
+                f
+                for f in result.findings
+                if f.claim.claim_id not in active or active[f.claim.claim_id].decision == "stale"
+            ]
+        }
+    )
+    token = CACHE_DISABLED.set(True)
+    try:
+        plan = plan_rule_fixes(actionable)
+    finally:
+        CACHE_DISABLED.reset(token)
+    patch = unified_patch(result.repo_path, plan)
+    if mask_secrets(patch) != patch:
+        patch = ""
+        comparison = {
+            **comparison,
+            "warnings": [
+                *comparison["warnings"],
+                "Patch omitted: masking would change exact source bytes. Review locally.",
+            ],
+        }
+    comparison = redact_value(comparison)
+    coverage = redact_value(coverage)
+    active = {
+        key: entry.model_copy(update={"reason": mask_secrets(entry.reason), "reviewer": mask_secrets(entry.reviewer)})
+        for key, entry in active.items()
+    }
+    audit = {key: entry.model_dump(mode="json") for key, entry in active.items()}
+    payload = {
+        **comparison,
+        "reviews": audit,
+        "coverage": coverage,
+        "fixable_edits": len(plan.edits),
+        "fix_suggestions": plan.suggestions,
+    }
+    payload = cast(dict[str, Any], redact_value(payload))
+    output.mkdir(parents=True)
+    for format, name in [("json", "pr.json"), ("markdown", "pr.md"), ("github", "annotations.txt")]:
+        (output / name).write_text(render(actionable, format), encoding="utf-8")
+    (output / "review.json").write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    (output / "fix.patch").write_bytes(patch.encode())
+    environment = Environment(loader=FileSystemLoader(Path(__file__).parent / "report"), autoescape=select_autoescape())
+    (output / "pr.html").write_text(
+        environment.get_template("workflow.html").render(
+            result=redact_result(result),
+            comparison=comparison,
+            reviews=active,
+            owners=owners,
+            coverage=coverage,
+            fixable=len(plan.edits),
+        ),
+        encoding="utf-8",
+    )
+    return payload
+
+
+def support_history(repo: Path, config: Config, claim_id: str, max_commits: int = 20) -> dict[str, Any]:
+    if not 1 <= max_commits <= MAX_HISTORY_COMMITS:
+        raise ValueError("History scans must be bounded to 1-50 commits.")
+    history = _run(repo, ["rev-list", "--first-parent", f"--max-count={max_commits}", "HEAD"])
+    if not history:
+        raise ValueError("Cannot traverse history; fetch the relevant commits first.")
+    observations = []
+    last_supported = first_drift = None
+    newer = None
+    for sha in history.stdout.splitlines():
+        scan = scan_snapshot(repo, sha, config)
+        finding = next((f for f in scan.findings if f.claim.claim_id == claim_id), None)
+        if finding is None or finding.verdict == "unverifiable":
+            observations.append({"sha": sha, "verdict": "absent-or-unverifiable"})
+            break
+        observations.append({"sha": sha, "verdict": finding.verdict.value})
+        if finding.verdict == "ok":
+            last_supported, first_drift = sha, newer
+            break
+        newer = sha
+    return {
+        "schema_version": 1,
+        "claim_id": claim_id,
+        "last_statically_supported": last_supported,
+        "first_observed_drift": first_drift,
+        "observations": observations,
+        "max_commits": max_commits,
+        "limits": "First-parent, bounded static scans. Missing claims or unavailable coverage stop attribution; "
+        "null means unknown. No runtime or complete-history claim.",
+    }
+
+
+def fix_branch(  # noqa: PLR0912, PLR0915 - explicit fail-closed proposal stages.
+    repo: Path, config: Config, claim_id: str, branch: str, destination: Path
+) -> dict[str, Any]:
+    status = _run(repo, [*checkout_options(repo), "status", "--porcelain"])
+    if status is None:
+        raise ValueError("Cannot determine source checkout status; Git inspection failed.")
+    if status.stdout.strip():
+        raise ValueError("A clean source checkout is required; preserve or commit your current work first.")
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._/-]{0,120}", branch) or ".." in branch:
+        raise ValueError("Use a valid local branch name without options or '..'.")
+    if destination.exists() or destination.resolve().is_relative_to(repo.resolve()):
+        raise ValueError("Use a new worktree directory outside the source checkout.")
+    result = static_scan(repo, config)
+    selected = [f for f in result.findings if f.claim.claim_id == claim_id and f.is_drift]
+    if not selected:
+        raise ValueError("Finding is absent or no longer drift; scan again.")
+    token = CACHE_DISABLED.set(True)
+    try:
+        plan = plan_rule_fixes(result.model_copy(update={"findings": selected}))
+    finally:
+        CACHE_DISABLED.reset(token)
+    if not plan.edits:
+        raise ValueError("No certain rule edit is available; review suggestions manually. No branch was created.")
+    created = _run(repo, ["worktree", "add", "--no-checkout", "-b", branch, str(destination.resolve()), "HEAD"])
+    if created is None:
+        raise ValueError("Cannot create the isolated fix worktree; check branch/destination availability.")
+    materialize_snapshot(repo, "HEAD", destination)
+    if _run(destination, ["read-tree", "HEAD"]) is None:
+        raise ValueError("Cannot initialize proposal index; nothing was pushed.")
+    fresh = static_scan(destination, config)
+    token = CACHE_DISABLED.set(True)
+    try:
+        plan = plan_rule_fixes(
+            fresh.model_copy(
+                update={"findings": [f for f in fresh.findings if f.claim.claim_id == claim_id and f.is_drift]}
+            )
+        )
+    finally:
+        CACHE_DISABLED.reset(token)
+    if not plan.edits:
+        raise ValueError("Proposal snapshot has no certain edit; inspect the worktree. Nothing was pushed.")
+    for name in sorted({edit.file for edit in plan.edits}):
+        apply_file(destination, plan, name)
+    after = static_scan(destination, config)
+    for edit in plan.edits:
+        candidates = [f for f in after.findings if f.claim.doc_path == edit.file and f.claim.line == edit.line]
+        if not candidates or any(f.verdict != "ok" for f in candidates):
+            raise ValueError(
+                f"Verification failed; inspect the uncommitted worktree at {destination}. Nothing was pushed."
+            )
+    files = sorted({edit.file for edit in plan.edits})
+    for name in files:
+        blob = _run(destination, ["hash-object", "-w", "--no-filters", "--", name])
+        mode = _run(destination, ["ls-files", "--stage", "--", name])
+        if blob is None or mode is None or not mode.stdout.strip():
+            raise ValueError("Cannot stage the local proposal; nothing was pushed.")
+        staged = _run(destination, ["update-index", "--cacheinfo", mode.stdout.split()[0], blob.stdout.strip(), name])
+        if staged is None:
+            raise ValueError("Cannot stage the local proposal; nothing was pushed.")
+    committed = _run(
+        destination,
+        [
+            *checkout_options(destination),
+            "-c",
+            "user.name=docs-drift",
+            "-c",
+            "user.email=docs-drift@localhost",
+            "-c",
+            "commit.gpgsign=false",
+            "commit",
+            "-m",
+            f"Review documentation fix {claim_id[:16]}",
+        ],
+    )
+    if committed is None:
+        raise ValueError(f"Cannot save the local proposal; inspect {destination}. Nothing was pushed.")
+    return {
+        "schema_version": 1,
+        "branch": branch,
+        "worktree": str(destination.resolve()),
+        "commit": resolve_revision(destination, "HEAD"),
+        "files": files,
+        "verified": True,
+        "pushed": False,
+        "approval": "Human review required; this tool-authored local proposal was not merged.",
+    }

docs_drift/config.py

@@ -0,0 +1,113 @@
+"""Validated configuration loaded exclusively from TOML text."""
+
+import tomllib
+import warnings
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+from docs_drift.safe_files import metadata_text
+
+
+class ConfigWarning(UserWarning):
+    """An unrecognized configuration key was ignored."""
+
+
+class ConfigError(ValueError):
+    """A selected configuration source could not be loaded."""
+
+
+class ConfigModel(BaseModel):
+    """Ignore unknown keys after making them visible to the user."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    @model_validator(mode="before")
+    @classmethod
+    def warn_unknown_keys(cls, data: object) -> object:
+        if isinstance(data, dict):
+            for key in data:
+                if key not in cls.model_fields:
+                    warnings.warn(
+                        f"Unknown configuration key '{cls.__name__}.{key}'; ignored. Check the spelling or remove it.",
+                        ConfigWarning,
+                        stacklevel=2,
+                    )
+        return data
+
+
+class LLMConfig(ConfigModel):
+    """Optional prose assessment settings."""
+
+    enabled: bool = False
+    model: str | None = None
+    max_claims: int = Field(default=40, ge=0, le=1000)
+    concurrency: int = Field(default=4, ge=1, le=16)
+    timeout: float = Field(default=60, gt=0, le=600)
+    budget: float = Field(default=0.50, ge=0, allow_inf_nan=False)
+    redact_paths: list[str] = Field(default_factory=list)
+
+
+class HistoryConfig(ConfigModel):
+    """Limits for static git history inspection."""
+
+    max_commits: int = Field(default=2000, ge=0)
+    show_emails: bool = False
+
+
+class Config(ConfigModel):
+    """Schema shared by .docs-drift.toml and [tool.docs-drift]."""
+
+    docs: list[str] = Field(default_factory=lambda: ["README.md", "docs/**/*.md", "*.md"])
+    # Changelogs describe the past on purpose, so old claims there are not drift.
+    exclude: list[str] = Field(
+        default_factory=lambda: [
+            "node_modules/**",
+            ".venv/**",
+            "vendor/**",
+            "CHANGELOG.md",
+            "**/CHANGELOG.md",
+        ]
+    )
+    languages: Literal["auto"] | list[str] = "auto"
+    ignore: list[str] = Field(default_factory=list)
+    min_confidence: float = Field(default=0.6, ge=0.0, le=1.0)
+    llm: LLMConfig = Field(default_factory=LLMConfig)
+    history: HistoryConfig = Field(default_factory=HistoryConfig)
+
+
+def _read_toml(path: Path) -> dict[str, object]:
+    try:
+        return tomllib.loads(metadata_text(path))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"Cannot read configuration at {path}: {exc}. Fix the file or path.") from exc
+
+
+def load_config(repo: Path | None = None, config_path: Path | None = None) -> Config:
+    """Select one source by precedence; omitted fields use schema defaults.
+
+    Explicit paths are relative to the process working directory. Implicit
+    .docs-drift.toml and pyproject.toml paths are relative to the selected repo.
+    A broken selected source is an error, never a reason to silently fall back.
+    """
+    root = Path.cwd() if repo is None else repo
+    source: Path | None = None
+    data: object = {}
+    if config_path is not None:
+        source = config_path
+        data = _read_toml(source)
+    elif (root / ".docs-drift.toml").exists():
+        source = root / ".docs-drift.toml"
+        data = _read_toml(source)
+    elif (root / "pyproject.toml").exists():
+        source = root / "pyproject.toml"
+        project = _read_toml(source)
+        tool = project.get("tool", {})
+        if not isinstance(tool, dict):
+            raise ConfigError(f"Invalid configuration in {source}: make [tool] a TOML table.")
+        data = tool.get("docs-drift", {})
+    try:
+        return Config.model_validate(data)
+    except ValidationError as exc:
+        raise ConfigError(f"Invalid configuration in {source}: {exc}. Correct the listed fields.") from exc

docs_drift/docs/__init__.py

@@ -0,0 +1 @@
+"""Read documentation as text and retain its original source locations."""

docs_drift/docs/defaults.py

@@ -0,0 +1,250 @@
+"""Normalize and link explicit default claims to nearby documented settings."""
+
+import re
+from collections import Counter
+from dataclasses import dataclass
+
+from docs_drift.docs.sections import ParsedDoc, is_historical_span
+from docs_drift.ids import make_claim_id
+from docs_drift.models import Claim, ClaimKind, Extraction
+
+_DURATION = re.compile(r"^(?P<number>\d+(?:\.\d+)?)\s*(?P<unit>s|sec(?:ond)?s?|m|min(?:ute)?s?|h|hours?)$", re.I)
+_SIZE = re.compile(r"^(?P<number>\d+(?:\.\d+)?)\s*(?P<unit>MiB|MB|KiB|KB|GiB|GB|B)$", re.I)
+_NUMBER = re.compile(r"^[-+]?\d+(?:\.\d+)?$")
+_DEFAULT_PHRASE = re.compile(
+    r"\bdefaults?\s+to\s+(?P<value>`[^`]+`|[^,;.)]+)|"
+    r"\bdefault\s*(?::|is)\s*(?P<colon>`[^`]+`|[^,;.)]+)|"
+    r"\([^()]*?\bdefault\s*:?\s*(?P<paren>`[^`]+`|[^()]+)\)|"
+    r"\bif\s+unset,?\s+uses?\s+(?P<unset>`[^`]+`|[^,;.)]+)",
+    re.I,
+)
+_HELP_DEFAULT = re.compile(r"\[\s*default\s*:\s*(?P<value>[^\]]+)\]", re.I)
+_LOG_LEVELS = {"trace", "debug", "info", "warn", "warning", "error", "fatal", "critical"}
+MAX_DEFAULT_LINK_DISTANCE = 2
+
+
+@dataclass(frozen=True)
+class NormalizedValue:
+    """Typed comparison form; ``None`` from equals means the units are insufficient."""
+
+    kind: str
+    value: str
+    unit: str | None
+    raw: str
+
+    def equals(self, other: "NormalizedValue") -> bool | None:
+        if self.kind == "unknown" or other.kind == "unknown":
+            return None
+        if self.kind != other.kind:
+            if {self.kind, other.kind} <= {"number", "duration", "size"}:
+                return None
+            return False
+        if self.kind in {"duration", "size"} and (self.unit is None or other.unit is None):
+            return None
+        return self.value == other.value and self.unit == other.unit
+
+
+def normalize_value(raw: str, *, subject: str = "") -> NormalizedValue:  # noqa: PLR0911
+    """Convert only unambiguous literal forms; keep unknown text comparable as text."""
+    text = raw.strip()
+    if len(text) >= 2 and text[0] == text[-1] and text[0] in {'"', "'", "`"}:  # noqa: PLR2004
+        text = text[1:-1].strip()
+    folded = text.casefold()
+    if folded in {"none", "null", "unset", "empty", '""', "''"} or text == "":
+        return NormalizedValue("none", "", None, raw)
+    boolean = {
+        "true": "true",
+        "yes": "true",
+        "on": "true",
+        "enabled": "true",
+        "1": "true",
+        "false": "false",
+        "no": "false",
+        "off": "false",
+        "disabled": "false",
+        "0": "false",
+    }
+    if folded in boolean and (
+        folded not in {"0", "1"}
+        or re.search(r"(?:debug|enabled|active|secure|verbose|disabled|feature|flag|bool)", subject, re.I)
+    ):
+        return NormalizedValue("boolean", boolean[folded], None, raw)
+    duration = _DURATION.fullmatch(text)
+    if duration:
+        number = float(duration.group("number"))
+        unit = duration.group("unit").casefold()
+        multiplier = 1 if unit.startswith("s") else 60 if unit.startswith("m") else 3600
+        return NormalizedValue("duration", _number_text(number * multiplier), "s", raw)
+    size = _SIZE.fullmatch(text)
+    if size:
+        unit = size.group("unit")
+        factors = {"b": 1, "kb": 1000, "mb": 1000**2, "gb": 1000**3, "kib": 1024, "mib": 1024**2, "gib": 1024**3}
+        return NormalizedValue("size", _number_text(float(size.group("number")) * factors[unit.casefold()]), "B", raw)
+    if _NUMBER.fullmatch(text):
+        number = float(text)
+        if number in {0.0, 1.0} and folded in {"0", "0.0", "1", "1.0"}:
+            return NormalizedValue("boolean", "true" if number == 1 else "false", None, raw)
+        return NormalizedValue("number", _number_text(number), None, raw)
+    # Path normalization is limited to path-like strings; it does not resolve or touch disk.
+    if text.startswith(("~/", "/", "./", "../")) or "/" in text or "\\" in text:
+        path = re.sub(r"/{2,}", "/", text).rstrip("/")
+        return NormalizedValue("path", path, None, raw)
+    string = (
+        text.casefold()
+        if (subject and subject.casefold().endswith(("log_level", "loglevel"))) or folded in _LOG_LEVELS
+        else text
+    )
+    return NormalizedValue("string", string, None, raw)
+
+
+def _number_text(number: float) -> str:
+    return str(int(number)) if number.is_integer() else format(number, ".12g")
+
+
+@dataclass(frozen=True)
+class DefaultsResult:
+    claims: list[Claim]
+    debug_notes: list[str]
+
+
+def _default_claim(  # noqa: PLR0913, PLR0917
+    parsed: ParsedDoc,
+    subject: Claim,
+    raw_value: str,
+    raw_text: str,
+    line: int,
+    column: int,
+    extraction: Extraction,
+    occurrence: int,
+) -> Claim:
+    normalized = normalize_value(raw_value, subject=subject.value)
+    section = parsed.line_to_section[line]
+    return Claim(
+        claim_id=make_claim_id(
+            parsed.doc.path,
+            section.heading_path,
+            ClaimKind.default_value,
+            f"{subject.kind.value}:{subject.value}:{normalized.kind}:{normalized.value}:{normalized.unit}",
+            occurrence,
+        ),
+        kind=ClaimKind.default_value,
+        raw_text=raw_text.strip() or raw_value,
+        value=subject.value,
+        qualifier=subject.kind.value,
+        expected_default=_display_value(normalized),
+        doc_path=parsed.doc.path,
+        line=line,
+        column=column,
+        section_id=section.section_id,
+        extraction=extraction,
+        extraction_confidence=0.8 if extraction == Extraction.table else 0.55,
+    )
+
+
+def _display_value(value: NormalizedValue) -> str:
+    if value.kind == "duration":
+        return f"{value.value}s"
+    if value.kind == "size":
+        return f"{value.value}B"
+    if value.kind == "none":
+        return "none"
+    return value.value
+
+
+def extract_defaults(parsed: ParsedDoc, claims: list[Claim]) -> DefaultsResult:  # noqa: PLR0912, PLR0915
+    """Link prose, table, and help defaults only to a unique nearby subject."""
+    subjects = [
+        claim for claim in claims if claim.kind in {ClaimKind.cli_flag, ClaimKind.env_var, ClaimKind.config_key}
+    ]
+    found: list[tuple[Claim, str, str, int, int, Extraction]] = []
+    notes: list[str] = []
+    for subject in subjects:
+        if subject.expected_default is not None:
+            found.append(
+                (subject, subject.expected_default, subject.raw_text, subject.line, subject.column, subject.extraction)
+            )
+    lines = parsed.lines
+    for line_number, line in enumerate(lines, 1):
+        section = parsed.line_to_section.get(line_number)
+        if section is None or is_historical_span(section, line_number):
+            continue
+        same_section = [item for item in subjects if item.section_id == section.section_id]
+        for match in _DEFAULT_PHRASE.finditer(line):
+            raw_value = (
+                next((part for part in match.groupdict().values() if part), "").strip().strip("`\"'").rstrip("].")
+            )
+            sentence = next(
+                (
+                    item
+                    for item in re.finditer(r"[^.!?]+(?:[.!?](?=\s|$)|$)", line)
+                    if item.start() <= match.start() <= item.end()
+                ),
+                None,
+            )
+            start = sentence.start() if sentence else 0
+            end = sentence.end() if sentence else len(line)
+            nearby = [item for item in same_section if item.line == line_number and start <= item.column - 1 <= end]
+            # Fixture and prose docs often introduce a setting in one bullet and state its default in the next.
+            # Cross-line linking is allowed only for a unique subject within two lines, keeping ambiguity quiet.
+            if not nearby:
+                nearby = [item for item in same_section if abs(item.line - line_number) <= MAX_DEFAULT_LINK_DISTANCE]
+                if len(nearby) > 1:
+                    notes.append(f"{parsed.doc.path}:{line_number}: multiple nearby default subjects; skipped")
+                    continue
+            if not raw_value:
+                continue
+            if not nearby:
+                continue
+            distances = sorted(
+                ((abs(item.column - 1 - match.start()), item) for item in nearby), key=lambda pair: pair[0]
+            )
+            if len(distances) > 1 and distances[0][0] == distances[1][0]:
+                notes.append(f"{parsed.doc.path}:{line_number}: equally near default subjects; skipped")
+                continue
+            subject = distances[0][1]
+            found.append((subject, raw_value, match.group(), line_number, match.start() + 1, Extraction.prose_pattern))
+        # A port number has no safe subject unless the section documents exactly one port-like name.
+        if not line.lstrip().startswith("|") and re.search(
+            r"\b(?:listens?\s+on\s+port|localhost|127\.0\.0\.1):?\s*\d+", line, re.I
+        ):
+            port_match = re.search(r"(?:port\s+|localhost:|127\.0\.0\.1:)(\d{2,5})", line, re.I)
+            port_subjects = [
+                item for item in same_section if "port" in item.value.casefold() or item.value.upper().endswith("_PORT")
+            ]
+            if port_match and len(port_subjects) == 1:
+                found.append(
+                    (
+                        port_subjects[0],
+                        port_match.group(1),
+                        port_match.group(),
+                        line_number,
+                        port_match.start() + 1,
+                        Extraction.prose_pattern,
+                    )
+                )
+            elif port_match and len(port_subjects) > 1:
+                notes.append(f"{parsed.doc.path}:{line_number}: multiple port subjects; default skipped")
+        for match in _HELP_DEFAULT.finditer(line):
+            raw_value = match.group("value").strip().strip("`\"'")
+            flags = [item for item in same_section if item.kind == ClaimKind.cli_flag and item.line == line_number]
+            flag_match = re.search(r"--?[A-Za-z][\w-]*", line)
+            if flags and flag_match and raw_value:
+                subject = next((item for item in flags if item.value == flag_match.group()), flags[0])
+                found.append((subject, raw_value, match.group(), line_number, match.start() + 1, Extraction.code_block))
+    counts: Counter[tuple[str, str, str]] = Counter()
+    result = []
+    unique: set[tuple[str, str, str, str]] = set()
+    for subject, raw_value, raw_text, claim_line, column, extraction in found:
+        section = parsed.line_to_section.get(claim_line)
+        if section is None or is_historical_span(section, claim_line):
+            continue
+        normalized = normalize_value(raw_value, subject=subject.value)
+        identity = (subject.section_id, subject.kind.value, subject.value, _display_value(normalized))
+        if identity in unique:
+            continue
+        unique.add(identity)
+        key = (subject.section_id, subject.kind.value, subject.value)
+        occurrence = counts[key]
+        counts[key] += 1
+        result.append(_default_claim(parsed, subject, raw_value, raw_text, claim_line, column, extraction, occurrence))
+    return DefaultsResult(result, notes)