api-claim-audit 0.1.0__tar.gz

api_claim_audit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 api-claim-audit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

api_claim_audit-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: api-claim-audit
+Version: 0.1.0
+Summary: Offline static audit of documented Python API claims
+Author: api-claim-audit contributors
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# api-claim-audit
+
+Offline CLI that checks a Python project's documented public API against its
+source on disk. Version 0.1.0 uses only the Python standard library (Python
+3.11+). It never imports or executes project code, accesses the network, or
+reads `.env` contents. Reports contain matched claims and rule names, never
+unrelated file contents.
+
+## Usage
+
+Install with `pip install .`, then run:
+
+```sh
+api-claim-audit .
+api-claim-audit /path/to/project --json
+api-claim-audit . --fail-on HIGH
+api-claim-audit . --ignore documented-import-missing --verbose
+api-claim-audit --version
+python -m api_claim_audit .
+```
+
+The path defaults to `.`. `--ignore RULE,...` drops named rules entirely; for
+example, ignore an import rule when documenting a symbol provided only by an
+optional extra. Unknown rules and invalid arguments are usage errors.
+
+For a package defining `greet(name)` and `Config.__init__(name="x")`, this
+README example verifies an import and a call:
+
+```python
+from pkg import greet, Config
+greet(name="Ada")
+```
+
+Changing the call to `greet(nam="Ada")` reports an unknown keyword. Documenting
+`from pkg import missing_thing` reports a missing import. Constructor keyword
+arguments are checked against `__init__`; `pkg.Config.run` checks a class method.
+Imports with aliases check the original name, and imported aliases resolve
+function and constructor calls within the same fenced example.
+
+Human output prints `SEVERITY rule file:line message` for each finding, then a
+PASS/FAIL summary. Verified claims print only with `--verbose`. `--json` returns:
+
+```json
+{"status":"PASS","findings":[],"verified_claims":[{"claim":"from pkg import greet","file":"README.md"}]}
+```
+
+Each finding has `severity`, `rule`, `file`, `line`, and `message`; findings sort
+by `(rule, file, line)`. Exit codes are **0** for PASS, **2** for FAIL, and **1**
+for usage/input errors. The default failure threshold is MEDIUM. With
+`--fail-on HIGH`, MEDIUM findings still print but do not fail.
+
+## Full rule table
+
+| Rule | Severity | Trigger |
+| --- | --- | --- |
+| `documented-import-missing` | HIGH | `from pkg[.sub] import Name` names a symbol absent from an existing module. Includes the import line and missing symbol in the message. |
+| `documented-module-missing` | HIGH | `import pkg.sub` or `from pkg.sub import ...` names a module absent on disk; a missing own top-level package uses this rule too. |
+| `documented-symbol-missing` | HIGH | `pkg[.sub].Name` is absent, or `pkg[.sub].Class.method` names a missing method. One finding per missing reference. |
+| `documented-kwarg-unknown` | MEDIUM | A resolved function or constructor call passes a keyword its signature does not accept, without a `**kwargs` catch-all. One finding per unknown keyword. Positional-only parameters are not keyword-passable. |
+| `verified_claims` | Not a finding | Resolved imports, symbols, and calls appear as claim text plus doc file in JSON; human output shows them with `--verbose`. No claims means PASS with zero verified claims. |
+
+## Scan boundaries
+
+Scans top-level `*.md` (including README.md) and recursive `docs/**/*.md`.
+Imports are claims only inside Python (`python`, `py`) or bare backtick fences,
+or inline code spans. Dotted references and calls are checked in fences only.
+Malformed import syntax is skipped. Plain prose is not a claim.
+
+Own names come from the normalized `[project].name` in pyproject.toml (lowercase,
+dashes replaced by underscores), packages containing `__init__.py` under the
+root or `src/`, and single Python modules there. Third-party names are ignored.
+Module evidence comes from Python files and package initializers. Top-level
+functions, classes, assignments, annotated assignments, and explicit
+`from ... import ...` re-exports count as symbols. Class methods come from the
+class body. Re-exports count in any module, including `__init__.py`.
+
+Tests are never evidence: `tests/`, `test_*.py`, and `*_test.py` are excluded.
+The scanner also skips `.venv`, `__pycache__`, `dist`, `.git`, `node_modules`,
+and `.egg-info` directories. Symlinks are not followed. Unparseable Python
+source produces an input error rather than a misleading missing-symbol report.
+
+## Differentiation
+
+- **readme-claim-audit** audits install names, --flags, links, versions, make
+  targets, and `python -m` paths. This tool audits documented importable symbols,
+  modules, and call signatures; there is no overlap in rules.
+- **apimirage** really imports code at runtime to check whether an API exists,
+  including LLM-hallucinated APIs. This tool is static and offline, executes
+  nothing, and checks a project's own docs against its own source.
+- **pyflakes/ruff** check names used inside code. This checks names promised
+  inside documentation.
+- **Sphinx autodoc** generates docs from code and cannot drift in that generated
+  surface. Hand-written README/docs examples can drift; this audits that drift.
+- **dep-claim-audit / privacy-claim-audit** audit dependency and privacy prose.
+  This audits API prose only, within the code formatting boundaries above.
+
+## Honest limitations
+
+Static scanning misses dynamic symbols: importlib, module `__getattr__` hooks,
+exec/eval-defined names, and symbols added by decorators at runtime. A symbol
+that exists but is not actually importable, for example behind a failing
+top-level import, still counts as present.
+
+Method checks cover only the `Class.method` dotted form. Instance calls such as
+`client.foo()` cannot be resolved statically and are skipped. Inherited methods
+and inherited constructor signatures are not inferred. Calls to functions
+accepting `**kwargs` skip keyword checks entirely. Unresolved callees are skipped
+by the keyword rule. Required arguments, argument values and types, positional
+arity, and runtime behavior are not checked. Star re-exports are not expanded.
+
+Claim detection is limited to fenced code blocks and inline code spans in docs;
+usage written as plain prose without code formatting is not checked. Inline
+spans support import claims only. Third-party imports are ignored by design.
+Examples are static evidence, not proof that code runs successfully.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+Builds produce an sdist and wheel. Tests use local temporary fixtures and no
+network. MIT licensed.

api_claim_audit-0.1.0/README.md

@@ -0,0 +1,124 @@
+# api-claim-audit
+
+Offline CLI that checks a Python project's documented public API against its
+source on disk. Version 0.1.0 uses only the Python standard library (Python
+3.11+). It never imports or executes project code, accesses the network, or
+reads `.env` contents. Reports contain matched claims and rule names, never
+unrelated file contents.
+
+## Usage
+
+Install with `pip install .`, then run:
+
+```sh
+api-claim-audit .
+api-claim-audit /path/to/project --json
+api-claim-audit . --fail-on HIGH
+api-claim-audit . --ignore documented-import-missing --verbose
+api-claim-audit --version
+python -m api_claim_audit .
+```
+
+The path defaults to `.`. `--ignore RULE,...` drops named rules entirely; for
+example, ignore an import rule when documenting a symbol provided only by an
+optional extra. Unknown rules and invalid arguments are usage errors.
+
+For a package defining `greet(name)` and `Config.__init__(name="x")`, this
+README example verifies an import and a call:
+
+```python
+from pkg import greet, Config
+greet(name="Ada")
+```
+
+Changing the call to `greet(nam="Ada")` reports an unknown keyword. Documenting
+`from pkg import missing_thing` reports a missing import. Constructor keyword
+arguments are checked against `__init__`; `pkg.Config.run` checks a class method.
+Imports with aliases check the original name, and imported aliases resolve
+function and constructor calls within the same fenced example.
+
+Human output prints `SEVERITY rule file:line message` for each finding, then a
+PASS/FAIL summary. Verified claims print only with `--verbose`. `--json` returns:
+
+```json
+{"status":"PASS","findings":[],"verified_claims":[{"claim":"from pkg import greet","file":"README.md"}]}
+```
+
+Each finding has `severity`, `rule`, `file`, `line`, and `message`; findings sort
+by `(rule, file, line)`. Exit codes are **0** for PASS, **2** for FAIL, and **1**
+for usage/input errors. The default failure threshold is MEDIUM. With
+`--fail-on HIGH`, MEDIUM findings still print but do not fail.
+
+## Full rule table
+
+| Rule | Severity | Trigger |
+| --- | --- | --- |
+| `documented-import-missing` | HIGH | `from pkg[.sub] import Name` names a symbol absent from an existing module. Includes the import line and missing symbol in the message. |
+| `documented-module-missing` | HIGH | `import pkg.sub` or `from pkg.sub import ...` names a module absent on disk; a missing own top-level package uses this rule too. |
+| `documented-symbol-missing` | HIGH | `pkg[.sub].Name` is absent, or `pkg[.sub].Class.method` names a missing method. One finding per missing reference. |
+| `documented-kwarg-unknown` | MEDIUM | A resolved function or constructor call passes a keyword its signature does not accept, without a `**kwargs` catch-all. One finding per unknown keyword. Positional-only parameters are not keyword-passable. |
+| `verified_claims` | Not a finding | Resolved imports, symbols, and calls appear as claim text plus doc file in JSON; human output shows them with `--verbose`. No claims means PASS with zero verified claims. |
+
+## Scan boundaries
+
+Scans top-level `*.md` (including README.md) and recursive `docs/**/*.md`.
+Imports are claims only inside Python (`python`, `py`) or bare backtick fences,
+or inline code spans. Dotted references and calls are checked in fences only.
+Malformed import syntax is skipped. Plain prose is not a claim.
+
+Own names come from the normalized `[project].name` in pyproject.toml (lowercase,
+dashes replaced by underscores), packages containing `__init__.py` under the
+root or `src/`, and single Python modules there. Third-party names are ignored.
+Module evidence comes from Python files and package initializers. Top-level
+functions, classes, assignments, annotated assignments, and explicit
+`from ... import ...` re-exports count as symbols. Class methods come from the
+class body. Re-exports count in any module, including `__init__.py`.
+
+Tests are never evidence: `tests/`, `test_*.py`, and `*_test.py` are excluded.
+The scanner also skips `.venv`, `__pycache__`, `dist`, `.git`, `node_modules`,
+and `.egg-info` directories. Symlinks are not followed. Unparseable Python
+source produces an input error rather than a misleading missing-symbol report.
+
+## Differentiation
+
+- **readme-claim-audit** audits install names, --flags, links, versions, make
+  targets, and `python -m` paths. This tool audits documented importable symbols,
+  modules, and call signatures; there is no overlap in rules.
+- **apimirage** really imports code at runtime to check whether an API exists,
+  including LLM-hallucinated APIs. This tool is static and offline, executes
+  nothing, and checks a project's own docs against its own source.
+- **pyflakes/ruff** check names used inside code. This checks names promised
+  inside documentation.
+- **Sphinx autodoc** generates docs from code and cannot drift in that generated
+  surface. Hand-written README/docs examples can drift; this audits that drift.
+- **dep-claim-audit / privacy-claim-audit** audit dependency and privacy prose.
+  This audits API prose only, within the code formatting boundaries above.
+
+## Honest limitations
+
+Static scanning misses dynamic symbols: importlib, module `__getattr__` hooks,
+exec/eval-defined names, and symbols added by decorators at runtime. A symbol
+that exists but is not actually importable, for example behind a failing
+top-level import, still counts as present.
+
+Method checks cover only the `Class.method` dotted form. Instance calls such as
+`client.foo()` cannot be resolved statically and are skipped. Inherited methods
+and inherited constructor signatures are not inferred. Calls to functions
+accepting `**kwargs` skip keyword checks entirely. Unresolved callees are skipped
+by the keyword rule. Required arguments, argument values and types, positional
+arity, and runtime behavior are not checked. Star re-exports are not expanded.
+
+Claim detection is limited to fenced code blocks and inline code spans in docs;
+usage written as plain prose without code formatting is not checked. Inline
+spans support import claims only. Third-party imports are ignored by design.
+Examples are static evidence, not proof that code runs successfully.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+Builds produce an sdist and wheel. Tests use local temporary fixtures and no
+network. MIT licensed.

api_claim_audit-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "api-claim-audit"
+version = "0.1.0"
+description = "Offline static audit of documented Python API claims"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "api-claim-audit contributors"}]
+dependencies = []
+
+[project.scripts]
+api-claim-audit = "api_claim_audit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

api_claim_audit-0.1.0/setup.cfg

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

api_claim_audit-0.1.0/src/api_claim_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Offline static audit of a project's documented Python API."""
+__version__ = '0.1.0'

api_claim_audit-0.1.0/src/api_claim_audit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

api_claim_audit-0.1.0/src/api_claim_audit/audit.py

@@ -0,0 +1,294 @@
+"""Static documentation API auditing; project code is never imported."""
+import ast
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+import tomllib
+
+RULES = {
+    'documented-import-missing': 'HIGH',
+    'documented-module-missing': 'HIGH',
+    'documented-symbol-missing': 'HIGH',
+    'documented-kwarg-unknown': 'MEDIUM',
+}
+SKIP = {'.venv', '__pycache__', 'dist', '.git', 'node_modules', 'tests'}
+
+
+def excluded(path):
+    return any(p in SKIP or p.endswith('.egg-info') for p in path.parts)
+
+
+@dataclass
+class Symbol:
+    keywords: set | None = None
+    catchall: bool = False
+    methods: set | None = None
+
+
+@dataclass
+class Module:
+    symbols: dict = field(default_factory=dict)
+    exports: dict = field(default_factory=dict)
+
+
+def signature(node, methods=None):
+    args = node.args
+    return Symbol({a.arg for a in args.args + args.kwonlyargs
+                   if a.arg not in {'self', 'cls'}}, args.kwarg is not None, methods)
+
+
+def index_source(root):
+    modules, own = {}, set()
+    config = root / 'pyproject.toml'
+    if config.is_file():
+        try:
+            name = tomllib.loads(config.read_text(encoding='utf-8')).get('project', {}).get('name')
+            if name:
+                own.add(name.lower().replace('-', '_'))
+        except (ValueError, OSError):
+            pass
+    for base in (root, root / 'src'):
+        if not base.is_dir():
+            continue
+        for entry in sorted(base.iterdir()):
+            if entry.is_symlink() or excluded(entry.relative_to(root)):
+                continue
+            if entry.is_file() and entry.suffix == '.py':
+                files = [entry]
+                package = entry.stem
+            elif entry.is_dir() and (entry / '__init__.py').is_file():
+                package = entry.name
+                files = []
+                for directory, dirs, names in os.walk(entry, followlinks=False):
+                    dirs[:] = sorted(d for d in dirs if not excluded(Path(d))
+                                     and not (Path(directory) / d).is_symlink())
+                    files.extend(Path(directory) / n for n in sorted(names) if n.endswith('.py'))
+            else:
+                continue
+            if package.startswith('test_') or package.endswith('_test'):
+                continue
+            own.add(package)
+            for path in files:
+                if path.is_symlink() or path.stem.startswith('test_') or path.stem.endswith('_test'):
+                    continue
+                parts = list(path.relative_to(base).with_suffix('').parts)
+                is_package = parts[-1] == '__init__'
+                if is_package:
+                    parts.pop()
+                name = '.'.join(parts)
+                module = Module()
+                modules[name] = module
+                try:
+                    tree = ast.parse(path.read_text(encoding='utf-8'))
+                except (SyntaxError, UnicodeError) as exc:
+                    raise ValueError('Cannot parse Python source: ' + str(path.relative_to(root))) from exc
+                for node in tree.body:
+                    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        module.symbols[node.name] = signature(node)
+                    elif isinstance(node, ast.ClassDef):
+                        methods = {n.name for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
+                        init = next((n for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.name == '__init__'), None)
+                        module.symbols[node.name] = signature(init, methods) if init else Symbol(set(), False, methods)
+                    elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+                        targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+                        for target in targets:
+                            for item in ast.walk(target):
+                                if isinstance(item, ast.Name):
+                                    module.symbols[item.id] = Symbol()
+                    elif isinstance(node, ast.ImportFrom):
+                        parent = parts if is_package else parts[:-1]
+                        origin = '.'.join(parent[:len(parent) - node.level + 1]) if node.level else ''
+                        origin = '.'.join(p for p in (origin, node.module) if p)
+                        for alias in node.names:
+                            if alias.name != '*':
+                                local = alias.asname or alias.name
+                                module.symbols[local] = Symbol()
+                                module.exports[local] = (origin, alias.name)
+    return own, modules
+
+
+def code_regions(text):
+    """Yield (text, first line, is fenced); preserve physical line numbers."""
+    lines = text.splitlines()
+    start, block, active, accepted, fence = 0, [], False, False, 0
+    for number, line in enumerate(lines, 1):
+        match = re.match(r'^\s*(`{3,})(.*)$', line)
+        if match:
+            ticks, info = match.groups()
+            if not active:
+                active, accepted, fence = True, info.strip() in {'', 'py', 'python'}, len(ticks)
+                start, block = number + 1, []
+            elif len(ticks) >= fence and not info.strip():
+                if accepted:
+                    yield '\n'.join(block), start, True
+                active = False
+            elif accepted:
+                block.append(line)
+        elif active:
+            if accepted:
+                block.append(line)
+        else:
+            for match in re.finditer(r'(?<!`)(`+)(?!`)(.+?)(?<!`)\1(?!`)', line):
+                yield match.group(2), number, False
+    if active and accepted:
+        yield '\n'.join(block), start, True
+
+
+def audit(path='.', fail_on='MEDIUM', ignore=()):
+    root = Path(path).resolve()
+    if not root.is_dir():
+        raise ValueError('Project path must be a directory')
+    if fail_on not in {'HIGH', 'MEDIUM'}:
+        raise ValueError('Invalid severity threshold')
+    unknown = set(ignore) - RULES.keys()
+    if unknown:
+        raise ValueError('Unknown ignored rule: ' + ', '.join(sorted(unknown)))
+    own, modules = index_source(root)
+    findings, verified = [], []
+
+    def resolve(name, seen=None):
+        seen = set() if seen is None else seen
+        if name in seen:
+            return None
+        seen.add(name)
+        mod, _, symbol = name.rpartition('.')
+        if mod in modules and symbol in modules[mod].symbols:
+            record = modules[mod]
+            if symbol in record.exports:
+                origin, original = record.exports[symbol]
+                return resolve(origin + '.' + original, seen) or record.symbols[symbol]
+            return record.symbols[symbol]
+        return None
+
+    docs = set(root.glob('*.md'))
+    docs_root = root / 'docs'
+    if docs_root.is_dir() and not docs_root.is_symlink():
+        for directory, dirs, names in os.walk(docs_root, followlinks=False):
+            dirs[:] = sorted(d for d in dirs if not excluded(Path(d)) and not (Path(directory) / d).is_symlink())
+            docs.update(Path(directory) / n for n in names if n.endswith('.md'))
+    for doc in sorted(docs):
+        if doc.is_symlink() or excluded(doc.relative_to(root)):
+            continue
+        filename = doc.relative_to(root).as_posix()
+        def good(claim):
+            item = {'claim': claim, 'file': filename}
+            if item not in verified:
+                verified.append(item)
+        def bad(rule, line, message):
+            if rule not in ignore:
+                findings.append(dict(severity=RULES[rule], rule=rule, file=filename, line=line, message=message))
+        for code, start, fenced in code_regions(doc.read_text(encoding='utf-8')):
+            aliases, import_lines = {}, set()
+            # Imports are parsed independently so a shell prompt or incomplete example
+            # elsewhere in the fence cannot conceal a valid import claim.
+            lines = code.splitlines()
+            offset = 0
+            imports = []
+            while offset < len(lines):
+                line = lines[offset]
+                if not re.match(r'^\s*(from\s|import\s)', line):
+                    offset += 1
+                    continue
+                end = offset + 1
+                while True:
+                    candidate = '\n'.join(lines[offset:end])
+                    try:
+                        tree = ast.parse(candidate.strip())
+                    except SyntaxError:
+                        # Continue only an explicitly continued import, not
+                        # arbitrary subsequent example lines.
+                        if end < len(lines) and (candidate.rstrip().endswith('\\') or
+                                                 candidate.count('(') > candidate.count(')')):
+                            end += 1
+                            continue
+                        tree = None
+                    break
+                import_lines.update(range(offset + 1, end + 1))
+                if tree is not None and tree.body and all(isinstance(n, (ast.Import, ast.ImportFrom)) for n in tree.body):
+                    imports.append((offset, candidate, tree))
+                offset = end
+            for offset, line, tree in imports:
+                line = ' '.join(line.split())
+                for node in tree.body:
+                    if isinstance(node, ast.ImportFrom):
+                        module = node.module or ''
+                        if node.level or module.split('.')[0] not in own:
+                            continue
+                        if module not in modules:
+                            bad('documented-module-missing', start + offset, line.strip() + ': missing module ' + module)
+                            continue
+                        for alias in node.names:
+                            if alias.name == '*':
+                                continue
+                            aliases[alias.asname or alias.name] = module + '.' + alias.name
+                            if alias.name not in modules[module].symbols:
+                                bad('documented-import-missing', start + offset, line.strip() + ': missing symbol ' + alias.name)
+                            else:
+                                good('from ' + module + ' import ' + alias.name)
+                    else:
+                        for alias in node.names:
+                            if alias.name.split('.')[0] not in own:
+                                continue
+                            aliases[alias.asname or alias.name.split('.')[0]] = alias.name if alias.asname else alias.name.split('.')[0]
+                            if alias.name not in modules:
+                                bad('documented-module-missing', start + offset, line.strip() + ': missing module ' + alias.name)
+                            else:
+                                good('import ' + alias.name)
+            if not fenced:
+                continue
+            for offset, line in enumerate(code.splitlines()):
+                if offset + 1 in import_lines:
+                    continue
+                for match in re.finditer(r'\b[A-Za-z_][\w]*(?:\.[A-Za-z_][\w]*)+', line):
+                    reference = match.group()
+                    parts = reference.split('.')
+                    if parts[0] not in own:
+                        continue
+                    valid = reference in modules or resolve(reference) is not None
+                    if not valid and len(parts) >= 3:
+                        cls = resolve('.'.join(parts[:-1]))
+                        valid = cls is not None and cls.methods is not None and parts[-1] in cls.methods
+                    if valid:
+                        good(reference)
+                    else:
+                        bad('documented-symbol-missing', start + offset, 'Missing documented reference ' + reference)
+            try:
+                tree = ast.parse(code)
+            except SyntaxError:
+                # Recover individually valid lines in incomplete snippets.
+                tree = ast.Module(body=[], type_ignores=[])
+                for offset, line in enumerate(code.splitlines()):
+                    try:
+                        part = ast.parse(line.strip())
+                    except SyntaxError:
+                        continue
+                    ast.increment_lineno(part, offset)
+                    tree.body.extend(part.body)
+            for node in ast.walk(tree):
+                if not isinstance(node, ast.Call):
+                    continue
+                def dotted(expr):
+                    if isinstance(expr, ast.Name):
+                        return expr.id
+                    if isinstance(expr, ast.Attribute):
+                        parent = dotted(expr.value)
+                        return parent + '.' + expr.attr if parent else ''
+                    return ''
+                callee = dotted(node.func)
+                first, dot, tail = callee.partition('.')
+                expanded = aliases.get(first, first) + (dot + tail if dot else '')
+                if expanded.split('.')[0] not in own:
+                    continue
+                symbol = resolve(expanded)
+                if symbol is None or symbol.keywords is None:
+                    continue
+                invalid = [] if symbol.catchall else [k.arg for k in node.keywords if k.arg is not None and k.arg not in symbol.keywords]
+                for keyword in invalid:
+                    bad('documented-kwarg-unknown', start + node.lineno - 1, callee + ': unknown keyword ' + keyword)
+                if not invalid:
+                    good(ast.get_source_segment(code, node) or callee + '(...)')
+    findings.sort(key=lambda f: (f['rule'], f['file'], f['line']))
+    verified.sort(key=lambda v: (v['file'], v['claim']))
+    failed = any(f['severity'] == 'HIGH' or fail_on == 'MEDIUM' for f in findings)
+    return {'status': 'FAIL' if failed else 'PASS', 'findings': findings, 'verified_claims': verified}

api_claim_audit-0.1.0/src/api_claim_audit/cli.py

@@ -0,0 +1,37 @@
+"""Command line interface."""
+import argparse
+import json
+import sys
+from . import __version__
+from .audit import audit
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(1, self.prog + ': error: ' + message + '\n')
+
+
+def main(argv=None):
+    parser = Parser(prog='api-claim-audit', description='Audit documented Python API claims without executing project code.')
+    parser.add_argument('path', nargs='?', default='.')
+    parser.add_argument('--json', action='store_true')
+    parser.add_argument('--fail-on', choices=['HIGH', 'MEDIUM'], default='MEDIUM')
+    parser.add_argument('--ignore', default='', metavar='RULE,...')
+    parser.add_argument('--verbose', action='store_true')
+    parser.add_argument('--version', action='version', version=__version__)
+    args = parser.parse_args(argv)
+    try:
+        result = audit(args.path, args.fail_on, [r.strip() for r in args.ignore.split(',') if r.strip()])
+    except (ValueError, OSError, UnicodeError) as exc:
+        parser.error(str(exc))
+    if args.json:
+        print(json.dumps(result, ensure_ascii=True))
+    else:
+        for item in result['findings']:
+            print('{severity} {rule} {file}:{line} {message}'.format(**item))
+        if args.verbose:
+            for item in result['verified_claims']:
+                print('VERIFIED {file} {claim}'.format(**item))
+        print(result['status'] + ': ' + str(len(result['findings'])) + ' finding(s)')
+    return 2 if result['status'] == 'FAIL' else 0

api_claim_audit-0.1.0/src/api_claim_audit.egg-info/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: api-claim-audit
+Version: 0.1.0
+Summary: Offline static audit of documented Python API claims
+Author: api-claim-audit contributors
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# api-claim-audit
+
+Offline CLI that checks a Python project's documented public API against its
+source on disk. Version 0.1.0 uses only the Python standard library (Python
+3.11+). It never imports or executes project code, accesses the network, or
+reads `.env` contents. Reports contain matched claims and rule names, never
+unrelated file contents.
+
+## Usage
+
+Install with `pip install .`, then run:
+
+```sh
+api-claim-audit .
+api-claim-audit /path/to/project --json
+api-claim-audit . --fail-on HIGH
+api-claim-audit . --ignore documented-import-missing --verbose
+api-claim-audit --version
+python -m api_claim_audit .
+```
+
+The path defaults to `.`. `--ignore RULE,...` drops named rules entirely; for
+example, ignore an import rule when documenting a symbol provided only by an
+optional extra. Unknown rules and invalid arguments are usage errors.
+
+For a package defining `greet(name)` and `Config.__init__(name="x")`, this
+README example verifies an import and a call:
+
+```python
+from pkg import greet, Config
+greet(name="Ada")
+```
+
+Changing the call to `greet(nam="Ada")` reports an unknown keyword. Documenting
+`from pkg import missing_thing` reports a missing import. Constructor keyword
+arguments are checked against `__init__`; `pkg.Config.run` checks a class method.
+Imports with aliases check the original name, and imported aliases resolve
+function and constructor calls within the same fenced example.
+
+Human output prints `SEVERITY rule file:line message` for each finding, then a
+PASS/FAIL summary. Verified claims print only with `--verbose`. `--json` returns:
+
+```json
+{"status":"PASS","findings":[],"verified_claims":[{"claim":"from pkg import greet","file":"README.md"}]}
+```
+
+Each finding has `severity`, `rule`, `file`, `line`, and `message`; findings sort
+by `(rule, file, line)`. Exit codes are **0** for PASS, **2** for FAIL, and **1**
+for usage/input errors. The default failure threshold is MEDIUM. With
+`--fail-on HIGH`, MEDIUM findings still print but do not fail.
+
+## Full rule table
+
+| Rule | Severity | Trigger |
+| --- | --- | --- |
+| `documented-import-missing` | HIGH | `from pkg[.sub] import Name` names a symbol absent from an existing module. Includes the import line and missing symbol in the message. |
+| `documented-module-missing` | HIGH | `import pkg.sub` or `from pkg.sub import ...` names a module absent on disk; a missing own top-level package uses this rule too. |
+| `documented-symbol-missing` | HIGH | `pkg[.sub].Name` is absent, or `pkg[.sub].Class.method` names a missing method. One finding per missing reference. |
+| `documented-kwarg-unknown` | MEDIUM | A resolved function or constructor call passes a keyword its signature does not accept, without a `**kwargs` catch-all. One finding per unknown keyword. Positional-only parameters are not keyword-passable. |
+| `verified_claims` | Not a finding | Resolved imports, symbols, and calls appear as claim text plus doc file in JSON; human output shows them with `--verbose`. No claims means PASS with zero verified claims. |
+
+## Scan boundaries
+
+Scans top-level `*.md` (including README.md) and recursive `docs/**/*.md`.
+Imports are claims only inside Python (`python`, `py`) or bare backtick fences,
+or inline code spans. Dotted references and calls are checked in fences only.
+Malformed import syntax is skipped. Plain prose is not a claim.
+
+Own names come from the normalized `[project].name` in pyproject.toml (lowercase,
+dashes replaced by underscores), packages containing `__init__.py` under the
+root or `src/`, and single Python modules there. Third-party names are ignored.
+Module evidence comes from Python files and package initializers. Top-level
+functions, classes, assignments, annotated assignments, and explicit
+`from ... import ...` re-exports count as symbols. Class methods come from the
+class body. Re-exports count in any module, including `__init__.py`.
+
+Tests are never evidence: `tests/`, `test_*.py`, and `*_test.py` are excluded.
+The scanner also skips `.venv`, `__pycache__`, `dist`, `.git`, `node_modules`,
+and `.egg-info` directories. Symlinks are not followed. Unparseable Python
+source produces an input error rather than a misleading missing-symbol report.
+
+## Differentiation
+
+- **readme-claim-audit** audits install names, --flags, links, versions, make
+  targets, and `python -m` paths. This tool audits documented importable symbols,
+  modules, and call signatures; there is no overlap in rules.
+- **apimirage** really imports code at runtime to check whether an API exists,
+  including LLM-hallucinated APIs. This tool is static and offline, executes
+  nothing, and checks a project's own docs against its own source.
+- **pyflakes/ruff** check names used inside code. This checks names promised
+  inside documentation.
+- **Sphinx autodoc** generates docs from code and cannot drift in that generated
+  surface. Hand-written README/docs examples can drift; this audits that drift.
+- **dep-claim-audit / privacy-claim-audit** audit dependency and privacy prose.
+  This audits API prose only, within the code formatting boundaries above.
+
+## Honest limitations
+
+Static scanning misses dynamic symbols: importlib, module `__getattr__` hooks,
+exec/eval-defined names, and symbols added by decorators at runtime. A symbol
+that exists but is not actually importable, for example behind a failing
+top-level import, still counts as present.
+
+Method checks cover only the `Class.method` dotted form. Instance calls such as
+`client.foo()` cannot be resolved statically and are skipped. Inherited methods
+and inherited constructor signatures are not inferred. Calls to functions
+accepting `**kwargs` skip keyword checks entirely. Unresolved callees are skipped
+by the keyword rule. Required arguments, argument values and types, positional
+arity, and runtime behavior are not checked. Star re-exports are not expanded.
+
+Claim detection is limited to fenced code blocks and inline code spans in docs;
+usage written as plain prose without code formatting is not checked. Inline
+spans support import claims only. Third-party imports are ignored by design.
+Examples are static evidence, not proof that code runs successfully.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+Builds produce an sdist and wheel. Tests use local temporary fixtures and no
+network. MIT licensed.

api_claim_audit-0.1.0/src/api_claim_audit.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/api_claim_audit/__init__.py
+src/api_claim_audit/__main__.py
+src/api_claim_audit/audit.py
+src/api_claim_audit/cli.py
+src/api_claim_audit.egg-info/PKG-INFO
+src/api_claim_audit.egg-info/SOURCES.txt
+src/api_claim_audit.egg-info/dependency_links.txt
+src/api_claim_audit.egg-info/entry_points.txt
+src/api_claim_audit.egg-info/top_level.txt
+tests/test_audit.py

api_claim_audit-0.1.0/src/api_claim_audit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

api_claim_audit-0.1.0/src/api_claim_audit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+api-claim-audit = api_claim_audit.cli:main

api_claim_audit-0.1.0/src/api_claim_audit.egg-info/top_level.txt

@@ -0,0 +1 @@
+api_claim_audit

api_claim_audit-0.1.0/tests/test_audit.py

@@ -0,0 +1,269 @@
+import contextlib
+import io
+import json
+from pathlib import Path
+import tempfile
+import unittest
+from api_claim_audit.audit import audit
+from api_claim_audit.cli import main
+
+SOURCE = '''def greet(name, *, punctuation="!"):
+    return name + punctuation
+class Config:
+    def __init__(self, name="x"):
+        self.name = name
+    def run(self):
+        pass
+VALUE = 1
+ANNOTATED: int = 2
+async def async_greet(name):
+    pass
+def flexible(**kwargs):
+    pass
+def positional(name, /, *, option=1):
+    pass
+'''
+
+
+class AuditTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        self.write('src/pkg/__init__.py', SOURCE)
+
+    def write(self, name, text):
+        path = self.root / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding='utf-8')
+
+    def document(self, code, language='python', name='README.md'):
+        self.write(name, 'Intro\n```' + language + '\n' + code + '\n```\n')
+
+    def run_cli(self, *args):
+        out, err = io.StringIO(), io.StringIO()
+        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            try:
+                status = main([str(self.root), *args])
+            except SystemExit as exc:
+                status = exc.code
+        return status, out.getvalue(), err.getvalue()
+
+    def test_good_fixture(self):
+        self.document('from pkg import greet, Config\npkg.Config.run(...)\ngreet(name="x")')
+        status, output, _ = self.run_cli('--json')
+        self.assertEqual(status, 0)
+        result = json.loads(output)
+        self.assertEqual(result['findings'], [])
+        self.assertIn({'claim': 'from pkg import greet', 'file': 'README.md'}, result['verified_claims'])
+
+    def test_bad_import_exact(self):
+        self.document('from pkg import missing_thing')
+        self.assertEqual([x['rule'] for x in audit(self.root)['findings']], ['documented-import-missing'])
+        self.assertEqual(self.run_cli()[0], 2)
+
+    def test_bad_module_exact(self):
+        self.document('from pkg.nosuch import thing')
+        self.assertEqual([x['rule'] for x in audit(self.root)['findings']], ['documented-module-missing'])
+
+    def test_bad_symbols(self):
+        self.document('pkg.Nope\npkg.Config.nomethod')
+        self.assertEqual([x['rule'] for x in audit(self.root)['findings']], ['documented-symbol-missing'] * 2)
+
+    def test_bad_kwargs_exact(self):
+        self.document('from pkg import greet, Config\ngreet(nam="x")\nConfig(timeout=5)')
+        self.assertEqual([x['rule'] for x in audit(self.root)['findings']], ['documented-kwarg-unknown'] * 2)
+
+    def test_reexport_signature(self):
+        self.write('src/pkg/core.py', SOURCE)
+        self.write('src/pkg/__init__.py', 'from .core import greet')
+        self.document('from pkg import greet\ngreet(nam="x")')
+        self.assertEqual(audit(self.root)['findings'][0]['rule'], 'documented-kwarg-unknown')
+
+    def test_test_only(self):
+        self.write('tests/helpers.py', 'def missing_thing(): pass')
+        self.document('from pkg import missing_thing')
+        self.assertEqual(audit(self.root)['findings'][0]['rule'], 'documented-import-missing')
+
+    def test_ignore(self):
+        self.document('from pkg import missing')
+        status, output, _ = self.run_cli('--ignore', 'documented-import-missing', '--json')
+        self.assertEqual(status, 0)
+        self.assertEqual(json.loads(output)['findings'], [])
+
+    def test_high_threshold(self):
+        self.document('pkg.greet(nam="x")')
+        status, output, _ = self.run_cli('--fail-on', 'HIGH', '--json')
+        self.assertEqual(status, 0)
+        self.assertEqual(len(json.loads(output)['findings']), 1)
+
+    def test_medium_default(self):
+        self.document('pkg.greet(nam="x")')
+        self.assertEqual(self.run_cli()[0], 2)
+
+    def test_sorting(self):
+        self.document('pkg.Nope\npkg.greet(nam=1)\nfrom pkg import absent')
+        self.document('pkg.Other', name='docs/nested/a.md')
+        result = audit(self.root)
+        self.assertEqual(result['findings'], sorted(result['findings'], key=lambda f: (f['rule'], f['file'], f['line'])))
+        self.assertEqual(result, audit(self.root))
+
+    def test_line_numbers(self):
+        self.document('pkg.Nope\nfrom pkg import missing')
+        found = audit(self.root)['findings']
+        self.assertEqual({f['line'] for f in found}, {3, 4})
+        self.assertTrue(all(f['file'] == 'README.md' for f in found))
+
+    def test_verbose(self):
+        self.document('from pkg import greet')
+        self.assertNotIn('VERIFIED', self.run_cli()[1])
+        self.assertIn('VERIFIED', self.run_cli('--verbose')[1])
+
+    def test_version(self):
+        self.assertEqual(self.run_cli('--version')[:2], (0, '0.1.0\n'))
+
+    def test_invalid_option(self):
+        self.assertEqual(self.run_cli('--unknown')[0], 1)
+
+    def test_invalid_threshold(self):
+        self.assertEqual(self.run_cli('--fail-on', 'LOW')[0], 1)
+
+    def test_invalid_ignore(self):
+        self.assertEqual(self.run_cli('--ignore', 'typo')[0], 1)
+
+    def test_invalid_path(self):
+        with self.assertRaises(ValueError):
+            audit(self.root / 'absent')
+
+    def test_no_execution(self):
+        self.write('src/pkg/__init__.py', 'raise RuntimeError("never execute")\n' + SOURCE)
+        self.document('from pkg import greet')
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+    def test_no_env_read(self):
+        (self.root / '.env').write_bytes(b'\xff\x00')
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+    def test_root_package(self):
+        self.write('other/__init__.py', 'def fn(x): pass')
+        self.document('other.fn(typo=1)')
+        self.assertEqual(audit(self.root)['findings'][0]['rule'], 'documented-kwarg-unknown')
+
+    def test_single_module(self):
+        self.write('single.py', 'VALUE = 1')
+        self.document('from single import VALUE')
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+    def test_normalized_project_name_missing(self):
+        self.write('pyproject.toml', '[project]\nname = "Absent-Pkg"')
+        self.document('import absent_pkg')
+        self.assertEqual(audit(self.root)['findings'][0]['rule'], 'documented-module-missing')
+
+    def test_nested_module(self):
+        self.write('src/pkg/sub/__init__.py', '')
+        self.write('src/pkg/sub/core.py', 'def hello(x): pass')
+        self.document('import pkg.sub.core\npkg.sub.core.hello(x=1)')
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+    def test_test_files_excluded(self):
+        for name in ['test_hidden.py', 'hidden_test.py', 'tests/helper.py']:
+            self.write('src/pkg/' + name, 'def hidden(): pass')
+        self.document('import pkg.test_hidden\nimport pkg.hidden_test\nimport pkg.tests.helper')
+        self.assertEqual(len(audit(self.root)['findings']), 3)
+
+    def test_excluded_directories(self):
+        for name in ['.venv', 'dist', '.git', '__pycache__', 'x.egg-info', 'node_modules']:
+            self.write('src/pkg/' + name + '/bad.py', 'invalid source !!!')
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+    def test_symlink_not_followed(self):
+        (self.root / 'src/pkg/loop').symlink_to(self.root, target_is_directory=True)
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+    def test_invalid_source_error(self):
+        self.write('src/pkg/bad.py', 'invalid syntax !!!')
+        self.assertEqual(self.run_cli()[0], 1)
+
+    def test_inline_only_imports(self):
+        self.write('README.md', '`from pkg import absent` and `pkg.Nope`')
+        self.assertEqual([f['rule'] for f in audit(self.root)['findings']], ['documented-import-missing'])
+
+    def test_non_docs_ignored(self):
+        self.write('other/note.md', '```python\npkg.Nope\n```')
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+    def test_reexport_cycle(self):
+        self.write('src/pkg/a.py', 'from .b import x')
+        self.write('src/pkg/b.py', 'from .a import x')
+        self.document('from pkg.a import x')
+        self.assertEqual(audit(self.root)['status'], 'PASS')
+
+
+CASES = [
+    ('multiline_import', 'from pkg import (\n    greet,\n    Config,\n)', None),
+    ('multiline_import_bad', 'from pkg import (\n    absent,\n)', 'documented-import-missing'),
+    ('third_party', 'from requests import get\nrequests.get(url="x")', None),
+    ('catchall', 'pkg.flexible(arbitrary=1)', None),
+    ('no_kwargs', 'pkg.greet()', None),
+    ('unknown_call', 'unknown(nam=1)', None),
+    ('unresolved_call', 'pkg.unknown(nam=1)', 'documented-symbol-missing'),
+    ('import_alias', 'from pkg import greet as hello\nhello(name="x")', None),
+    ('import_alias_bad', 'from pkg import greet as hello\nhello(nam="x")', 'documented-kwarg-unknown'),
+    ('module_alias', 'import pkg as p\np.greet(nam="x")', 'documented-kwarg-unknown'),
+    ('import_module', 'import pkg', None),
+    ('missing_import_module', 'import pkg.absent as p', 'documented-module-missing'),
+    ('class_symbol', 'pkg.Config', None),
+    ('method_exists', 'pkg.Config.run()', None),
+    ('assignment', 'pkg.VALUE', None),
+    ('annotated_assignment', 'pkg.ANNOTATED', None),
+    ('async_signature', 'pkg.async_greet(nam=1)', 'documented-kwarg-unknown'),
+    ('positional_only', 'pkg.positional(name="x")', 'documented-kwarg-unknown'),
+    ('keyword_only', 'pkg.positional(option=1)', None),
+    ('malformed_dotted_import', 'from pkg.nosuch import ???', None),
+    ('malformed_import', 'from pkg import ???', None),
+    ('star_import', 'from pkg import *', None),
+    ('instance_method', 'client.foo(timeout=1)', None),
+    ('expanded_kwargs', 'pkg.greet(**options)', None),
+    ('multiline_call', 'pkg.greet(\n    nam="x",\n)', 'documented-kwarg-unknown'),
+    ('repeated_reference', 'pkg.Nope; pkg.Nope', 'documented-symbol-missing'),
+]
+
+
+def make_case(code, rule):
+    def test(self):
+        self.document(code)
+        result = audit(self.root)
+        self.assertEqual(result['status'], 'FAIL' if rule else 'PASS')
+        self.assertEqual({f['rule'] for f in result['findings']}, {rule} if rule else set())
+    return test
+
+
+for name, code, rule in CASES:
+    setattr(AuditTests, 'test_case_' + name, make_case(code, rule))
+
+
+def make_markdown(text, count):
+    def test(self):
+        self.write('README.md', text)
+        result = audit(self.root)
+        self.assertEqual(len(result['findings']), count)
+        if not count:
+            self.assertEqual(result['verified_claims'], [])
+    return test
+
+
+for name, text, count in [
+    ('prose', 'pkg.Nope is mentioned in prose.', 0),
+    ('empty', '# Command line\nUse the CLI.', 0),
+    ('py_fence', '```py\npkg.Nope\n```', 1),
+    ('bare_fence', '```\npkg.Nope\n```', 1),
+    ('other_fence', '```javascript\npkg.Nope\n```', 0),
+    ('inline_import', 'Use `from pkg import missing`.', 1),
+    ('plain_import', 'from pkg import missing', 0),
+    ('inline_third_party', '`from requests import get`', 0),
+]:
+    setattr(AuditTests, 'test_markdown_' + name, make_markdown(text, count))
+
+
+if __name__ == '__main__':
+    unittest.main()