recursion-claim-audit 0.1.0__tar.gz

recursion_claim_audit-0.1.0/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/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE README.md
+recursive-include tests *.py *.md .env

recursion_claim_audit-0.1.0/PKG-INFO

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

@@ -0,0 +1,155 @@
+# 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/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recursion-claim-audit"
+version = "0.1.0"
+description = "Audit documented directory traversal depth against Python source."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = []
+
+[project.scripts]
+recursion-claim-audit = "recursion_claim_audit.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

recursion_claim_audit-0.1.0/setup.cfg

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

recursion_claim_audit-0.1.0/src/recursion_claim_audit/__init__.py

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

recursion_claim_audit-0.1.0/src/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-0.1.0/src/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/src/recursion_claim_audit.egg-info/PKG-INFO

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

@@ -0,0 +1,25 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/recursion_claim_audit/__init__.py
+src/recursion_claim_audit/__main__.py
+src/recursion_claim_audit/audit.py
+src/recursion_claim_audit.egg-info/PKG-INFO
+src/recursion_claim_audit.egg-info/SOURCES.txt
+src/recursion_claim_audit.egg-info/dependency_links.txt
+src/recursion_claim_audit.egg-info/entry_points.txt
+src/recursion_claim_audit.egg-info/top_level.txt
+tests/test_audit.py
+tests/fixtures/bad/recursive/README.md
+tests/fixtures/bad/recursive/main.py
+tests/fixtures/bad/shallow/README.md
+tests/fixtures/bad/shallow/main.py
+tests/fixtures/good/recursive/.env
+tests/fixtures/good/recursive/README.md
+tests/fixtures/good/recursive/main.py
+tests/fixtures/good/shallow/README.md
+tests/fixtures/good/shallow/main.py
+tests/fixtures/testonly/README.md
+tests/fixtures/testonly/main.py
+tests/fixtures/testonly/tests/test_work.py

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

@@ -0,0 +1 @@
+

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

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

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

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

recursion_claim_audit-0.1.0/tests/fixtures/bad/recursive/README.md

@@ -0,0 +1 @@
+This tool scans recursively.

recursion_claim_audit-0.1.0/tests/fixtures/bad/recursive/main.py

@@ -0,0 +1,2 @@
+import os
+entries = os.listdir(".")

recursion_claim_audit-0.1.0/tests/fixtures/bad/shallow/README.md

@@ -0,0 +1 @@
+This tool top-level only.

recursion_claim_audit-0.1.0/tests/fixtures/bad/shallow/main.py

@@ -0,0 +1,2 @@
+import os
+for entry in os.walk("."): pass

recursion_claim_audit-0.1.0/tests/fixtures/good/recursive/.env

@@ -0,0 +1 @@
+RECURSION_AUDIT_ENV_MARKER_DO_NOT_READ

recursion_claim_audit-0.1.0/tests/fixtures/good/recursive/README.md

@@ -0,0 +1 @@
+This tool scans recursively.

recursion_claim_audit-0.1.0/tests/fixtures/good/recursive/main.py

@@ -0,0 +1,2 @@
+import os
+for entry in os.walk("."): pass

recursion_claim_audit-0.1.0/tests/fixtures/good/shallow/README.md

@@ -0,0 +1 @@
+This tool top-level only.

recursion_claim_audit-0.1.0/tests/fixtures/good/shallow/main.py

@@ -0,0 +1,2 @@
+import os
+entries = os.listdir(".")

recursion_claim_audit-0.1.0/tests/fixtures/testonly/README.md

@@ -0,0 +1 @@
+This tool scans recursively.

recursion_claim_audit-0.1.0/tests/fixtures/testonly/main.py

@@ -0,0 +1,2 @@
+import os
+entries = os.listdir(".")

recursion_claim_audit-0.1.0/tests/fixtures/testonly/tests/test_work.py

@@ -0,0 +1,4 @@
+import os
+
+def test_walk():
+    return list(os.walk("."))

recursion_claim_audit-0.1.0/tests/test_audit.py

@@ -0,0 +1,282 @@
+import contextlib
+import io
+import json
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from recursion_claim_audit.audit import audit, extract_claims, extract_evidence, RECURSIVE, SHALLOW
+from recursion_claim_audit.__main__ import main
+
+FIXTURES = Path(__file__).parent / 'fixtures'
+
+
+class Claims(unittest.TestCase):
+    def test_fenced(self):
+        self.assertEqual(extract_claims('```text\nscans recursively\n```'), [])
+
+    def test_tilde_fenced(self):
+        self.assertEqual(extract_claims('~~~\ntop-level only\n~~~'), [])
+
+    def test_long_fence(self):
+        self.assertEqual(extract_claims('````\n```\nrecursively\n````'), [])
+
+    def test_inline(self):
+        self.assertEqual(extract_claims('Uses `recursive scan`.')[0]['family'], 'recursive')
+
+    def test_bare_noun(self):
+        self.assertEqual(extract_claims('recursion support'), [])
+
+    def test_negated_recursive(self):
+        self.assertEqual(extract_claims('does not scan recursively'), [])
+
+    def test_walks_adverb(self):
+        self.assertEqual(extract_claims('walks recursively')[0]['family'], 'recursive')
+
+    def test_negated_shallow(self):
+        self.assertEqual(extract_claims('does not scan top-level only'), [])
+
+    def test_negated_explicit(self):
+        self.assertEqual([c['family'] for c in extract_claims('this tool is not recursive')], ['shallow'])
+
+    def test_boundaries(self):
+        self.assertEqual(extract_claims('non-recursively scanning; recursive scanner'), [])
+
+    def test_sentence_scope(self):
+        self.assertEqual(len(extract_claims('Not supported. Scans recursively.')), 1)
+
+    def test_inline_dotted_name_negation(self):
+        self.assertEqual(extract_claims('Does not use `os.walk` recursively.'), [])
+
+    def test_multiline_negation(self):
+        self.assertEqual(extract_claims('does not scan\nrecursively'), [])
+
+    def test_multiline_phrase(self):
+        self.assertEqual(extract_claims('Uses recursive\nscan.')[0]['line'], 1)
+
+    def test_line_number(self):
+        self.assertEqual(extract_claims('Hello.\n\nScans recursively.')[0]['line'], 3)
+
+
+class Evidence(unittest.TestCase):
+    def test_syntax_error(self):
+        evidence, error = extract_evidence('def broken(', 'x.py')
+        self.assertEqual(evidence, [])
+        self.assertTrue(error)
+
+    def test_nested_function_separate(self):
+        source = 'def scan():\n    scan()\n    def inner():\n        os.listdir(".")\n'
+        self.assertEqual(extract_evidence(source, 'x.py')[0], [])
+
+    def test_dedupe(self):
+        self.assertEqual(len(extract_evidence('os.walk("."); os.walk(".")', 'x.py')[0]), 1)
+
+
+POSITIVE = {
+ 'os_walk': 'import os\nos.walk(".")',
+ 'import_walk': 'from os import walk\nwalk(".")',
+ 'alias_walk': 'from os import walk as descend\ndescend(".")',
+ 'alias_os': 'import os as operating\noperating.walk(".")',
+ 'legacy': 'os.path.walk(".", callback, None)',
+ 'rglob': 'Path(".").rglob("*.py")',
+ 'any_rglob': 'thing.rglob("*")',
+ 'glob_keyword': 'import glob\nglob.glob("*", recursive=True)',
+ 'glob_alias': 'from glob import glob as gg\ngg("*", recursive=True)',
+ 'glob_pattern': 'glob.glob("**/*.py")',
+ 'path_glob': 'path.glob("**/*.py")',
+ 'self_scandir': 'def scan(p):\n    for x in os.scandir(p):\n        scan(x.path)',
+ 'self_listdir': 'def scan(p):\n    os.listdir(p)\n    scan(p)',
+ 'self_iterdir': 'def scan(p):\n    p.iterdir()\n    scan(p)',
+ 'self_alias': 'from os import scandir as read\ndef scan(p):\n    read(p)\n    scan(p)',
+ 'dead_code': 'def unused():\n    os.walk(".")',
+}
+NEGATIVE = {
+ 'bare_walk': 'walk(".")',
+ 'flat_listdir': 'os.listdir(".")',
+ 'flat_scandir': 'os.scandir(".")',
+ 'flat_iterdir': 'path.iterdir()',
+ 'plain_glob': 'glob.glob("*.py")',
+ 'plain_path_glob': 'Path(".").glob("*.py")',
+ 'variable_recursive': 'glob.glob("*", recursive=setting)',
+ 'false_recursive': 'glob.glob("*", recursive=False)',
+ 'integer_recursive': 'glob.glob("*", recursive=1)',
+ 'non_glob_recursive': 'fetch("*", recursive=True)',
+ 'factorial': 'def fact(n):\n    return n * fact(n-1)',
+ 'fixed_directories': 'for p in ["a", "b"]:\n    os.listdir(p)',
+ 'pattern_variable': 'glob.glob(pattern)',
+ 'string_evidence': 'value = "os.walk()"',
+}
+
+
+def phrase_test(phrase, family):
+    def test(self):
+        self.assertEqual([c['family'] for c in extract_claims(phrase.upper())], [family])
+    return test
+
+
+for family, phrases in [('recursive', RECURSIVE), ('shallow', SHALLOW)]:
+    for i, phrase in enumerate(phrases):
+        setattr(Claims, 'test_phrase_' + family + '_' + str(i), phrase_test(phrase, family))
+
+
+def evidence_test(source, positive):
+    def test(self):
+        evidence, error = extract_evidence(source, 'main.py')
+        self.assertIsNone(error)
+        self.assertEqual(bool(evidence), positive)
+    return test
+
+
+for positive, cases in [(True, POSITIVE), (False, NEGATIVE)]:
+    for name, source in cases.items():
+        setattr(Evidence, 'test_' + name, evidence_test(source, positive))
+
+
+class Integration(unittest.TestCase):
+    def make_tree(self, claim='scans recursively', source='import os\nos.listdir(".")'):
+        temp = tempfile.TemporaryDirectory()
+        self.addCleanup(temp.cleanup)
+        root = Path(temp.name)
+        (root / 'README.md').write_text(claim)
+        if source is not None:
+            (root / 'main.py').write_text(source)
+        return root
+
+    def cli(self, *args):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            code = main(list(map(str, args)))
+        return code, output.getvalue()
+
+    def test_good_recursive(self):
+        result = audit(FIXTURES / 'good/recursive')
+        self.assertEqual(result['findings'], [])
+        self.assertEqual(result['verified_claims'][0]['family'], 'recursive')
+
+    def test_good_shallow(self):
+        self.assertEqual(audit(FIXTURES / 'good/shallow')['verified_claims'][0]['family'], 'shallow')
+
+    def test_bad_recursive(self):
+        findings = audit(FIXTURES / 'bad/recursive')['findings']
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0]['rule'], 'documented-recursive-claim-false')
+        self.assertEqual(findings[0]['severity'], 'HIGH')
+
+    def test_bad_shallow(self):
+        findings = audit(FIXTURES / 'bad/shallow')['findings']
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0]['rule'], 'documented-shallow-claim-false')
+        self.assertEqual(len(findings[0]['evidence']), 1)
+
+    def test_testonly(self):
+        code, output = self.cli(FIXTURES / 'testonly', '--json')
+        finding = json.loads(output)['findings'][0]
+        self.assertEqual(code, 2)
+        self.assertEqual(finding['rule'], 'documented-recursive-claim-false-test-only')
+        self.assertEqual(finding['severity'], 'MEDIUM')
+
+    def test_high_threshold(self):
+        code, output = self.cli(FIXTURES / 'testonly', '--fail-on', 'HIGH')
+        self.assertEqual(code, 0)
+        self.assertIn('MEDIUM', output)
+
+    def test_ignore(self):
+        root = self.make_tree(source='os.walk(".")')
+        self.assertEqual(audit(root)['findings'], [])
+        self.assertEqual(audit(root, ['main.py'])['findings'][0]['evidence'], [{'kind': 'no-source'}])
+
+    def test_both_no_source(self):
+        root = self.make_tree('Scans recursively. Top-level only.', None)
+        findings = audit(root)['findings']
+        self.assertEqual(len(findings), 2)
+        self.assertTrue(all(f['severity'] == 'HIGH' and f['evidence'] == [{'kind': 'no-source'}] for f in findings))
+
+    def test_both_testonly(self):
+        root = self.make_tree('Scans recursively. Top-level only.')
+        (root / 'tests').mkdir()
+        (root / 'tests/test_x.py').write_text('os.walk(".")')
+        self.assertEqual(len(audit(root)['findings']), 2)
+        self.assertTrue(all(f['severity'] == 'MEDIUM' for f in audit(root)['findings']))
+
+    def test_no_claim(self):
+        self.assertEqual(audit(self.make_tree('A tool.', 'os.walk(".")'))['findings'], [])
+
+    def test_shallow_all_evidence(self):
+        root = self.make_tree('top-level only', 'os.walk(".")\np.rglob("*")')
+        self.assertEqual(len(audit(root)['findings'][0]['evidence']), 2)
+
+    def test_json_shape(self):
+        code, output = self.cli(FIXTURES / 'good/recursive', '--json')
+        self.assertEqual(code, 0)
+        self.assertEqual(set(json.loads(output)), {'findings', 'verified_claims', 'errors'})
+
+    def test_env_never_opened(self):
+        original = Path.open
+        def guarded(path, *args, **kwargs):
+            self.assertNotEqual(path.name, '.env')
+            return original(path, *args, **kwargs)
+        with patch.object(Path, 'open', guarded):
+            code, output = self.cli(FIXTURES / 'good/recursive', '--json')
+        self.assertEqual(code, 0)
+        self.assertNotIn('RECURSION_AUDIT_ENV_MARKER_DO_NOT_READ', output)
+
+    def test_symlinks(self):
+        root = self.make_tree()
+        with tempfile.TemporaryDirectory() as outside:
+            path = Path(outside) / 'source.py'
+            path.write_text('os.walk(".")')
+            (root / 'linked.py').symlink_to(path)
+            (root / 'linked_dir').symlink_to(outside, target_is_directory=True)
+            self.assertEqual(audit(root)['findings'][0]['severity'], 'HIGH')
+            self.assertEqual(audit(root)['findings'][0]['evidence'], [])
+
+    def test_exclusions(self):
+        root = self.make_tree('top-level only')
+        for directory in ['docs', 'examples']:
+            (root / directory).mkdir()
+            (root / directory / 'walk.py').write_text('os.walk(".")')
+        self.assertEqual(len(audit(root)['verified_claims']), 1)
+
+    def test_docs_nested(self):
+        root = self.make_tree('A tool.')
+        (root / 'docs/nested').mkdir(parents=True)
+        (root / 'docs/nested/guide.md').write_text('scans recursively')
+        self.assertEqual(len(audit(root)['findings']), 1)
+
+    def test_other_markdown_excluded(self):
+        root = self.make_tree('A tool.')
+        (root / 'OTHER.md').write_text('scans recursively')
+        self.assertEqual(audit(root)['findings'], [])
+
+    def test_parse_diagnostic(self):
+        root = self.make_tree(source='def bad(')
+        self.assertEqual(len(audit(root)['errors']), 1)
+
+    def test_version(self):
+        with self.assertRaises(SystemExit) as error:
+            code, output = self.cli('--version')
+        self.assertEqual(error.exception.code, 0)
+        result = subprocess.run([sys.executable, '-m', 'recursion_claim_audit', '--version'], capture_output=True, text=True)
+        self.assertEqual(result.stdout.strip(), '0.1.0')
+
+    def test_usage(self):
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as error:
+            main(['--unknown'])
+        self.assertEqual(error.exception.code, 1)
+
+    def test_missing_target(self):
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as error:
+            main(['/no/such/audit/tree'])
+        self.assertEqual(error.exception.code, 1)
+
+    def test_self_audit(self):
+        result = audit(Path(__file__).resolve().parents[1])
+        self.assertEqual(result['findings'], [])
+        self.assertEqual(result['verified_claims'], [])
+
+
+if __name__ == '__main__':
+    unittest.main()