docs-drift 0.1.0__py3-none-any.whl

docs_drift/docs/pipeline.py

@@ -0,0 +1,234 @@
+"""Run the documentation-only extraction pipeline, isolating every input file."""
+
+import fnmatch
+import hashlib
+import os
+import re
+import subprocess
+import time
+import warnings
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from pathlib import Path
+
+from docs_drift.config import Config
+from docs_drift.docs.defaults import extract_defaults
+from docs_drift.docs.discover import DiscoveryWarning, discover_docs, read_doc
+from docs_drift.docs.extract_blocks import extract_block_claims, project_command_names
+from docs_drift.docs.extract_inline import extract_claims
+from docs_drift.docs.sections import ParsedDoc, is_historical_span, parse_document
+from docs_drift.models import Claim, ClaimLocation, ScanResult, SuppressedClaim
+
+MIN_EXTRACTION_CONFIDENCE = 0.3
+
+
+@contextmanager
+def _timed(timings: dict[str, float], stage: str) -> Iterator[None]:
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        timings[stage] = timings.get(stage, 0.0) + time.perf_counter() - start
+
+
+def _head(root: Path) -> str:
+    env = {key: value for key, value in os.environ.items() if not key.upper().startswith("GIT_")}
+    env["GIT_OPTIONAL_LOCKS"] = "0"
+    try:
+        value = subprocess.run(
+            ["git", "-c", "core.fsmonitor=false", "-C", str(root), "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=3,
+            env=env,
+        ).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        value = ""
+    return value if re.fullmatch(r"(?:[0-9a-f]{40}|[0-9a-f]{64})", value) else "0" * 40
+
+
+def snapshot_time(root: Path) -> datetime:
+    """Use the commit timestamp for reproducible snapshots; unversioned input uses the epoch."""
+    try:
+        value = subprocess.run(
+            ["git", "-c", "core.fsmonitor=false", "-C", str(root), "show", "-s", "--format=%ct", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+            check=True,
+        )
+        return datetime.fromtimestamp(int(value.stdout.strip()), UTC)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return datetime(1970, 1, 1, tzinfo=UTC)
+
+
+def _suppression(parsed: ParsedDoc, claim: Claim) -> str | None:  # noqa: PLR0911, PLR0912
+    if "docs-drift-ignore" not in parsed.text:
+        return None
+    lines = parsed.lines
+    if any("docs-drift-ignore-file" in line for line in lines[: min(len(lines), 100)]):
+        return "docs-drift-ignore-file"
+    if claim.line > 1 and "docs-drift-ignore-next-line" in lines[claim.line - 2]:
+        return "docs-drift-ignore-next-line"
+    if claim.line > 1 and "docs-drift-ignore" in lines[claim.line - 2]:
+        return "docs-drift-ignore"
+    # A paragraph/table/fence directive suppresses the following block through its closing boundary.
+    for index, line in enumerate(lines[: claim.line - 1]):
+        if "docs-drift-ignore" not in line or "next-line" in line or "file" in line:
+            continue
+        next_nonblank = next((n for n in range(index + 1, len(lines)) if lines[n].strip()), None)
+        if next_nonblank is None or claim.line - 1 < next_nonblank:
+            continue
+        opening = lines[next_nonblank].lstrip()
+        if opening.startswith("```") or opening.startswith("~~~"):
+            marker = opening[:3]
+            close = next(
+                (n for n in range(next_nonblank + 1, len(lines)) if lines[n].lstrip().startswith(marker)), len(lines)
+            )
+            if next_nonblank <= claim.line - 1 <= close:
+                return "docs-drift-ignore"
+        if opening.startswith("|"):
+            end = next_nonblank
+            while end + 1 < len(lines) and lines[end + 1].strip() and lines[end + 1].lstrip().startswith("|"):
+                end += 1
+            if next_nonblank <= claim.line - 1 <= end:
+                return "docs-drift-ignore"
+        if not opening.startswith(("#", "|")):
+            end = next_nonblank
+            while (
+                end + 1 < len(lines)
+                and lines[end + 1].strip()
+                and not lines[end + 1].lstrip().startswith(("#", "```", "~~~", "|"))
+            ):
+                end += 1
+            if next_nonblank <= claim.line - 1 <= end:
+                return "docs-drift-ignore"
+    return None
+
+
+def _ignored(claim: Claim, patterns: list[str]) -> bool:
+    if claim.claim_id in patterns:
+        return True
+    return any(
+        ":" in pattern
+        and pattern.split(":", 1)[0] == claim.kind.value
+        and fnmatch.fnmatchcase(claim.value, pattern.split(":", 1)[1])
+        for pattern in patterns
+    )
+
+
+def _merge(parsed: ParsedDoc, claims: list[Claim]) -> list[Claim]:
+    groups: dict[tuple[str, str, str | None, str], Claim] = {}
+    for claim in claims:
+        section = parsed.line_to_section.get(claim.line)
+        if section is None:
+            continue
+        key = (claim.kind.value, claim.value, claim.qualifier, section.section_id)
+        existing = groups.get(key)
+        location = ClaimLocation(
+            line=claim.line, column=claim.column, raw_text=claim.raw_text, extraction=claim.extraction
+        )
+        group_key = hashlib.sha256("\0".join(part or "" for part in key[:3]).encode()).hexdigest()
+        if existing is None:
+            claim.locations = [*claim.locations, location]
+            claim.extraction_sources = list(dict.fromkeys([*claim.extraction_sources, claim.extraction]))
+            claim.group_key = group_key
+            groups[key] = claim
+        else:
+            existing.locations.append(location)
+            existing.extraction_sources = list(dict.fromkeys([*existing.extraction_sources, claim.extraction]))
+            if claim.extraction_confidence > existing.extraction_confidence:
+                existing.extraction_confidence = claim.extraction_confidence
+                existing.expected_default = claim.expected_default or existing.expected_default
+    return list(groups.values())
+
+
+def scan_claims(
+    repo: Path,
+    config: Config,
+    *,
+    doc_paths: set[str] | None = None,
+    contents: dict[str, str] | None = None,
+    source_repo: Path | None = None,
+) -> ScanResult:
+    """Extract claims without importing or running any code in the scanned repository."""
+    root = repo.resolve()
+    timings: dict[str, float] = {}
+    docs = []
+    sections = []
+    claims: list[Claim] = []
+    suppressed: list[SuppressedClaim] = []
+    warnings_out: list[str] = []
+    historical = 0
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always", DiscoveryWarning)
+        with _timed(timings, "discover"):
+            docs = discover_docs(root, config)
+            if doc_paths is not None:
+                docs = [doc for doc in docs if doc.path in doc_paths]
+            if contents:
+                from docs_drift.models import DocFile, DocFormat  # noqa: PLC0415 - optional dependency or shared pipeline import.
+
+                for path, text in contents.items():
+                    docs = [doc for doc in docs if doc.path != path]
+                    docs.append(
+                        DocFile(
+                            path=path,
+                            content_hash=hashlib.sha256(text.encode()).hexdigest(),
+                            format={".rst": DocFormat.rst, ".mdx": DocFormat.mdx}.get(
+                                Path(path).suffix, DocFormat.markdown
+                            ),
+                        )
+                    )
+        warnings_out.extend(str(item.message) for item in caught)
+    command_context = project_command_names(source_repo or root)
+    for doc in docs:
+        try:
+            with _timed(timings, "parse"):
+                parsed = parse_document(
+                    doc, contents[doc.path] if contents and doc.path in contents else read_doc(root, doc)
+                )
+            sections.extend(parsed.sections)
+            with _timed(timings, "inline"):
+                inline = extract_claims(parsed)
+            with _timed(timings, "blocks"):
+                blocks = extract_block_claims(parsed, source_repo or root, command_context=command_context)
+            historical += inline.historical_skipped + blocks.historical_skipped
+            source = [claim for claim in [*inline.claims, *blocks.claims] if claim.kind.value != "default_value"]
+            if doc.format.value == "rst":
+                from docs_drift.docs.preprocess import rst_claims  # noqa: PLC0415 - optional dependency or shared pipeline import.
+
+                source.extend(rst_claims(parsed))
+            with _timed(timings, "defaults"):
+                defaults = extract_defaults(parsed, source)
+            with _timed(timings, "merge_filter"):
+                merged = _merge(parsed, [*source, *defaults.claims])
+                for claim in merged:
+                    section = parsed.line_to_section.get(claim.line)
+                    reason = _suppression(parsed, claim)
+                    if reason:
+                        suppressed.append(SuppressedClaim(claim=claim, reason=reason))
+                    elif section is not None and is_historical_span(section, claim.line):
+                        historical += 1
+                    elif claim.extraction_confidence >= MIN_EXTRACTION_CONFIDENCE and not _ignored(
+                        claim, config.ignore
+                    ):
+                        claims.append(claim)
+                warnings_out.extend(defaults.debug_notes)
+        except Exception as exc:  # A malformed document must not prevent useful scans of its neighbors.
+            warnings_out.append(f"Could not process {doc.path}: {type(exc).__name__}: {exc}")
+    return ScanResult(
+        repo_path=root,
+        head_sha=_head(root),
+        scan_time=snapshot_time(source_repo or root),
+        config_used=config,
+        docs=docs,
+        sections=sections,
+        claims=claims,
+        timings=timings,
+        warnings=warnings_out,
+        suppressed=suppressed,
+        historical_ignored=historical,
+    )

docs_drift/docs/preprocess.py

@@ -0,0 +1,71 @@
+"""Line-preserving MDX stripping and explicit reStructuredText claims."""
+
+import re
+
+from docs_drift.docs.sections import ParsedDoc
+from docs_drift.ids import make_claim_id
+from docs_drift.models import Claim, ClaimKind, Extraction
+
+
+def strip_mdx(text: str) -> str:
+    lines, fence, importing = [], None, False
+    for line in text.splitlines(keepends=True):
+        marker = re.match(r"\s*(```+|~~~+)", line)
+        if marker:
+            fence = None if fence else marker[1][0]
+        if fence or marker:
+            lines.append(line)
+            continue
+        if re.match(r"^\s*(import|export)\b", line) or importing:
+            importing = not bool(re.search(r"(?:from\s+['\"].*['\"]|[;}])\s*;?\s*$", line))
+            lines.append("\n" if line.endswith("\n") else "")
+        else:
+            # Strip wrappers, retaining child code fences and inline Markdown.
+            lines.append(re.sub(r"</?[A-Z][\w.]*(?:\s[^>]*?)?/?>", lambda m: " " * len(m[0]), line))
+    return "".join(lines)
+
+
+def rst_claims(parsed: ParsedDoc) -> list[Claim]:
+    claims = []
+    counts: dict[tuple[str, str, str], int] = {}
+    for line_no, line in enumerate(parsed.text.splitlines(), 1):
+        for match in re.finditer(r":(option|envvar):`([^`]+)`|``([^`]+)``", line):
+            value = match[2] or match[3]
+            kind = ClaimKind.env_var if match[1] == "envvar" else ClaimKind.cli_flag if value.startswith("-") else None
+            if kind is None:
+                from docs_drift.docs.extract_inline import (  # noqa: PLC0415 - shared lexical rules.
+                    _classify,
+                    _explicit_api_reference,
+                    path_context,
+                )
+
+                # Share explicit API disambiguation without broadening unrelated
+                # RST literals into Markdown-only configuration/prose heuristics.
+                classified = _classify(value)
+                if _explicit_api_reference(value, line):
+                    kind = ClaimKind.symbol
+                elif classified:
+                    kind = classified[0]
+                    value = classified[1]
+            section = parsed.line_to_section.get(line_no)
+            if kind is None or section is None:
+                continue
+            key = (section.section_id, kind.value, value)
+            occurrence = counts.get(key, 0)
+            counts[key] = occurrence + 1
+            claims.append(
+                Claim(
+                    claim_id=make_claim_id(parsed.doc.path, section.heading_path, kind.value, value, occurrence),
+                    kind=kind,
+                    raw_text=line,
+                    value=value,
+                    qualifier=path_context(line, value) if kind == ClaimKind.file_path else None,
+                    doc_path=parsed.doc.path,
+                    line=line_no,
+                    column=match.start(2 if match[2] else 3) + 1,
+                    section_id=section.section_id,
+                    extraction=Extraction.inline_code,
+                    extraction_confidence=0.99 if match[1] else 0.9,
+                )
+            )
+    return claims

docs_drift/docs/sections.py

@@ -0,0 +1,247 @@
+"""Parse documentation locations and historical context without executing embedded content."""
+
+import re
+from collections import Counter
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import PurePosixPath
+
+from markdown_it import MarkdownIt
+from markdown_it.token import Token
+
+from docs_drift.ids import make_section_id
+from docs_drift.limits import MAX_DOC_CHARS, MAX_LINE_CHARS, MAX_MARKUP_OPENERS
+from docs_drift.models import DocFile, DocFormat, Section, SectionContext
+
+MIN_ADORNMENT_LENGTH = 3
+
+
+@dataclass(frozen=True)
+class ParsedDoc:
+    doc: DocFile
+    sections: list[Section]
+    tokens: list[Token]
+    line_to_section: dict[int, Section]
+    text: str
+
+    @cached_property
+    def lines(self) -> list[str]:
+        return self.text.splitlines()
+
+
+def _historical_heading(heading: str) -> bool:
+    words = (
+        r"\b(?:change[- ]?log|release notes|history|migrat\w*|upgrad\w*|deprecat\w*|legacy|"
+        r"breaking changes|what['\u2019]s new)\b"
+    )
+    versions = r"\bv\d+(?:\.\d+)*(?:\.x)?\b|\b\d+(?:\.\d+)*\.x\b|\b\d+\.\d+\.\d+\b"
+    illustrative = r"\b(?:synthetic|illustrative)\s+(?:examples?|fixtures?)\b"
+    return re.search(f"{words}|{versions}|{illustrative}", heading, re.IGNORECASE) is not None
+
+
+def _historical_file(path: str) -> bool:
+    return (
+        re.match(
+            r"^(?:change[-_ ]?log|history|releases?|upgrading|migrations?)(?:[._ -]|$)",
+            PurePosixPath(path).stem,
+            re.IGNORECASE,
+        )
+        is not None
+    )
+
+
+def _historical_paragraph(text: str) -> bool:
+    return (
+        re.search(
+            r"\b(?:previously|formerly|was\s+renamed\s+to|no\s+longer|deprecated\s+in|removed\s+in|used\s+to\s+be)\b",
+            text,
+            re.IGNORECASE,
+        )
+        is not None
+    )
+
+
+def _skip_front_matter(text: str) -> tuple[str, int]:
+    lines = text.splitlines(keepends=True)
+    if lines and lines[0].rstrip().removeprefix("\ufeff") == "---":
+        for index, line in enumerate(lines[1:], 1):
+            if line.rstrip() == "---":
+                return "\n" * (index + 1) + "".join(lines[index + 1 :]), index + 1
+    return text, 0
+
+
+def _inline_text(token: Token, *, include_code: bool = True) -> str:
+    if token.children is None:
+        return token.content
+    return "".join(
+        child.content
+        if child.type in {"text", "image"} or (include_code and child.type == "code_inline")
+        else (" " if child.type in {"softbreak", "hardbreak", "code_inline"} else "")
+        for child in token.children
+    )
+
+
+@dataclass(frozen=True)
+class _Heading:
+    text: str
+    level: int
+    line: int
+
+
+def _headings(tokens: list[Token]) -> list[_Heading]:
+    return [
+        _Heading(_inline_text(tokens[index + 1]), int(token.tag[1:]), token.map[0] + 1)
+        for index, token in enumerate(tokens)
+        if token.type == "heading_open" and token.map is not None
+    ]
+
+
+def _sections(doc: DocFile, text: str, tokens: list[Token], skipped: int) -> list[Section]:
+    headings = _headings(tokens)
+    lines = text.splitlines()
+    first_heading = headings[0].line - 1 if headings else len(lines)
+    if any(line.strip() for line in lines[skipped:first_heading]):
+        headings.insert(0, _Heading("(top)", 0, skipped + 1))
+    stack: list[_Heading] = []
+    occurrences: Counter[tuple[str, ...]] = Counter()
+    sections = []
+    for index, heading in enumerate(headings):
+        while stack and stack[-1].level >= heading.level:
+            stack.pop()
+        trail = [parent.text for parent in stack if parent.level] + ([heading.text] if heading.level else [])
+        occurrence = occurrences[tuple(trail)]
+        occurrences[tuple(trail)] += 1
+        context = (
+            SectionContext.historical
+            if _historical_file(doc.path) or any(map(_historical_heading, trail))
+            else SectionContext.current
+        )
+        sections.append(
+            Section(
+                section_id=make_section_id(doc.path, trail, occurrence),
+                doc_path=doc.path,
+                heading=heading.text,
+                heading_level=heading.level,
+                heading_path=trail,
+                start_line=heading.line,
+                end_line=headings[index + 1].line - 1 if index + 1 < len(headings) else len(lines),
+                context=context,
+            )
+        )
+        stack.append(heading)
+    return sections
+
+
+def _adornment(line: str) -> str | None:
+    text = line.strip()
+    return text[0] if len(text) >= MIN_ADORNMENT_LENGTH and text[0] in '=-~^"+#*' and len(set(text)) == 1 else None
+
+
+def _rst_heading(lines: list[str], index: int) -> tuple[str, str, int] | None:
+    if index + 2 < len(lines) and _adornment(lines[index]) and _adornment(lines[index]) == _adornment(lines[index + 2]):
+        return lines[index + 1].strip(), "over:" + lines[index].strip()[0], 3
+    if (
+        index + 1 < len(lines)
+        and lines[index].strip()
+        and _adornment(lines[index + 1])
+        and len(lines[index + 1].strip()) >= len(lines[index].strip())
+    ):
+        return lines[index].strip(), "under:" + lines[index + 1].strip()[0], 2
+    return None
+
+
+def _simple_tokens(text: str, *, rst: bool) -> list[Token]:
+    lines = text.splitlines()
+    tokens: list[Token] = []
+    levels: dict[str, int] = {}
+    index = 0
+    while index < len(lines):
+        directive = re.match(r"\s*\.\.\s+code-block::\s*(\S*)", lines[index]) if rst else None
+        if directive:
+            start = index
+            index += 1
+            while index < len(lines) and (not lines[index].strip() or lines[index].lstrip().startswith(":")):
+                index += 1
+            content_start = index
+            while index < len(lines) and (not lines[index].strip() or lines[index].startswith((" ", "\t"))):
+                index += 1
+            import textwrap  # noqa: PLC0415 - optional dependency or shared pipeline import.
+
+            token = Token(
+                "fence",
+                "code",
+                0,
+                map=[content_start - 1, index],
+                info=directive[1],
+                content=textwrap.dedent("\n".join(lines[content_start:index])) + "\n",
+            )
+            tokens.append(token)
+            continue
+        heading = _rst_heading(lines, index) if rst else None
+        if heading is not None:
+            title, adornment, count = heading
+            level = levels.setdefault(adornment, len(levels) + 1)
+            tokens.extend(
+                [
+                    Token("heading_open", f"h{level}", 1, map=[index, index + count]),
+                    Token("inline", "", 0, content=title, map=[index, index + count]),
+                    Token("heading_close", f"h{level}", -1),
+                ]
+            )
+            index += count
+        elif lines[index].strip():
+            start = index
+            index += 1
+            while index < len(lines) and lines[index].strip() and not (rst and _rst_heading(lines, index)):
+                index += 1
+            tokens.extend(
+                [
+                    Token("paragraph_open", "p", 1, map=[start, index]),
+                    Token("inline", "", 0, content="\n".join(lines[start:index]), map=[start, index]),
+                    Token("paragraph_close", "p", -1),
+                ]
+            )
+        else:
+            index += 1
+    return tokens
+
+
+def _mark_paragraphs(tokens: list[Token], mapping: dict[int, Section]) -> None:
+    for index, token in enumerate(tokens):
+        if token.type != "paragraph_open" or token.map is None:
+            continue
+        if _historical_paragraph(_inline_text(tokens[index + 1], include_code=False)):
+            first, end = token.map[0] + 1, token.map[1]
+            section = mapping.get(first)
+            if section is not None:
+                section.historical_spans.append((first, end))
+
+
+def is_historical_span(section: Section, line: int) -> bool:
+    """Paragraph markers suppress their full paragraph, never the rest of a current section."""
+    return section.start_line <= line <= section.end_line and (
+        section.context == SectionContext.historical
+        or any(start <= line <= end for start, end in section.historical_spans)
+    )
+
+
+def parse_document(doc: DocFile, text: str) -> ParsedDoc:
+    """Partition physical lines at every heading; map lines to their most specific section."""
+    if len(text) > MAX_DOC_CHARS or any(len(line) > MAX_LINE_CHARS for line in text.splitlines()):
+        raise ValueError("Document exceeds the parser size or 8,192-character line limit; split generated content.")
+    if doc.format in {DocFormat.markdown, DocFormat.mdx}:
+        if any(line.count("[") + line.count("(") > MAX_MARKUP_OPENERS for line in text.splitlines()):
+            raise ValueError("Document exceeds the Markdown parser delimiter limit; split densely nested markup.")
+        if doc.format == DocFormat.mdx:
+            from docs_drift.docs.preprocess import strip_mdx  # noqa: PLC0415 - optional dependency or shared pipeline import.
+
+            text = strip_mdx(text)
+        source, skipped = _skip_front_matter(text)
+        tokens = MarkdownIt("commonmark", {"html": False, "maxNesting": 20}).enable("table").parse(source)
+    else:
+        source, skipped = text, 0
+        tokens = _simple_tokens(source, rst=doc.format == DocFormat.rst)
+    sections = _sections(doc, source, tokens, skipped)
+    mapping = {line: section for section in sections for line in range(section.start_line, section.end_line + 1)}
+    _mark_paragraphs(tokens, mapping)
+    return ParsedDoc(doc, sections, tokens, mapping, text)

docs_drift/errors.py

@@ -0,0 +1,119 @@
+"""Friendly CLI boundary, with local debug logs for unexpected failures."""
+
+import sys
+import traceback
+from contextlib import nullcontext, redirect_stdout
+from io import StringIO
+from pathlib import Path
+from typing import Any
+
+from typer import _click as click
+from typer._click import Context
+from typer.core import TyperCommand, TyperGroup
+from typer.exceptions import Abort, Exit
+
+from docs_drift.llm.privacy import mask_secrets
+
+
+class DocsDriftError(Exception):
+    def __init__(self, message: str, hint: str | None = None):
+        super().__init__(message)
+        self.hint = hint
+
+
+COMMON_VALUES = {"--repo", "--config", "--format", "--output", "--output-json", "--output-sarif"}
+COMMON_FLAGS = {"--verbose", "-v", "--quiet", "-q", "--no-color", "--debug", "--show-authors"}
+
+
+class Command(TyperCommand):
+    def get_help(self, ctx: Context) -> str:
+        path = " ".join(ctx.command_path.split()[1:])
+        argument = " <id>" if self.name in {"explain", "ignore"} else " --yes" if self.name == "init" else ""
+        self.epilog = self.epilog or f"Example: docs-drift {path}{argument} --repo ."
+        return (
+            super().get_help(ctx)
+            + "\nCommon options: --repo PATH, --format FORMAT, --output PATH, -q/--quiet, -v/--verbose,"
+            " --no-color, --debug.\n"
+        )
+
+
+class Group(TyperGroup):
+    def get_help(self, ctx: Context) -> str:
+        path = " ".join(ctx.command_path.split()[1:])
+        leaf = "update" if path.endswith("baseline") else "clear" if path.endswith("cache") else "scan"
+        self.epilog = self.epilog or f"Example: docs-drift {path} {leaf} --repo ."
+        return super().get_help(ctx)
+
+    def parse_args(self, ctx: Context, args: list[str]) -> list[str]:
+        if ctx.parent is not None:
+            return super().parse_args(ctx, args)
+        # Global options have identical meaning before and after any subcommand.
+        common, rest = [], []
+        i = 0
+        while i < len(args):
+            token = args[i]
+            key = token.split("=", 1)[0]
+            if token == "--":
+                rest.extend(args[i:])
+                break
+            if key in COMMON_VALUES or key in COMMON_FLAGS:
+                common.append(token)
+                if key in COMMON_VALUES and "=" not in token and i + 1 < len(args):
+                    i += 1
+                    common.append(args[i])
+            else:
+                rest.append(token)
+            i += 1
+        ctx.meta["help_only"] = "--help" in rest
+        return super().parse_args(ctx, common + rest)
+
+    def invoke(self, ctx: Context) -> Any:
+        try:
+            destination = ctx.params.get("output")
+            quiet = ctx.params.get("quiet", False)
+            capture = ctx.parent is None and ctx._protected_args[:1] != ["lsp"] and bool(destination or quiet)
+            buffer = StringIO()
+            with redirect_stdout(buffer) if capture else nullcontext():
+                value = super().invoke(ctx)
+            # Scan renderers write destinations directly. Other commands share
+            # this boundary so --output and --quiet have the same meaning.
+            if capture and destination and buffer.getvalue():
+                target = Path(destination)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(buffer.getvalue(), encoding="utf-8", newline="\n")
+            return value
+        except Exit:
+            if capture and buffer.getvalue():
+                # A failed --quiet check must still explain its findings.
+                sys.stdout.write(buffer.getvalue())
+            raise
+        except (click.ClickException, Abort):
+            raise
+        except Exception as exc:
+            if ctx.parent is not None:
+                raise
+            debug = ctx.params.get("debug", False)
+            root = Path(ctx.params.get("repo", ".")).resolve()
+            if isinstance(exc, DocsDriftError):
+                message = str(exc) + (f"\nHint: {exc.hint}" if exc.hint else "")
+            elif isinstance(exc, (OSError, ValueError)):
+                friendly = DocsDriftError(
+                    str(exc), "Check the selected paths, file permissions and configuration, then retry."
+                )
+                message = f"{friendly}\nHint: {friendly.hint}"
+            else:
+                log = root / ".docs-drift" / "last-error.log"
+                try:
+                    log.parent.mkdir(parents=True, exist_ok=True)
+                    log.write_text(mask_secrets(traceback.format_exc()), encoding="utf-8")
+                    location = str(log)
+                except OSError:
+                    location = "unavailable (repository is not writable)"
+                message = (
+                    f"The scan could not finish ({type(exc).__name__}).\n"
+                    f"Debug log file: last-error.log\nLocation: {location}\n"
+                    "Retry with --debug; report this at https://github.com/ayushagarwalhere/docs-drift/issues/new"
+                )
+            if debug:
+                traceback.print_exc(file=sys.stderr)
+            raise click.ClickException(message) from None

docs_drift/fix/__init__.py

@@ -0,0 +1 @@
+"""Reviewable edits; generation never writes documentation or executes examples."""