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

interactive_claim_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Offline static audit of documented interactivity claims."""
+__version__ = '0.1.0'

interactive_claim_audit/__main__.py

@@ -0,0 +1,47 @@
+"""Command line entry point."""
+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(description='Offline static audit of documented interactivity claims.')
+    parser.add_argument('path', nargs='?', default='.')
+    parser.add_argument('--json', action='store_true', dest='as_json')
+    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)
+    try:
+        result = audit(args.path, args.ignore)
+    except (OSError, ValueError) as exc:
+        parser.error(str(exc))
+    failed = any(f['severity'] == 'HIGH' or args.fail_on == 'MEDIUM' for f in result['findings'])
+    result['status'] = 'FAIL' if failed else 'PASS'
+    if args.as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(result['status'])
+        for finding in result['findings']:
+            print(finding['severity'] + ' ' + finding['rule'])
+            for item in finding['evidence']:
+                print('  ' + item.get('path', '') + ':' + str(item.get('line', '')) + ' ' + item['kind'])
+        if args.verbose:
+            for claim in result['verified_claims']:
+                print('verified: ' + claim['family'])
+            for error in result['errors']:
+                print('parse warning: ' + error['path'] + ': ' + error['message'])
+    return 2 if failed else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

interactive_claim_audit/audit.py

@@ -0,0 +1,158 @@
+"""Static documentation and prompt-call auditing; never imports audited code."""
+import ast
+import fnmatch
+import os
+from pathlib import Path
+import re
+
+NONINTERACTIVE = (
+    'non-interactive', 'non interactive', 'not interactive', 'no prompts',
+    'no user input', 'without user input', 'does not prompt', "doesn't prompt",
+    'never prompts', 'without prompting', 'no interaction required',
+    'no confirmation prompt', 'no manual intervention', 'does not ask',
+    'never asks', 'runs unattended', 'unattended', 'CI-friendly', 'CI friendly',
+    'suitable for CI', 'works in CI',
+)
+INTERACTIVE = (
+    'interactive mode', 'interactive prompt', 'interactive use',
+    'interactive confirmation', 'confirmation prompt', 'prompts for confirmation',
+    'asks for confirmation', 'asks the user', 'prompts the user',
+    'prompt for confirmation', 'ask the user',
+)
+NEGATION = re.compile(r"\b(?:no|not|never|without|doesn't|don't|isn't|does not)\b", re.I)
+
+
+def phrase_pattern(phrases):
+    return re.compile(r'(?<!\w)(?:' + '|'.join(re.escape(p) for p in sorted(phrases, key=len, reverse=True)) + r')(?!\w)', re.I)
+
+
+def extract_claims(text, path='README.md'):
+    """Return phrase occurrences with locations, excluding Markdown fences."""
+    lines = []
+    fence = None
+    for line in text.splitlines(keepends=True):
+        match = re.match(r'^\s{0,3}(`{3,}|~{3,})', line)
+        if fence:
+            lines.append('\n' if line.endswith('\n') else '')
+            if match and match[1][0] == fence[0] and len(match[1]) >= len(fence) and not line[match.end():].strip():
+                fence = None
+        elif match:
+            fence = match[1]
+            lines.append('\n' if line.endswith('\n') else '')
+        else:
+            lines.append(line)
+    prose = ''.join(lines)
+    result = []
+    for sentence in re.finditer(r'[^.!?]+(?:[.!?]|$)', prose):
+        value = sentence[0]
+        masked = list(value)
+        for match in phrase_pattern(NONINTERACTIVE).finditer(value):
+            result.append({'family': 'noninteractive', 'path': path,
+                           'line': prose.count('\n', 0, sentence.start() + match.start()) + 1,
+                           'phrase': match[0]})
+            masked[match.start():match.end()] = ' ' * len(match[0])
+        if not NEGATION.search(value):
+            for match in phrase_pattern(INTERACTIVE).finditer(''.join(masked)):
+                result.append({'family': 'interactive', 'path': path,
+                               'line': prose.count('\n', 0, sentence.start() + match.start()) + 1,
+                               'phrase': match[0]})
+    return result
+
+
+def extract_evidence(source, path):
+    tree = ast.parse(source, filename=path)
+    getpass_names = set()
+    questionary_names = set()
+    questionary_functions = set()
+    toolkit_names = set()
+    toolkit_imported = False
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == 'questionary':
+                    questionary_names.add(alias.asname or alias.name)
+                if alias.name == 'prompt_toolkit' or alias.name.startswith('prompt_toolkit.'):
+                    toolkit_names.add(alias.asname or alias.name.split('.')[0])
+                    toolkit_imported = True
+        elif isinstance(node, ast.ImportFrom):
+            if node.module == 'getpass':
+                getpass_names.update(a.asname or a.name for a in node.names if a.name == 'getpass')
+            if node.module == 'questionary':
+                questionary_functions.update(a.asname or a.name for a in node.names)
+            if node.module and (node.module == 'prompt_toolkit' or node.module.startswith('prompt_toolkit.')):
+                toolkit_imported = True
+                toolkit_names.update(a.asname or a.name for a in node.names if a.name == 'shortcuts')
+                toolkit_names.update(a.asname or a.name for a in node.names if a.name == 'prompt')
+    result = {}
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        func = node.func
+        kind = None
+        if isinstance(func, ast.Name):
+            if func.id == 'input':
+                kind = 'input'
+            elif func.id in getpass_names:
+                kind = 'getpass'
+            elif func.id in questionary_functions:
+                kind = 'questionary'
+            elif toolkit_imported and (func.id == 'prompt' or func.id in toolkit_names and func.id != 'shortcuts'):
+                kind = 'prompt_toolkit'
+        elif isinstance(func, ast.Attribute):
+            if func.attr in ('prompt', 'confirm', 'getpass'):
+                kind = func.attr
+            elif func.attr == 'input' and isinstance(func.value, ast.Name) and func.value.id == 'builtins':
+                kind = 'input'
+            elif isinstance(func.value, ast.Name) and func.value.id in questionary_names:
+                kind = 'questionary'
+        if kind:
+            result[(path, node.lineno, kind)] = {'path': path, 'line': node.lineno, 'kind': kind}
+    return sorted(result.values(), key=lambda e: (e['path'], e['line'], e['kind']))
+
+
+def audit(root, ignore=()):
+    root = Path(root)
+    if not root.is_dir():
+        raise ValueError('audit path must be a directory')
+    claims, production, testonly, errors = [], [], [], []
+    source_count = 0
+    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 not any(fnmatch.fnmatch((Path(directory) / d).relative_to(root).as_posix(), p) for p in ignore))
+        for name in sorted(files):
+            file = Path(directory) / name
+            relative = file.relative_to(root)
+            path = relative.as_posix()
+            if file.is_symlink() or name == '.env' or name.startswith('.env.') or any(fnmatch.fnmatch(path, p) for p in ignore):
+                continue
+            is_doc = path == 'README.md' or (relative.parts[0] == 'docs' and file.suffix == '.md')
+            if is_doc:
+                claims.extend(extract_claims(file.read_text(encoding='utf-8'), path))
+            if file.suffix != '.py' or any(p in ('docs', 'examples') for p in relative.parts[:-1]):
+                continue
+            test = any(p in ('tests', 'fixtures') for p in relative.parts[:-1]) or name.startswith('test_') or name.endswith('_test.py')
+            if not test:
+                source_count += 1
+            try:
+                evidence = extract_evidence(file.read_text(encoding='utf-8-sig'), path)
+            except (SyntaxError, UnicodeError) as exc:
+                errors.append({'path': path, 'message': str(exc)})
+                continue
+            (testonly if test else production).extend(evidence)
+    findings, verified = [], []
+    for family in ('noninteractive', 'interactive'):
+        family_claims = [c for c in claims if c['family'] == family]
+        if not family_claims:
+            continue
+        evidence = production
+        severity, suffix = 'HIGH', ''
+        if not source_count:
+            evidence = [{'kind': 'no-source'}]
+        elif not production and testonly:
+            severity, suffix, evidence = 'MEDIUM', '-test-only', testonly
+        elif (family == 'noninteractive' and not production) or (family == 'interactive' and production):
+            verified.append({'family': family, 'claims': family_claims, 'evidence': production})
+            continue
+        findings.append({'rule': 'documented-' + family + '-claim-false' + suffix,
+                         'severity': severity, 'claims': family_claims, 'evidence': evidence})
+    return {'findings': findings, 'verified_claims': verified, 'claims': claims,
+            'production_evidence': production, 'test_only_evidence': testonly, 'errors': errors}

interactive_claim_audit-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: interactive-claim-audit
+Version: 0.1.0
+Summary: Offline static audit of documented interactivity claims.
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# interactive-claim-audit
+
+Offline static audit of documented interactivity claims.
+
+Version 0.1.0 · Python 3.9+ · MIT · standard library only at runtime.
+
+Compare documentation promises about human interaction with named Python call sites. The auditor parses source without importing or executing the audited project, uses no network, skips symlinks, and skips `.env` and `.env.*` file contents.
+
+## Usage
+
+Install from a local checkout:
+
+```sh
+python3 -m pip install .
+interactive-claim-audit /path/to/project
+python3 -m interactive_claim_audit /path/to/project --json
+interactive-claim-audit /path/to/project --verbose --ignore 'vendor/*'
+interactive-claim-audit /path/to/project --fail-on HIGH
+interactive-claim-audit --version
+```
+
+The path defaults to the current directory. `--ignore GLOB` is repeatable and matches relative paths. `--verbose` adds verified families and parse warnings to text output. `--json` emits a JSON object containing `status`, `findings`, `verified_claims`, `claims`, `production_evidence`, `test_only_evidence`, and `errors`.
+
+Exit codes are 0 for PASS, 2 for findings meeting the selected threshold, and 1 for usage errors. The default threshold is MEDIUM; `--fail-on HIGH` leaves MEDIUM findings visible but permits exit 0.
+
+## Rules
+
+Documentation occurrences collapse into two families, `noninteractive` and `interactive`, evaluated independently. Each failing family produces one finding containing all applicable evidence items.
+
+| Rule | Severity | Condition |
+| --- | --- | --- |
+| `documented-noninteractive-claim-false` | HIGH | The noninteractive family has production evidence. |
+| `documented-noninteractive-claim-false-test-only` | MEDIUM | That family has evidence only in test or fixture sources. |
+| `documented-interactive-claim-false` | HIGH | The interactive family lacks production evidence and has no test evidence. |
+| `documented-interactive-claim-false-test-only` | MEDIUM | That family has evidence only in test or fixture sources. |
+
+A claimed family with no production Python files produces one HIGH finding with `no-source` evidence, taking priority over the test-only rules. With production files present, the noninteractive family is verified when evidence is absent everywhere; the interactive family is verified when production evidence exists. Verified families appear in `verified_claims`. A tree with zero documentation claims passes regardless of its call sites.
+
+## Claim vocabulary
+
+Only root `README.md` and `docs/**/*.md` supply claims. Fenced code blocks are excluded; inline code spans count as prose. Matching is case-insensitive and limited to the exact phrases below; hyphen and space spellings are accepted only where explicitly listed.
+
+```text
+NONINTERACTIVE
+non-interactive
+non interactive
+not interactive
+no prompts
+no user input
+without user input
+does not prompt
+doesn't prompt
+never prompts
+without prompting
+no interaction required
+no confirmation prompt
+no manual intervention
+does not ask
+never asks
+runs unattended
+unattended
+CI-friendly
+CI friendly
+suitable for CI
+works in CI
+
+INTERACTIVE
+interactive mode
+interactive prompt
+interactive use
+interactive confirmation
+confirmation prompt
+prompts for confirmation
+asks for confirmation
+asks the user
+prompts the user
+prompt for confirmation
+ask the user
+```
+
+Negation is asymmetric: a sentence containing `no`, `not`, `never`, `without`, `doesn't`, `don't`, `isn't`, or `does not` suppresses the interactive family. Matches in the noninteractive family still count, including its negated phrases. Overlap masking finds the noninteractive family first, masks its matched spans, and searches the remaining text for the interactive family. This prevents a substring from generating an extra family match.
+
+The bare words “interactive” and “prompt” are not claims. Paraphrases outside the vocabulary are not inferred. Contradictory documentation can supply both families; each receives its own evaluation.
+
+## Named evidence table
+
+Evidence is collected from Python AST calls and deduplicated by relative file, line, and kind. Imports and aliases are tracked per file where indicated.
+
+| Named call | Evidence treatment |
+| --- | --- |
+| `input(...)`, `builtins.input(...)` | Counts, including a locally shadowed `input`. |
+| `.getpass(...)` | Counts on any receiver spelling. |
+| Imported bare `getpass(...)` | Counts with `from getpass import getpass`, including aliases; a bare name without that import does not count. |
+| `.prompt(...)` | Counts on any receiver, including Click, Questionary objects, and toolkit sessions. |
+| `.confirm(...)` | Counts on any receiver. |
+| `questionary.<name>(...)` or imported Questionary functions | Counts with tracked module or function imports and aliases. |
+| Toolkit `prompt(...)` | Counts with a per-file `prompt_toolkit` import; imported `prompt` aliases and `shortcuts` imports are recognized. |
+
+Production evidence excludes `tests/`, `fixtures/`, test filename patterns (`test_*.py`, `*_test.py`), `docs/`, and `examples/`. Test and fixture evidence is collected separately; docs and examples supply no source evidence. Symlinked files and directories are skipped. Parse and decoding failures are reported in `errors`; they are not proof that a file lacks relevant behavior.
+
+## Differentiation
+
+| Neighbour | Its question | This tool's distinction |
+| --- | --- | --- |
+| auth-claim-audit | Are credentials required? | Examines dependence on a human, including filename and yes/no questions. `getpass` overlaps explicitly: login evidence there, human-input evidence here. |
+| error-claim-audit | Which failures occur? | Examines waiting for a person. |
+| concurrency-claim-audit | What execution model is used? | Examines human interaction. |
+| timeout-claim-audit | What time bounds apply? | Examines human blocking rather than elapsed-time guarantees. |
+| Bandit / Ruff | What code issues exist? | Compares documentation promises with source evidence. |
+| Click / Questionary / prompt_toolkit documentation | How are input primitives used? | Checks documentation against a project's source instead of teaching those APIs. |
+
+## Honest limitations
+
+This is a vocabulary-and-call-site check, not a behavioral proof. Exact-phrase claims miss paraphrases. Dead code counts: a call in an uncalled function is still evidence. Reachability, branches, flag defaults, runtime configuration, and whether a person actually sees a question are not inferred. A successful result does not prove every documented execution path behaves as intended.
+
+Receiver types are not inferred: `.prompt`, `.confirm`, and `.getpass` calls on unrelated objects or test doubles can count. A locally defined `input` also counts. Import recognition is limited to the named evidence table; dynamic imports, indirect wrappers, and arbitrary alias assignments can escape detection.
+
+Reading `sys.stdin.read`, `readline`, or `readlines`, including redirected or piped input, is not evidence. Printing and logging are not evidence. Argparse and Click option declarations are not evidence; in particular, `click.option(..., prompt=True)` is a documented gap because it is a declaration rather than a `.prompt(...)` call.
+
+Curses, Urwid, and Textual interfaces are outside scope. Other libraries such as inquirer, PyInquirer, and bullet are outside scope unless their calls independently match a named pattern. Evidence found only in tests or fixtures receives MEDIUM under the rules above; it does not establish production behavior. Negation and overlap masking follow the lexical rules above rather than natural-language understanding.
+
+## Development and packaging
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+# If isolated build dependencies are unavailable offline:
+python3 -m build --no-isolation
+```
+
+The build produces a wheel and source distribution in `dist/`. The source distribution includes the test fixtures through `MANIFEST.in`.

interactive_claim_audit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+interactive_claim_audit/__init__.py,sha256=68Wu9BiGkv56193JM09CjVbDkooBhRKdbHna1AE1FDE,85
+interactive_claim_audit/__main__.py,sha256=sZ2JnqFG6Pk8TPXLe6vVjhXvZTEg1p9H9paLp5ynk9o,1847
+interactive_claim_audit/audit.py,sha256=3ua7AqPTSxxMWKRlkVlv8Pqz-xVoIKlU3_EQdBmsPlo,7838
+interactive_claim_audit-0.1.0.dist-info/licenses/LICENSE,sha256=thQsacfdu4M-E9dSdndeSvRLT6qXnmnSSuwb59DaxUA,1093
+interactive_claim_audit-0.1.0.dist-info/METADATA,sha256=LokRZBA49rHYnl8r_6zLam_aL4k-VRkR8IWUyqJqDOY,8195
+interactive_claim_audit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+interactive_claim_audit-0.1.0.dist-info/entry_points.txt,sha256=Vk4ZASCWTzKE6IOsIauhbvr7Kg4jzS8kgPtQFQ2Buug,82
+interactive_claim_audit-0.1.0.dist-info/top_level.txt,sha256=oS7zsom5pGvCnOPzoPFKiV_Z6XeBHvgHFLqZdGMCh_M,24
+interactive_claim_audit-0.1.0.dist-info/RECORD,,

interactive_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
+

interactive_claim_audit-0.1.0.dist-info/entry_points.txt

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

interactive_claim_audit-0.1.0.dist-info/licenses/LICENSE

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

interactive_claim_audit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+interactive_claim_audit