cache-claim-audit

Offline-audit of documented cache-reuse promises against Python source.

Version 0.1.0. Python 3.9 or later; standard library only at runtime. This tool compares documentation promises with static source evidence. It executes no audited code, imports no audited modules, makes no network requests, and never opens .env contents. Symlink files and directories are skipped.

Usage

Install a locally built distribution and run either entry point:

python3 -m pip install dist/cache_claim_audit-0.1.0-py3-none-any.whl
cache-claim-audit /path/to/project
python3 -m cache_claim_audit /path/to/project --json
cache-claim-audit /path/to/project --verbose
cache-claim-audit /path/to/project --ignore 'vendor/*' --ignore 'generated/*'
cache-claim-audit /path/to/project --fail-on HIGH
cache-claim-audit --version

The positional directory defaults to the current directory. --json emits a single JSON object with findings, verified_claims, claims, production_evidence, test_only_evidence, production_source_count, warnings, and version. Findings contain rule, severity, family, claims, and evidence. Claims record relative path, line, and sentence text; evidence records relative path, line, and kind (or just kind: no-source). --verbose adds scan details in text mode; JSON always contains these details.

Exit codes: 0 PASS, 2 FAIL, 1 usage/path error. Default --fail-on MEDIUM fails for any finding. --fail-on HIGH still prints MEDIUM findings but returns 0 for a MEDIUM-only report. --ignore is repeatable and uses case-sensitive glob matching against slash-separated relative paths and their directory ancestors; quote globs to prevent shell expansion.

Claim extraction

Only root README.md and docs/**/*.md supply claims. Backtick and tilde fenced blocks are excluded; inline code spans count as prose. Matching ignores case and normalizes whitespace in sentences, including wrapped lines. These are the complete phrase tables; no optional middle words or extra hyphen variants are accepted:

cached family:
  cached (whole word), caching (whole word)
  uses a cache, use a cache, with a cache, with caching
  result cache, response cache

no-cache family:
  no caching, no cache, does not cache, doesn't cache, never caches
  not cached, uncached, without caching, without a cache, no memoization

The spec also explicitly identifies "does not use a cache" as a no-cache claim.

Negation asymmetry is intentional: a sentence containing no, not, never, without, doesn't, don't, or isn't suppresses the positive family only. The reverse family uses negation as its claim phrasing, so it is still counted. This differs from R26/R27, which suppressed negation-phrased reverse claims. A bare cache noun is not a claim: path names, settings, and instructions such as clear the cache directory do not promise reuse. Multiple phrases collapse to one finding per family, while retaining all claim locations.

Rules

No production Python source overrides these conditions: each documented family gets one HIGH finding with no-source evidence. Contradictory families are audited independently; both can fail when there is no source. Otherwise, positive claims with production evidence are verified, and reverse claims with no evidence anywhere are verified. No claim means PASS even if evidence exists. All relevant evidence sites are listed in each finding.

Named evidence table

Evidence is deduplicated by relative file, line, and kind. Production excludes tests/, fixtures/, test_*.py, *_test.py, docs/, and examples/. Test and fixture evidence is collected separately, while docs and examples are excluded entirely as source. Symlink files/directories are skipped. Repository metadata, virtual environments, build output, and bytecode folders are also skipped.

Differentiation

Honest limitations

This is static, project-wide evidence, not proof of runtime hits, correct invalidation, scope, capacity, expiry, or reuse by the documented operation. Exact phrase matching misses paraphrases, other languages, and non-Markdown docs. Sentence splitting is punctuation-based and does not interpret natural language, abbreviations, Markdown tables, or scoped promises semantically.

Unused imports count intentionally: the four named library imports are an over-approximation. Dead code counts too, including primitives in uncalled functions. Bare import functools does not count. Only the stdlib-plus-named evidence table above is supported; other third-party libraries and dynamic alias resolution are out of scope. Disk store calls require the listed exact qualified names and a literal filename, not computed paths.

Dict stores require a write site: a bare read such as cache[key] or cache.get(key) alone does not count, even if the variable name suggests reuse. A store that is only cleared, including cache_clear() without a decorator or write, does not count. HTTP Cache-Control headers and ETag handling alone do not count: they are protocol behaviour rather than local reuse evidence. Subscript stores and name-based heuristics may also match unrelated objects.

Unreadable, non-UTF-8, or syntactically invalid source is skipped with a warning in JSON/verbose output; its production file still counts as source. Review warnings before relying on verified claims. No dependency inspection or source execution occurs. .env contents are never read; a marker-only fixture and an open guard test pin this behaviour.

Build and test

PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 -m build

The standard build uses isolation. If build dependencies are unavailable offline, with setuptools and wheel already installed, use:

python3 -m build --no-isolation

Artifacts are a wheel and sdist in dist/. MANIFEST.in includes tests and all fixtures in the sdist. Each of the good fixtures exits 0; each bad fixture exits 2 with one HIGH finding; the test-only fixture has one MEDIUM finding and exits 0 under --fail-on HIGH.

PYTHONPATH=src python3 -m cache_claim_audit tests/fixtures/good/cached --json
PYTHONPATH=src python3 -m cache_claim_audit tests/fixtures/good/nocache --json
PYTHONPATH=src python3 -m cache_claim_audit tests/fixtures/bad/cached --json
PYTHONPATH=src python3 -m cache_claim_audit tests/fixtures/bad/nocache --json
PYTHONPATH=src python3 -m cache_claim_audit tests/fixtures/testonly --fail-on HIGH --json

MIT licensed. This project is intended for local use.