recursion-claim-audit 0.1.0__py3-none-any.whl

recursion_claim_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Audit documented directory traversal depth against Python source."""
+__version__ = '0.1.0'

recursion_claim_audit/__main__.py

@@ -0,0 +1,44 @@
+"""Command line interface."""
+import argparse
+import json
+from pathlib import Path
+from . import __version__
+from .audit import audit
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(__import__('sys').stderr)
+        self.exit(1, self.prog + ': error: ' + message + '\n')
+
+
+def main(argv=None):
+    parser = Parser(description='Audit documented directory traversal depth against Python source.')
+    parser.add_argument('path', nargs='?', default='.')
+    parser.add_argument('--json', action='store_true')
+    parser.add_argument('--verbose', action='store_true')
+    parser.add_argument('--ignore', action='append', default=[], metavar='GLOB')
+    parser.add_argument('--fail-on', choices=['MEDIUM', 'HIGH'], default='MEDIUM')
+    parser.add_argument('--version', action='version', version=__version__)
+    args = parser.parse_args(argv)
+    if not Path(args.path).is_dir():
+        parser.error('path must be an existing directory')
+    result = audit(args.path, args.ignore)
+    failed = any(f['severity'] == 'HIGH' or args.fail_on == 'MEDIUM' for f in result['findings'])
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print('FAIL' if failed else 'PASS')
+        for finding in result['findings']:
+            print(finding['severity'] + ' ' + finding['rule'])
+            for claim in finding['claims']:
+                print('  {path}:{line}: {text}'.format(**claim))
+            for evidence in finding['evidence']:
+                print('  ' + json.dumps(evidence, sort_keys=True))
+        if args.verbose:
+            print(json.dumps(dict(verified_claims=result['verified_claims'], errors=result['errors']), indent=2))
+    return 2 if failed else 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

recursion_claim_audit/audit.py

@@ -0,0 +1,181 @@
+"""Offline documentation and directory-descent analysis."""
+import ast
+import fnmatch
+import re
+from pathlib import Path
+
+RECURSIVE = ('recursively', 'recursive scan', 'recursive search', 'recursively scans',
+             'scans recursively', 'searches recursively', 'recursively searches',
+             'walks the tree', 'walks the directory tree', 'recursive traversal',
+             'traverses recursively', 'recursively walks', 'descends into subdirectories',
+             'all subdirectories', 'including subdirectories', 'nested directories')
+SHALLOW_NEG = ('not recursive', 'does not recurse', "doesn't recurse", 'no recursion',
+               'without recursion', 'does not descend', "doesn't descend")
+SHALLOW = ('top-level only', 'top level only', 'non-recursive', 'single directory',
+           'shallow scan', 'flat scan') + SHALLOW_NEG
+NEGATION = re.compile(r"\b(?:no|not|never|without|doesn't|don't|isn't)\b", re.I)
+
+
+def contains(sentence, phrase):
+    return re.search(r'(?<![\w-])' + re.escape(phrase) + r'(?![\w-])', sentence, re.I) is not None
+
+
+def extract_claims(text, path='README.md'):
+    claims = []
+    fence = None
+    paragraph = []
+
+    def flush():
+        if not paragraph:
+            return
+        joined = ' '.join(line for _, line in paragraph)
+        offsets = []
+        for number, line in paragraph:
+            offsets.extend([number] * (len(line) + 1))
+        for match in re.finditer(r'.+?(?:[.!?](?=\s|$)|$)', joined):
+            sentence = match.group().strip()
+            negated = bool(NEGATION.search(sentence))
+            for family, phrases in [('recursive', RECURSIVE), ('shallow', SHALLOW)]:
+                hits = [p for p in phrases if contains(sentence, p)
+                        and (not negated or (family == 'shallow' and p in SHALLOW_NEG))]
+                if hits:
+                    start = match.start() + len(match.group()) - len(match.group().lstrip())
+                    claims.append(dict(family=family, path=path, line=offsets[start],
+                                       text=sentence))
+        paragraph.clear()
+
+    for number, line in enumerate(text.splitlines(), 1):
+        mark = re.match(r'^\s{0,3}(`{3,}|~{3,})', line)
+        if mark:
+            token = mark.group(1)
+            if fence is None:
+                flush()
+                fence = token
+            elif token[0] == fence[0] and len(token) >= len(fence):
+                fence = None
+            continue
+        if fence:
+            continue
+        if not line.strip():
+            flush()
+        else:
+            paragraph.append((number, line))
+    flush()
+    return claims
+
+
+def dotted(node):
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return dotted(node.value) + '.' + node.attr
+    return ''
+
+
+def extract_evidence(source, path):
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError) as exc:
+        return [], str(exc)
+    aliases = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for item in node.names:
+                aliases[item.asname or item.name] = item.name
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            for item in node.names:
+                aliases[item.asname or item.name] = node.module + '.' + item.name
+
+    def name(call):
+        parts = dotted(call.func).split('.')
+        return '.'.join([aliases.get(parts[0], parts[0])] + parts[1:])
+
+    items = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            target = name(node)
+            attr = node.func.attr if isinstance(node.func, ast.Attribute) else None
+            kind = None
+            if target in ('os.walk', 'os.path.walk'):
+                kind = target
+            elif attr == 'rglob':
+                kind = 'rglob'
+            elif target == 'glob.glob' and any(k.arg == 'recursive' and
+                    isinstance(k.value, ast.Constant) and k.value.value is True for k in node.keywords):
+                kind = 'recursive-glob'
+            elif (target == 'glob.glob' or attr == 'glob') and node.args and isinstance(node.args[0], ast.Constant) and isinstance(node.args[0].value, str) and '**' in node.args[0].value:
+                kind = 'glob-pattern'
+            if kind:
+                items.add((node.lineno, kind))
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # Nested definitions are separate scopes, not part of this reader.
+            def body_nodes(root):
+                for child in ast.iter_child_nodes(root):
+                    if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)):
+                        continue
+                    yield child
+                    yield from body_nodes(child)
+            calls = [n for n in body_nodes(node) if isinstance(n, ast.Call)]
+            self_call = any(isinstance(c.func, ast.Name) and c.func.id == node.name for c in calls)
+            reader = any(name(c) in ('os.listdir', 'os.scandir') or
+                         (isinstance(c.func, ast.Attribute) and c.func.attr == 'iterdir') for c in calls)
+            if self_call and reader:
+                items.add((node.lineno, 'self-recursive-reader'))
+    return [dict(path=path, line=line, kind=kind) for line, kind in sorted(items)], None
+
+
+def audit(root, ignore=()):
+    root = Path(root)
+    claims, production, testonly, errors = [], [], [], []
+    source_count = 0
+    # Do not follow directory symlinks, or open non-source files (including .env).
+    import os
+    for directory, dirs, files in os.walk(root, followlinks=False):
+        dirs[:] = sorted(d for d in dirs if not (Path(directory) / d).is_symlink()
+                         and d not in ('.git', '__pycache__', '.venv', 'venv', 'build', 'dist')
+                         and not any(fnmatch.fnmatch((Path(directory) / d).relative_to(root).as_posix(), p) for p in ignore))
+        for filename in sorted(files):
+            file = Path(directory) / filename
+            relative = file.relative_to(root).as_posix()
+            if file.is_symlink() or any(fnmatch.fnmatch(relative, p) for p in ignore):
+                continue
+            parts = file.relative_to(root).parts
+            is_doc = relative == 'README.md' or (parts[0] == 'docs' and file.suffix == '.md')
+            is_test = any(p in ('tests', 'fixtures') for p in parts[:-1]) or filename.startswith('test_') or filename.endswith('_test.py')
+            is_source = file.suffix == '.py' and not any(p in ('docs', 'examples') for p in parts[:-1])
+            if not (is_doc or is_source):
+                continue
+            if is_source and not is_test:
+                source_count += 1
+            try:
+                text = file.read_text(encoding='utf-8')
+            except (OSError, UnicodeError) as exc:
+                errors.append(dict(path=relative, error=str(exc)))
+                continue
+            if is_doc:
+                claims.extend(extract_claims(text, relative))
+            if is_source:
+                evidence, error = extract_evidence(text, relative)
+                (testonly if is_test else production).extend(evidence)
+                if error:
+                    errors.append(dict(path=relative, error=error))
+    findings, verified = [], []
+    for family in ('recursive', 'shallow'):
+        family_claims = [c for c in claims if c['family'] == family]
+        if not family_claims:
+            continue
+        severity, evidence, suffix = None, [], ''
+        if not source_count:
+            severity, evidence = 'HIGH', [dict(kind='no-source')]
+        elif family == 'recursive' and not production:
+            severity, evidence = ('MEDIUM', testonly) if testonly else ('HIGH', [])
+            suffix = '-test-only' if testonly else ''
+        elif family == 'shallow' and (production or testonly):
+            severity, evidence = ('HIGH', production) if production else ('MEDIUM', testonly)
+            suffix = '' if production else '-test-only'
+        if severity:
+            findings.append(dict(rule='documented-' + family + '-claim-false' + suffix,
+                                 severity=severity, claims=family_claims, evidence=evidence))
+        else:
+            verified.append(dict(family=family, claims=family_claims, evidence=production if family == 'recursive' else []))
+    return dict(findings=findings, verified_claims=verified, errors=errors)

recursion_claim_audit-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: recursion-claim-audit
+Version: 0.1.0
+Summary: Audit documented directory traversal depth against Python source.
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# recursion-claim-audit
+
+Audit documented directory traversal depth against Python source.
+
+Version 0.1.0. A stdlib-only, offline static auditor for Python projects.
+It executes no audited code, uses no network, skips symlinks, and never reads
+`.env` contents. Only root `README.md`, Markdown files beneath `docs/`, and
+eligible Python source are opened. Files outside the target are not opened.
+
+## Usage
+
+Requires Python 3.9 or newer. Install and run:
+
+```sh
+python3 -m pip install .
+recursion-claim-audit /path/to/project
+python3 -m recursion_claim_audit /path/to/project --json
+recursion-claim-audit . --verbose --ignore 'vendor/*' --fail-on HIGH
+recursion-claim-audit --version
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+The target defaults to the current directory. `--ignore GLOB` is repeatable
+and matches relative paths; matching directories are pruned. `--verbose`
+adds verified claims and source diagnostics to text output. `--json` emits
+an object with `findings`, `verified_claims`, and `errors`. Findings include
+rule, severity, claims (path, line, text, family), and evidence (path, line,
+kind). Parse/read errors appear in diagnostics and do not themselves create
+rules. Exit status is 0 for PASS, 2 for findings meeting the threshold, and
+1 for usage errors. The default threshold is MEDIUM; `--fail-on HIGH` keeps
+MEDIUM findings visible while permitting exit 0.
+
+## Claim extraction
+
+Claims come only from root README.md and docs Markdown. Fenced blocks are
+excluded; inline code counts as prose. Matching is case-insensitive and uses
+only the exact phrases below, with word boundaries. The families are
+independent; contradictory documentation can produce separate findings.
+
+```text
+RECURSIVE:
+recursively
+recursive scan
+recursive search
+recursively scans
+scans recursively
+searches recursively
+recursively searches
+walks the tree
+walks the directory tree
+recursive traversal
+traverses recursively
+recursively walks
+descends into subdirectories
+all subdirectories
+including subdirectories
+nested directories
+
+SHALLOW:
+top-level only
+top level only
+non-recursive
+not recursive
+single directory
+does not recurse
+doesn't recurse
+no recursion
+without recursion
+shallow scan
+flat scan
+does not descend
+doesn't descend
+```
+
+Negation is asymmetric: a sentence containing no, not, never, without,
+doesn't, don't, or isn't suppresses the RECURSIVE family. SHALLOW phrases
+which express negation themselves still count; other SHALLOW phrases are
+suppressed in negated sentences. This includes the two descent-negation
+phrases at the end of the list. Sentence boundaries are punctuation or
+paragraph boundaries. The bare adverb in the first family counts on its
+own, while the bare noun “recursion” does not. For example:
+
+```text
+walks recursively                  -> recursive claim
+recursion support                  -> no claim
+does not scan recursively          -> no claim
+this tool is not recursive         -> shallow claim
+does not scan top-level only       -> no claim
+```
+
+## Rules
+
+One finding per claimed family; repeated prose is retained in its claims.
+
+| Rule | Severity | Condition |
+| --- | --- | --- |
+| documented-recursive-claim-false | HIGH | RECURSIVE claim without production or test evidence |
+| documented-recursive-claim-false-test-only | MEDIUM | RECURSIVE claim with test evidence alone |
+| documented-shallow-claim-false | HIGH | SHALLOW claim with production evidence |
+| documented-shallow-claim-false-test-only | MEDIUM | SHALLOW claim with test evidence alone |
+
+A claimed family with no production Python source always gets its base HIGH
+rule with `no-source` evidence. A RECURSIVE claim with production evidence
+is verified. A SHALLOW claim without evidence anywhere is verified. No
+claim means PASS regardless of source evidence.
+
+## Named evidence
+
+Each call site or definition is one item, deduplicated by file, line, kind.
+
+| Kind | Recognized syntax |
+| --- | --- |
+| os.walk | Standard library call, including per-file imported aliases |
+| os.path.walk | Legacy standard library call |
+| rglob | Attribute call on any receiver |
+| recursive-glob | glob.glob with literal True for its recursive keyword |
+| glob-pattern | glob.glob or any .glob with a literal first argument containing ** |
+| self-recursive-reader | Function calls its own name and reads directory entries via os.listdir, os.scandir or .iterdir |
+
+Production excludes tests/ and fixtures/ directories, test_*.py, *_test.py,
+docs/, and examples/. Test and fixture source is collected separately.
+Symlinked files and directories are skipped. Build outputs, virtual
+environments, Git metadata and bytecode directories are skipped too.
+
+## Differentiation
+
+| Neighbour | Scope compared with this tool |
+| --- | --- |
+| sort-claim-audit | Output order rather than traversal depth |
+| pagination-claim-audit | Result paging rather than local descent |
+| instruction-drift | Instruction-file truth rather than traversal behaviour |
+| streaming-claim-audit | Read chunking rather than tree depth |
+| bandit / ruff | Code issues rather than documented promises |
+| os.walk / pathlib documentation | Primitive semantics rather than docs-versus-code truth |
+
+## Honest limitations
+
+Exact-phrase matching misses paraphrases and does not resolve which API a
+sentence describes. Evidence is a deliberate over-approximation: dead code
+counts, and presence does not prove the promised operation reaches that
+code. Receiver types are not inferred for attribute matches. Imported names
+are tracked per file, without resolving shadowing, control flow or dynamic
+imports. Nested function definitions are treated separately.
+
+A directory-entry read alone (os.listdir, os.scandir, or .iterdir) is not
+evidence. Repeating a read over a fixed list of directories is not evidence.
+glob.glob without the keyword or the double-star pattern is not evidence;
+a plain Path.glob pattern is not evidence either. A function calling itself
+without directory reads is not evidence. A directory reader without a
+self-call or a recognized walker is not evidence. Third-party walkers such
+as pathspec, wcmatch and the scandir package are outside scope. A keyword
+named recursive with literal True on a non-glob call is not evidence.
+Syntax and decoding errors are reported without executing fallback code.
+The tool cannot prove runtime coverage or filesystem permissions.

recursion_claim_audit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+recursion_claim_audit/__init__.py,sha256=tyalzAT4_vApfhWD0BRLYxa7CWomUC8DfTN73emd4Zs,94
+recursion_claim_audit/__main__.py,sha256=E65AtSdNvcXg4uRaULQU7zG_xoO1LBLTf4bIOxCXAic,1798
+recursion_claim_audit/audit.py,sha256=_fjdlKAuCm5xGgc_fwFbaPTm1HV3RfQiKv4_SnkH4Xk,8482
+recursion_claim_audit-0.1.0.dist-info/licenses/LICENSE,sha256=npbfPSaCrk2DCGzXcDpFkAFgZ1Ghc4aeo9Kl0GJTjyk,1091
+recursion_claim_audit-0.1.0.dist-info/METADATA,sha256=_VZA66FPQz-WU9DAJzGHn5GvQS1cTS9f4CY6HkumDW0,6662
+recursion_claim_audit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+recursion_claim_audit-0.1.0.dist-info/entry_points.txt,sha256=43nMkT4UzORGzAPc6yfmUtd3UOOoDpxscgvb8PfZYgw,78
+recursion_claim_audit-0.1.0.dist-info/top_level.txt,sha256=74_YOD4h_M5wQU0iUGgNTh0QtDPgT18k2hi1igRjeTo,22
+recursion_claim_audit-0.1.0.dist-info/RECORD,,

recursion_claim_audit-0.1.0.dist-info/WHEEL

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

recursion_claim_audit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+recursion-claim-audit = recursion_claim_audit.__main__:main

recursion_claim_audit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 recursion-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.

recursion_claim_audit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+recursion_claim_audit