doc-drift-py 0.1.1__tar.gz

doc_drift_py-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,103 @@
+# 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/doc_drift_py.egg-info/PKG-INFO

@@ -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/doc_drift_py.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+doc_drift_py.egg-info/PKG-INFO
+doc_drift_py.egg-info/SOURCES.txt
+doc_drift_py.egg-info/dependency_links.txt
+doc_drift_py.egg-info/entry_points.txt
+doc_drift_py.egg-info/requires.txt
+doc_drift_py.egg-info/top_level.txt
+docdrift/__init__.py
+docdrift/cli.py
+docdrift/code.py
+docdrift/compare.py
+docdrift/docs.py
+docdrift/report.py
+tests/test_cli.py
+tests/test_code.py
+tests/test_docs.py

doc_drift_py-0.1.1/doc_drift_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

doc_drift_py-0.1.1/doc_drift_py.egg-info/entry_points.txt

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

doc_drift_py-0.1.1/doc_drift_py.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8
+build>=1.0

doc_drift_py-0.1.1/doc_drift_py.egg-info/top_level.txt

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

doc_drift_py-0.1.1/docdrift/__init__.py

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

doc_drift_py-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())

doc_drift_py-0.1.1/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

doc_drift_py-0.1.1/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

doc_drift_py-0.1.1/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

doc_drift_py-0.1.1/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"])

doc_drift_py-0.1.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "doc-drift-py"
+version = "0.1.1"
+description = "Find the docs that lie: env vars and CLI flags your documentation mentions that the code no longer has, and code nobody documented."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "mgkvibez"}]
+keywords = ["documentation", "docs", "ci", "static-analysis", "drift", "developer-tools"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Environment :: Console",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Documentation",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.0"]
+
+[project.scripts]
+docdrift = "docdrift.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["docdrift*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

doc_drift_py-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

doc_drift_py-0.1.1/tests/test_cli.py

@@ -0,0 +1,134 @@
+"""End to end: exit codes are the contract CI depends on."""
+
+from __future__ import annotations
+
+import json
+import textwrap
+
+import pytest
+
+from docdrift import __version__
+from docdrift.cli import main
+
+
+def project(tmp_path, readme, source):
+    (tmp_path / "README.md").write_text(textwrap.dedent(readme), encoding="utf-8")
+    src = tmp_path / "src"
+    src.mkdir(exist_ok=True)
+    (src / "app.py").write_text(textwrap.dedent(source), encoding="utf-8")
+    return tmp_path
+
+
+@pytest.fixture
+def clean(tmp_path, monkeypatch):
+    path = project(tmp_path, "Set `DATABASE_URL`.\n", """
+        import os
+        KEY = os.environ["DATABASE_URL"]
+    """)
+    monkeypatch.chdir(path)
+    return path
+
+
+def test_clean_project_exits_zero(clean, capsys):
+    assert main(["check"]) == 0
+    out = capsys.readouterr().out
+    assert "no issues found by docdrift v%s" % __version__ in out
+
+
+def test_stale_env_var_fails(tmp_path, monkeypatch, capsys):
+    path = project(tmp_path, "Set `DATABASE_URL` and `LEGACY_TOKEN`.\n", """
+        import os
+        KEY = os.environ["DATABASE_URL"]
+    """)
+    monkeypatch.chdir(path)
+    assert main(["check"]) == 1
+    out = capsys.readouterr().out
+    assert "stale-env" in out and "LEGACY_TOKEN" in out
+    assert "README.md:1" in out
+
+
+def test_undocumented_flag_fails_by_default(tmp_path, monkeypatch, capsys):
+    path = project(tmp_path, "Just prose.\n", """
+        import argparse
+        p = argparse.ArgumentParser()
+        p.add_argument("--secret-mode", action="store_true")
+    """)
+    monkeypatch.chdir(path)
+    assert main(["check"]) == 1
+    assert "undocumented-flag" in capsys.readouterr().out
+
+
+def test_fail_on_stale_ignores_undocumented_only(tmp_path, monkeypatch):
+    path = project(tmp_path, "Just prose.\n", """
+        import argparse
+        p = argparse.ArgumentParser()
+        p.add_argument("--secret-mode", action="store_true")
+    """)
+    monkeypatch.chdir(path)
+    assert main(["check", "--fail-on", "stale"]) == 0
+
+
+def test_fail_on_none_never_fails(tmp_path, monkeypatch):
+    path = project(tmp_path, "Set `GONE`.\n", "")
+    monkeypatch.chdir(path)
+    assert main(["check", "--fail-on", "none"]) == 0
+
+
+def test_ignore_exact_and_prefix(tmp_path, monkeypatch, capsys):
+    path = project(tmp_path, "Set `GONE` and `ALSO_GONE`.\n", "")
+    monkeypatch.chdir(path)
+    assert main(["check", "--ignore", "GONE", "--ignore", "ALSO_*"]) == 0
+    assert "no issues found" in capsys.readouterr().out
+
+
+def test_json_output_shape(tmp_path, monkeypatch, capsys):
+    path = project(tmp_path, "Set `GONE`.\n", "")
+    monkeypatch.chdir(path)
+    assert main(["check", "--json"]) == 1
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["counts"]["stale"] == 1
+    finding = payload["findings"][0]
+    assert finding["kind"] == "stale" and finding["subject"] == "env"
+    assert finding["doc"]["line"] == 1
+
+
+def test_missing_path_is_a_usage_error(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert main(["check", "--docs", "nope.md"]) == 2
+
+
+def test_no_docs_anywhere_is_a_usage_error(tmp_path, monkeypatch):
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "app.py").write_text("x = 1\n", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+    assert main(["check"]) == 2
+
+
+def test_symbols_flag_finds_renamed_function(tmp_path, monkeypatch, capsys):
+    path = project(tmp_path, "Call `old_helper()` to start.\n", """
+        def new_helper():
+            pass
+    """)
+    monkeypatch.chdir(path)
+    assert main(["check"]) == 0
+    assert main(["check", "--symbols"]) == 1
+    assert "stale-symbol" in capsys.readouterr().out
+
+
+def test_version_flag(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert __version__ in capsys.readouterr().out
+
+
+def test_builtin_argparse_flags_are_never_reported(tmp_path, monkeypatch, capsys):
+    path = project(tmp_path, "Just prose.\n", """
+        import argparse
+        p = argparse.ArgumentParser()
+        p.add_argument("--version", action="version", version="1")
+        p.add_argument("--help")
+    """)
+    monkeypatch.chdir(path)
+    assert main(["check"]) == 0
+    assert "undocumented-flag" not in capsys.readouterr().out

doc_drift_py-0.1.1/tests/test_code.py

@@ -0,0 +1,115 @@
+"""Code-side extraction. ast, not grep, is the point."""
+
+from __future__ import annotations
+
+import textwrap
+
+from docdrift.code import scan, scan_file
+
+
+def write(tmp_path, name, body):
+    path = tmp_path / name
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(textwrap.dedent(body), encoding="utf-8")
+    return path
+
+
+def test_os_environ_subscript(tmp_path):
+    path = write(tmp_path, "a.py", """
+        import os
+        key = os.environ["DATABASE_URL"]
+    """)
+    facts = scan_file(path)
+    assert "DATABASE_URL" in facts.env
+
+
+def test_os_environ_get(tmp_path):
+    path = write(tmp_path, "a.py", """
+        import os
+        key = os.environ.get("API_TOKEN", "")
+    """)
+    assert "API_TOKEN" in scan_file(path).env
+
+
+def test_os_getenv(tmp_path):
+    path = write(tmp_path, "a.py", """
+        import os
+        key = os.getenv("STRIPE_KEY")
+    """)
+    assert "STRIPE_KEY" in scan_file(path).env
+
+
+def test_env_name_in_a_comment_is_not_a_read(tmp_path):
+    path = write(tmp_path, "a.py", """
+        # os.environ["GHOST_VAR"] is handled elsewhere
+        x = 1
+    """)
+    assert scan_file(path).env == {}
+
+
+def test_env_name_in_a_dead_string_is_not_a_read(tmp_path):
+    path = write(tmp_path, "a.py", """
+        MESSAGE = 'set os.environ["GHOST_VAR"] first'
+    """)
+    assert scan_file(path).env == {}
+
+
+def test_argparse_flags_including_short_forms(tmp_path):
+    path = write(tmp_path, "a.py", """
+        import argparse
+        p = argparse.ArgumentParser()
+        p.add_argument("--dry-run", action="store_true")
+        p.add_argument("-f", "--file")
+    """)
+    facts = scan_file(path)
+    assert "--dry-run" in facts.flags
+    assert "--file" in facts.flags
+    assert "-f" in facts.flags
+
+
+def test_non_flag_add_argument_positionals_ignored(tmp_path):
+    path = write(tmp_path, "a.py", """
+        import argparse
+        p = argparse.ArgumentParser()
+        p.add_argument("target")
+    """)
+    assert scan_file(path).flags == {}
+
+
+def test_symbols_defined_and_private_excluded(tmp_path):
+    path = write(tmp_path, "a.py", """
+        def public_thing():
+            pass
+
+        def _private_thing():
+            pass
+
+        class Widget:
+            pass
+
+        async def fetch_all():
+            pass
+    """)
+    facts = scan_file(path)
+    assert "public_thing" in facts.symbols
+    assert "Widget" in facts.symbols
+    assert "fetch_all" in facts.symbols
+    assert "_private_thing" not in facts.symbols
+
+
+def test_unparseable_file_is_skipped_silently(tmp_path):
+    path = write(tmp_path, "broken.py", """
+        def oops(:
+    """)
+    facts = scan_file(path)
+    assert facts.env == {} and facts.flags == {} and facts.symbols == {}
+
+
+def test_scan_merges_a_tree_and_skips_vendored_dirs(tmp_path):
+    write(tmp_path, "pkg/a.py", 'import os\nX = os.environ["ONE"]\n')
+    write(tmp_path, "pkg/deep/b.py", 'import os\nY = os.getenv("TWO")\n')
+    vendored = tmp_path / ".venv" / "lib"
+    vendored.mkdir(parents=True)
+    (vendored / "c.py").write_text('import os\nZ = os.getenv("VENDORED")\n', encoding="utf-8")
+    facts = scan([tmp_path])
+    assert set(facts.env) == {"ONE", "TWO"}

doc_drift_py-0.1.1/tests/test_docs.py

@@ -0,0 +1,137 @@
+"""Doc-side extraction. The hard requirement here is no false positives."""
+
+from __future__ import annotations
+
+import textwrap
+
+from docdrift.docs import scan_doc
+
+
+def write(tmp_path, name, body):
+    path = tmp_path / name
+    path.write_text(textwrap.dedent(body), encoding="utf-8")
+    return path
+
+
+def test_backticked_env_var_is_a_claim(tmp_path):
+    path = write(tmp_path, "README.md", "Set `DATABASE_URL` before starting.\n")
+    assert "DATABASE_URL" in scan_doc(path).env
+
+
+def test_export_line_is_a_claim(tmp_path):
+    path = write(tmp_path, "README.md", "export STRIPE_SECRET_KEY=sk_test\n")
+    assert "STRIPE_SECRET_KEY" in scan_doc(path).env
+
+
+def test_fenced_block_is_a_claim(tmp_path):
+    path = write(tmp_path, "README.md", """
+        ```bash
+        API_TOKEN=abc uvicorn app:app
+        ```
+    """)
+    assert "API_TOKEN" in scan_doc(path).env
+
+
+def test_plain_prose_acronyms_are_not_claims(tmp_path):
+    path = write(tmp_path, "README.md", "This speaks HTTP and JSON over TCP, not XML.\n")
+    facts = scan_doc(path)
+    assert facts.env == {}
+
+
+def test_uppercase_words_without_underscores_are_not_claims(tmp_path):
+    path = write(tmp_path, "README.md", "Use the CLI, read the README, the MIT license applies.\n")
+    assert scan_doc(path).env == {}
+
+
+def test_html_comment_is_ignored(tmp_path):
+    path = write(tmp_path, "README.md", """
+        Visible text.
+        <!-- Set `SECRET_FROM_COMMENT` when debugging. -->
+        More visible text.
+    """)
+    assert "SECRET_FROM_COMMENT" not in scan_doc(path).env
+
+
+def test_long_flag_is_a_claim(tmp_path):
+    path = write(tmp_path, "README.md", "Run `docdrift check --fail-on stale`.\n")
+    assert "--fail-on" in scan_doc(path).flags
+
+
+def test_number_range_is_not_a_flag(tmp_path):
+    path = write(tmp_path, "README.md", "Covers versions 1.0--2.0 only.\n")
+    assert scan_doc(path).flags == {}
+
+
+def test_bare_double_dash_is_not_a_flag(tmp_path):
+    path = write(tmp_path, "README.md", "Then run `-- status`.\n")
+    assert scan_doc(path).flags == {}
+
+
+def test_symbols_off_by_default(tmp_path):
+    path = write(tmp_path, "README.md", "Call `parse_flags()` yourself.\n")
+    assert scan_doc(path).symbols == {}
+
+
+def test_backticked_snake_case_symbol_when_enabled(tmp_path):
+    path = write(tmp_path, "README.md", "Call `parse_flags()` yourself.\n")
+    assert "parse_flags" in scan_doc(path, symbols=True).symbols
+
+
+def test_backticked_uppercase_is_not_a_symbol(tmp_path):
+    path = write(tmp_path, "README.md", "Set `DATABASE_URL` first.\n")
+    assert scan_doc(path, symbols=True).symbols == {}
+
+
+def test_line_numbers_point_at_the_claim(tmp_path):
+    path = write(tmp_path, "README.md", """
+        # Title
+
+        Some text.
+
+        Set `MISSING_VAR` here.
+    """)
+    facts = scan_doc(path)
+    assert facts.env["MISSING_VAR"][1] == 6
+
+
+# --- suppressions: the difference between a useful checker and a noisy one ---
+
+def test_fenced_block_tagged_ignore_is_not_a_claim(tmp_path):
+    path = write(tmp_path, "README.md", """
+        ```console docdrift-ignore
+        $ tool --not-a-real-flag
+        Set `NOT_REAL_EITHER`.
+        ```
+    """)
+    facts = scan_doc(path)
+    assert facts.flags == {} and facts.env == {}
+
+
+def test_untagged_fence_is_still_a_claim(tmp_path):
+    path = write(tmp_path, "README.md", """
+        ```console
+        $ tool --real-flag
+        ```
+    """)
+    assert "--real-flag" in scan_doc(path).flags
+
+
+def test_ignore_next_line_only_skips_one_line(tmp_path):
+    path = write(tmp_path, "README.md", """
+        <!-- docdrift: ignore-next-line -->
+        Illustrative `SKIPPED_NAME` here.
+        But `REAL_NAME` here is a claim.
+    """)
+    facts = scan_doc(path)
+    assert "SKIPPED_NAME" not in facts.env
+    assert "REAL_NAME" in facts.env
+
+
+def test_suppression_keeps_line_numbers_honest(tmp_path):
+    path = write(tmp_path, "README.md", """
+        ```console docdrift-ignore
+        $ pretend
+        ```
+        Set `REAL_NAME` here.
+    """)
+    assert scan_doc(path).env["REAL_NAME"][1] == 5