doc-drift-py 0.1.1__py3-none-any.whl

doc_drift_py-0.1.1.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: doc-drift-py
+Version: 0.1.1
+Summary: Find the docs that lie: env vars and CLI flags your documentation mentions that the code no longer has, and code nobody documented.
+Author: mgkvibez
+License: MIT
+Keywords: documentation,docs,ci,static-analysis,drift,developer-tools
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+
+# doc-drift
+
+**Find the docs that lie.** `docdrift` reports the environment variables and CLI flags your documentation promises that the code no longer has, and the ones the code has that nobody documented.
+
+[![ci](https://github.com/mgkvibez/doc-drift/actions/workflows/ci.yml/badge.svg)](https://github.com/mgkvibez/doc-drift/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+
+```console docdrift-ignore
+$ docdrift check
+Docs that are wrong now
+  stale-env      LEGACY_TOKEN                 README.md:41
+                 the docs promise it and the code never reads it: rename the doc, or read the variable
+
+Code nobody is told about
+  undocumented-flag  --secret-mode            src/cli.py:22
+                     the flag exists and no one can find it
+
+1 stale in docs, 1 missing from docs (3 docs, 11 source files)
+```
+
+## Why this exists
+
+Docs drift in a specific, boring way: someone renames a variable or deletes a flag, the code stays green, and the README keeps instructing people to use something that no longer exists. Nothing catches it, because tests exercise code and nothing exercises prose.
+
+<!-- docdrift: ignore-next-line -->
+The usual version of this tool greps. Grep lies in both directions: it finds `DATABASE_URL` inside a comment or a deleted branch, and it misses a name that appears with different spacing. `docdrift` reads the source with `ast`, so a variable inside a comment is not a variable, and a renamed function is really renamed.
+
+## Install
+
+```bash
+pipx install doc-drift-py
+```
+
+The distribution is `doc-drift-py` because PyPI refused `doc-drift` as too similar to an
+existing project. The command stays `docdrift`: nothing you type changes.
+
+## Use
+
+```bash
+docdrift check                          # README.md + docs/ against src/ (or .)
+docdrift check --docs docs --src app    # explicit paths
+docdrift check --fail-on stale          # only fail on docs that are wrong, not gaps
+docdrift check --symbols                # also check backticked function/class names
+docdrift check --json                   # machine-readable
+docdrift check --ignore LEGACY_*        # skip a name, exact or prefix
+```
+
+Exit codes are the contract:
+
+| code | meaning |
+|---|---|
+| 0 | nothing drifted |
+| 1 | drift found (the useful failure) |
+| 2 | usage or configuration problem: bad path, no docs, no source |
+
+In CI:
+
+```yaml docdrift-ignore
+- name: Docs tell the truth
+  run: pipx run --spec git+https://github.com/mgkvibez/doc-drift.git docdrift check --fail-on stale
+```
+
+## What counts as a claim
+
+Precision matters more than coverage here, because a checker that cries wolf gets deleted. So a documentation mention only counts when it is written the way a user would read it:
+
+<!-- docdrift: ignore-next-line -->
+- an environment variable in backticks, after `export`, inside `os.environ.get(...)`, or anywhere inside a fenced code block
+<!-- docdrift: ignore-next-line -->
+- a `--flag` written as a flag, not a hyphenated word and not a version range like `1.0--2.0`
+
+Plain uppercase prose is ignored on purpose: `This speaks HTTP and JSON over TCP` is not a claim about your environment.
+
+<!-- docdrift: ignore-next-line -->
+On the code side, only real reads count: `os.environ["X"]`, `os.environ.get("X")`, `os.getenv("X")`, `argparse.add_argument("--flag")`. Files that fail to parse are skipped silently and cannot create findings.
+
+## Suppressing a false positive
+
+Some docs legitimately discuss names they do not promise: a migration guide, an example of another tool's command, a paragraph about how the check works. Two markers handle that, and both keep line numbers honest by blanking rather than deleting.
+
+<!-- docdrift: ignore-next-line -->
+- `<!-- docdrift: ignore-next-line -->` blanks the line that follows it
+- a fence tagged `docdrift-ignore` (` ```console docdrift-ignore `) is treated as an illustration, never as a claim
+
+argparse's own `-h`, `--help` and `--version` are excluded automatically, because no project documents those.
+
+## What it deliberately does not do
+
+- **Not every framework.** Flags are read from `argparse`. Click, Typer and docopt are not parsed yet, and a project using them will report its flags as undocumented. That is a known gap, not a silent one.
+- **Not every language.** Source scanning is Python only. Markdown, RST and plain text docs are read.
+<!-- docdrift: ignore-next-line -->
+- **A flag in an example may not be yours.** `gh run view --log-failed` in your README is a flag of `gh`, not of your project, and it will be reported. Use `--ignore` or tag that fence `docdrift-ignore`. Found by running this on its own sibling project.
+- **Not a prose checker.** It says a name is missing, not that a sentence is wrong.
+- **Symbols are opt-in.** Backticked `function_name` references are heuristic, so they are behind `--symbols` and off by default.
+
+## Dogfooding
+
+This repo runs `docdrift` on itself in the gate, so the README above cannot quietly drift from the code that ships it.
+
+## License
+
+MIT

doc_drift_py-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+docdrift/__init__.py,sha256=C_Enausv6mzM_nxR6u16fMEF36rsEEyCx0ertaN2CVo,53
+docdrift/cli.py,sha256=T-gLr2SMQO4ZJ42un_DTi1nDIEzXNPjCQSmGWGQBBWc,3798
+docdrift/code.py,sha256=kOWtrdZb_i7Qqv2xYQHzol44VSnoRjhpnKbbMXobAlY,4366
+docdrift/compare.py,sha256=NE-PTBK7R6OPkYJw1yojHptLPqgl3665tBIdcRGULhE,2042
+docdrift/docs.py,sha256=qB64cb35O1xt0BLyJu6mVD-ECjQb1t4ZFpy-Pvat-dc,5190
+docdrift/report.py,sha256=GG9dQGh1ZDbzWaA4x1GZ5brTW2b9HmZowVhrkgT5utA,4108
+doc_drift_py-0.1.1.dist-info/METADATA,sha256=BzoOE0DrUimuxeGBCJHv2ScrWNcbLuw-iJAM7eg-5HA,5871
+doc_drift_py-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+doc_drift_py-0.1.1.dist-info/entry_points.txt,sha256=vLNHjC9sdHzy9imyIEC60oY9MpI6qHjibTXtK33lPew,47
+doc_drift_py-0.1.1.dist-info/top_level.txt,sha256=wcmBTBnmnLgshMXanJnF_YEtZgFCVsCFykfvg1tAt9A,9
+doc_drift_py-0.1.1.dist-info/RECORD,,

doc_drift_py-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

doc_drift_py-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docdrift = docdrift.cli:main

doc_drift_py-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+docdrift

docdrift/__init__.py

@@ -0,0 +1,3 @@
+"""Find the docs that lie."""
+
+__version__ = "0.1.1"

docdrift/cli.py

@@ -0,0 +1,99 @@
+"""Command line. Exit codes are part of the contract:
+
+0  nothing drifted
+1  drift found (docdrift is a check, so this is the useful failure)
+2  usage or configuration problem: bad path, nothing to scan, bad flag
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from . import __version__, code, docs
+from .compare import compare
+from .report import ENV, FLAG, SYMBOL, Report, summarise, render_json, render_text
+
+EXIT_CLEAN = 0
+EXIT_DRIFT = 1
+EXIT_USAGE = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="docdrift",
+        description="Find env vars and CLI flags that documentation mentions but code does not have, and vice versa.",
+    )
+    parser.add_argument("--version", action="version", version="docdrift %s" % __version__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    check = sub.add_parser("check", help="compare docs against source")
+    check.add_argument("--docs", action="extend", nargs="+", metavar="PATH", default=None,
+                       help="doc file(s) or dir(s); default README.md and docs/")
+    check.add_argument("--src", action="extend", nargs="+", metavar="PATH", default=None,
+                       help="source file(s) or dir(s); default src/ then .")
+    check.add_argument("--ignore", action="extend", nargs="+", metavar="NAME", default=[],
+                       help="names to skip, exact or prefix with *")
+    check.add_argument("--symbols", action="store_true",
+                       help="also check backticked function/class names (heuristic, off by default)")
+    check.add_argument("--json", action="store_true", help="machine-readable output")
+    check.add_argument("--fail-on", choices=["stale", "any", "none"], default="any",
+                       help="which drift fails the build (default: any)")
+    return parser
+
+
+def _default_docs() -> List[Path]:
+    candidates = [Path("README.md"), Path("README.rst"), Path("docs")]
+    return [p for p in candidates if p.exists()]
+
+
+def _default_src() -> List[Path]:
+    for candidate in (Path("src"), Path(".")):
+        if candidate.exists():
+            return [candidate]
+    return []
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(list(sys.argv[1:] if argv is None else argv))
+
+    doc_paths = [Path(p) for p in (args.docs or [])] or _default_docs()
+    src_paths = [Path(p) for p in (args.src or [])] or _default_src()
+
+    missing = [str(p) for p in doc_paths + src_paths if not p.exists()]
+    if missing:
+        print("error: path not found: %s" % ", ".join(missing), file=sys.stderr)
+        return EXIT_USAGE
+    if not doc_paths:
+        print("error: no docs found; pass --docs or add a README.md", file=sys.stderr)
+        return EXIT_USAGE
+    if not src_paths:
+        print("error: no source found; pass --src", file=sys.stderr)
+        return EXIT_USAGE
+
+    code_facts = code.scan(src_paths)
+    doc_facts = docs.scan(doc_paths, symbols=args.symbols)
+
+    subjects = [ENV, FLAG] + ([SYMBOL] if args.symbols else [])
+    report = Report(
+        docs=[str(p) for p in docs.iter_doc_files(doc_paths)],
+        sources=[str(p) for p in code.iter_python_files(src_paths)],
+        findings=compare(code_facts, doc_facts, subjects=subjects, ignore=args.ignore),
+    )
+
+    print(render_json(report) if args.json else render_text(report))
+
+    if report.ok or args.fail_on == "none":
+        return EXIT_CLEAN
+    if args.fail_on == "stale" and not report.stale():
+        return EXIT_CLEAN
+    line = summarise(report)
+    if line and not args.json:
+        print(line, file=sys.stderr)
+    return EXIT_DRIFT
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

docdrift/code.py

@@ -0,0 +1,112 @@
+"""What the code actually has, read with ast rather than regex.
+
+Grep over source finds names in comments, in dead strings, and in the tests of a
+library you forgot to delete. Parsing means a variable inside a comment is not a
+variable, and a renamed function is really renamed.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple
+
+SKIP_DIRS = {".git", ".venv", "venv", "node_modules", "build", "dist", "__pycache__",
+             ".mypy_cache", ".pytest_cache", ".ruff_cache", "site-packages"}
+
+
+@dataclass
+class CodeFacts:
+    """Where each thing lives, so a finding can point at a line."""
+
+    env: Dict[str, Tuple[str, int]] = field(default_factory=dict)
+    flags: Dict[str, Tuple[str, int]] = field(default_factory=dict)
+    symbols: Dict[str, Tuple[str, int]] = field(default_factory=dict)
+
+    def merge(self, other: "CodeFacts") -> None:
+        for attr in ("env", "flags", "symbols"):
+            mine = getattr(self, attr)
+            for key, value in getattr(other, attr).items():
+                mine.setdefault(key, value)
+
+
+class _Visitor(ast.NodeVisitor):
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self.facts = CodeFacts()
+
+    # os.environ["X"], os.environ.get("X"), os.getenv("X")
+    def _env_name(self, node: ast.AST) -> Optional[str]:
+        if isinstance(node, ast.Subscript):
+            target = node.value
+            if isinstance(target, ast.Attribute) and target.attr == "environ":
+                key = node.slice
+                if isinstance(key, ast.Constant) and isinstance(key.value, str):
+                    return key.value
+        return None
+
+    def visit_Subscript(self, node: ast.Subscript) -> None:
+        name = self._env_name(node)
+        if name:
+            self.facts.env.setdefault(name, (self.path, getattr(node, "lineno", 0)))
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        func = node.func
+        # os.environ.get("X") / os.getenv("X")
+        if isinstance(func, ast.Attribute) and func.attr in ("get", "getenv"):
+            owner = func.value
+            is_environ = (
+                (isinstance(owner, ast.Attribute) and owner.attr == "environ")
+                or (isinstance(owner, ast.Name) and owner.id == "os" and func.attr == "getenv")
+            )
+            if is_environ and node.args:
+                first = node.args[0]
+                if isinstance(first, ast.Constant) and isinstance(first.value, str):
+                    self.facts.env.setdefault(first.value, (self.path, node.lineno))
+        # argparse: add_argument("--flag") / add_argument("-f", "--flag")
+        if isinstance(func, ast.Attribute) and func.attr == "add_argument":
+            for arg in node.args:
+                if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+                    value = arg.value
+                    if value.startswith("-") and len(value) > 1:
+                        self.facts.flags.setdefault(value, (self.path, node.lineno))
+        self.generic_visit(node)
+
+    def _define(self, node) -> None:
+        name = getattr(node, "name", None)
+        if name and not name.startswith("_"):
+            self.facts.symbols.setdefault(name, (self.path, node.lineno))
+        self.generic_visit(node)
+
+    visit_FunctionDef = _define
+    visit_AsyncFunctionDef = _define
+    visit_ClassDef = _define
+
+
+def scan_file(path: Path) -> CodeFacts:
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"), filename=str(path))
+    except SyntaxError:
+        return CodeFacts()  # a file we cannot parse contributes nothing, and says nothing
+    visitor = _Visitor(str(path))
+    visitor.visit(tree)
+    return visitor.facts
+
+
+def iter_python_files(paths: Iterable[Path]) -> Iterable[Path]:
+    for path in paths:
+        if path.is_file() and path.suffix == ".py":
+            yield path
+        elif path.is_dir():
+            for child in sorted(path.rglob("*.py")):
+                if not SKIP_DIRS.intersection(child.parts):
+                    yield child
+
+
+def scan(paths: Sequence[Path]) -> CodeFacts:
+    facts = CodeFacts()
+    for file_path in iter_python_files(paths):
+        facts.merge(scan_file(file_path))
+    return facts

docdrift/compare.py

@@ -0,0 +1,53 @@
+"""Match what the docs claim against what the code does."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+from typing import Iterable, List, Sequence, Set
+
+from .code import CodeFacts
+from .docs import DocFacts
+from .report import ENV, FLAG, STALE, SYMBOL, UNDOCUMENTED, Finding
+
+# argparse generates these; nobody documents them per project
+BUILTIN_FLAGS = ("-h", "--help", "--version")
+
+
+def _ignored(name: str, patterns: Sequence[str]) -> bool:
+    for pattern in patterns:
+        if pattern.endswith("*"):
+            if name.startswith(pattern[:-1]):
+                return True
+        elif fnmatchcase(name, pattern) or name == pattern:
+            return True
+    return False
+
+
+def _pair(doc_map, code_map, subject: str, ignore: Sequence[str]) -> List[Finding]:
+    findings: List[Finding] = []
+    for name, (path, line) in sorted(doc_map.items()):
+        if _ignored(name, ignore):
+            continue
+        if name not in code_map:
+            findings.append(Finding(kind=STALE, subject=subject, name=name, doc_path=path, doc_line=line))
+    for name, (path, line) in sorted(code_map.items()):
+        if _ignored(name, ignore):
+            continue
+        if name not in doc_map:
+            findings.append(Finding(kind=UNDOCUMENTED, subject=subject, name=name, code_path=path, code_line=line))
+    return findings
+
+
+def compare(code: CodeFacts, docs: DocFacts, *, subjects: Iterable[str] = (ENV, FLAG),
+            ignore: Sequence[str] = ()) -> List[Finding]:
+    findings: List[Finding] = []
+    for subject in subjects:
+        if subject == ENV:
+            findings.extend(_pair(docs.env, code.env, ENV, ignore))
+        elif subject == FLAG:
+            findings.extend(_pair(docs.flags, code.flags, FLAG, tuple(ignore) + BUILTIN_FLAGS))
+        elif subject == SYMBOL:
+            findings.extend(_pair(docs.symbols, code.symbols, SYMBOL, ignore))
+    # stale first: those break the reader right now
+    findings.sort(key=lambda f: (f.kind != STALE, f.subject, f.name))
+    return findings

docdrift/docs.py

@@ -0,0 +1,128 @@
+"""What the documentation claims, read conservatively on purpose.
+
+A doc checker loses trust the first time it reports a false positive, so the rules
+here are narrow: an environment variable counts when it is backticked or written in
+a shell context, and a flag counts when it is written the way a user would type it.
+A name that merely looks uppercase is prose, not a claim about the code.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterable, List, Sequence, Set, Tuple
+
+DOC_SUFFIXES = {".md", ".markdown", ".rst", ".txt"}
+
+# --flag, not a hyphenated word and not a range like 1--2
+FLAG_RE = re.compile(r"(?<![\w-])--([a-z0-9][a-z0-9-]*)")
+# backticked token
+BACKTICK_RE = re.compile(r"`([^`\n]{1,120})`")
+# ENV_STYLE_NAME with at least one underscore, or a well-known bare name
+ENV_RE = re.compile(r"(?<!\w)([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)(?!\w)")
+SHELL_CONTEXT_RE = re.compile(r"(?:export\s+$|\bos\.environ\.get\(\s*['\"]|\bgetenv\(\s*['\"])")
+HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.S)
+CODE_SPAN_RE = re.compile(r"`[^`\n]*`")
+FENCE_RE = re.compile(r"^(```|~~~).*?^\1", re.S | re.M)
+# ```console docdrift-ignore ... ```  content is an illustration, never a claim
+IGNORE_FENCE_RE = re.compile(r"^(```|~~~)[^\n]*docdrift-ignore[^\n]*\n.*?^\1", re.S | re.M)
+# <!-- docdrift: ignore-next-line --> blanks the line after it
+IGNORE_NEXT_RE = re.compile(r"<!--\s*docdrift:\s*ignore-next-line\s*-->[^\n]*\n[^\n]*")
+
+# words that are capitalised and underscored but are not variables
+ENV_STOPWORDS = {
+    "README", "CHANGELOG", "TODO", "FIXME", "NOTE", "WARNING", "USAGE", "MIT",
+    "HTTP_200", "HTTP_404", "HTTP_500", "SOC", "SOC_2", "AI_ML", "CI_CD",
+}
+
+
+@dataclass
+class DocFacts:
+    """name -> (path, line)"""
+
+    env: Dict[str, Tuple[str, int]] = field(default_factory=dict)
+    flags: Dict[str, Tuple[str, int]] = field(default_factory=dict)
+    symbols: Dict[str, Tuple[str, int]] = field(default_factory=dict)
+
+    def merge(self, other: "DocFacts") -> None:
+        for attr in ("env", "flags", "symbols"):
+            mine = getattr(self, attr)
+            for key, value in getattr(other, attr).items():
+                mine.setdefault(key, value)
+
+
+def _strip_noise(text: str) -> str:
+    """Blank out anything that is not a claim, keeping line numbers intact.
+
+    Blanking rather than deleting is deliberate: every reported line number has to
+    match the file a human will open.
+    """
+    def blank(match: "re.Match[str]") -> str:
+        return re.sub(r"[^\n]", " ", match.group(0))
+
+    text = IGNORE_NEXT_RE.sub(blank, text)
+    text = IGNORE_FENCE_RE.sub(blank, text)
+    return HTML_COMMENT_RE.sub(blank, text)
+
+
+def _line_of(text: str, offset: int) -> int:
+    return text.count("\n", 0, offset) + 1
+
+
+def scan_doc(path: Path, *, symbols: bool = False) -> DocFacts:
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    text = _strip_noise(raw)
+    facts = DocFacts()
+    name = str(path)
+
+    for match in FLAG_RE.finditer(text):
+        facts.flags.setdefault("--" + match.group(1), (name, _line_of(text, match.start())))
+
+    for match in ENV_RE.finditer(text):
+        candidate = match.group(1)
+        if candidate in ENV_STOPWORDS:
+            continue
+        line_start = text.rfind("\n", 0, match.start()) + 1
+        prefix = text[line_start:match.start()]
+        backticked = prefix.count("`") % 2 == 1 or text[match.end():match.end() + 1] == "`"
+        shellish = bool(SHELL_CONTEXT_RE.search(prefix))
+        # inside a code fence counts as a claim, since that is where commands live
+        fenced = any(f.start() < match.start() < f.end() for f in FENCE_RE.finditer(text))
+        if backticked or shellish or fenced:
+            facts.env.setdefault(candidate, (name, _line_of(text, match.start())))
+
+    for match in BACKTICK_RE.finditer(text):
+        token = match.group(1).strip()
+        if token.isupper() and len(token) >= 2 and token not in ENV_STOPWORDS:
+            facts.env.setdefault(token, (name, _line_of(text, match.start())))
+        elif symbols and _looks_like_symbol(token):
+            facts.symbols.setdefault(token.split("(")[0].strip(), (name, _line_of(text, match.start())))
+
+    return facts
+
+
+def _looks_like_symbol(token: str) -> bool:
+    token = token.split("(")[0].strip()
+    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*", token):
+        return False
+    if token.isupper():
+        return False  # that is an env var or a constant, handled above
+    return "_" in token or token[:1].isupper()
+
+
+def iter_doc_files(paths: Iterable[Path]) -> Iterable[Path]:
+    for path in paths:
+        if path.is_file() and path.suffix.lower() in DOC_SUFFIXES:
+            yield path
+        elif path.is_dir():
+            for child in sorted(path.rglob("*")):
+                if child.is_file() and child.suffix.lower() in DOC_SUFFIXES:
+                    yield child
+
+
+def scan(paths: Sequence[Path], *, symbols: bool = False) -> DocFacts:
+    facts = DocFacts()
+    for file_path in iter_doc_files(paths):
+        facts.merge(scan_doc(file_path, symbols=symbols))
+    return facts

docdrift/report.py

@@ -0,0 +1,121 @@
+"""Findings and their rendering.
+
+Two kinds of drift, in both directions: docs that mention something the code no
+longer has, and code that nothing in the docs mentions. The first breaks whoever
+follows the instructions, the second hides a feature from them.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+STALE = "stale"          # docs mention it, code does not have it
+UNDOCUMENTED = "undocumented"  # code has it, docs do not mention it
+
+ENV = "env"
+FLAG = "flag"
+SYMBOL = "symbol"
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str            # STALE | UNDOCUMENTED
+    subject: str         # ENV | FLAG | SYMBOL
+    name: str
+    doc_path: str = ""
+    doc_line: int = 0
+    code_path: str = ""
+    code_line: int = 0
+
+    @property
+    def label(self) -> str:
+        return "%s-%s" % (self.kind, self.subject)
+
+    def as_dict(self) -> Dict[str, object]:
+        data = {"kind": self.kind, "subject": self.subject, "name": self.name}
+        if self.doc_path:
+            data["doc"] = {"path": self.doc_path, "line": self.doc_line}
+        if self.code_path:
+            data["code"] = {"path": self.code_path, "line": self.code_line}
+        return data
+
+
+@dataclass
+class Report:
+    docs: List[str] = field(default_factory=list)
+    sources: List[str] = field(default_factory=list)
+    findings: List[Finding] = field(default_factory=list)
+
+    def stale(self) -> List[Finding]:
+        return [f for f in self.findings if f.kind == STALE]
+
+    def undocumented(self) -> List[Finding]:
+        return [f for f in self.findings if f.kind == UNDOCUMENTED]
+
+    @property
+    def ok(self) -> bool:
+        return not self.findings
+
+    def counts(self) -> Dict[str, int]:
+        return {"stale": len(self.stale()), "undocumented": len(self.undocumented())}
+
+
+_ADVICE = {
+    (STALE, ENV): "the docs promise it and the code never reads it: rename the doc, or read the variable",
+    (STALE, FLAG): "the docs document a flag the parser does not define, so following them fails",
+    (STALE, SYMBOL): "the docs name something no longer defined, so the example will not run",
+    (UNDOCUMENTED, ENV): "the code reads a variable nobody is told to set",
+    (UNDOCUMENTED, FLAG): "the flag exists and no one can find it",
+    (UNDOCUMENTED, SYMBOL): "public surface with no mention anywhere",
+}
+
+
+def render_text(report: Report) -> str:
+    if report.ok:
+        return "no issues found by docdrift v%s across %d doc(s) and %d source file(s)" % (
+            _version(), len(report.docs), len(report.sources))
+
+    lines = []
+    for group, title in ((STALE, "Docs that are wrong now"), (UNDOCUMENTED, "Code nobody is told about")):
+        items = [f for f in report.findings if f.kind == group]
+        if not items:
+            continue
+        lines.append(title)
+        for f in items:
+            where = "%s:%d" % (f.doc_path, f.doc_line) if f.doc_path else "%s:%d" % (f.code_path, f.code_line)
+            lines.append("  %-14s %-28s %s" % (f.label, f.name, where))
+            advice = _ADVICE.get((f.kind, f.subject))
+            if advice:
+                lines.append("  %-14s %s" % ("", advice))
+        lines.append("")
+
+    c = report.counts()
+    lines.append("%d stale in docs, %d missing from docs (%d docs, %d source files)" % (
+        c["stale"], c["undocumented"], len(report.docs), len(report.sources)))
+    return "\n".join(lines).rstrip()
+
+
+def render_json(report: Report) -> str:
+    return json.dumps({
+        "tool": "docdrift",
+        "version": _version(),
+        "docs": report.docs,
+        "sources": report.sources,
+        "counts": report.counts(),
+        "findings": [f.as_dict() for f in report.findings],
+    }, indent=2)
+
+
+def _version() -> str:
+    from . import __version__
+    return __version__
+
+
+def summarise(report: Report) -> Optional[str]:
+    """One line for CI logs, or None when clean."""
+    if report.ok:
+        return None
+    c = report.counts()
+    return "docdrift: %d stale reference(s), %d undocumented item(s)" % (c["stale"], c["undocumented"])