entry-claim-audit 0.1.0__tar.gz

entry_claim_audit-0.1.0/LICENSE

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

entry_claim_audit-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: entry-claim-audit
+Version: 0.1.0
+Summary: Offline static audits of Python entry-point claims
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# entry-claim-audit
+
+Offline static CLI that checks Python packaging entry-point claims against source on disk. It checks `[project.scripts]` and `[project.gui-scripts]` targets for a module, symbol, and callability, and checks documented command names. It never executes project code, accesses the network, or reads .env contents. Reports contain rule names, paths, script names and targets, not unrelated file contents.
+
+Requires Python 3.9 or later. Runtime dependencies: none.
+
+## Usage
+
+```sh
+pip install .
+entry-claim-audit .
+entry-claim-audit /path/to/project --json
+entry-claim-audit . --fail-on HIGH
+entry-claim-audit . --ignore script-undocumented,script-target-not-callable
+entry-claim-audit . --verbose
+entry-claim-audit --version
+python -m entry_claim_audit .
+```
+
+The path defaults to `.`. Exit codes: 0 PASS, 2 FAIL, 1 usage/input error. Default failure threshold is MEDIUM; `--fail-on HIGH` still prints MEDIUM findings but does not fail for them. `--ignore RULE,...` drops those rules entirely, for example when scripts are documented elsewhere or a data-object target is intentional. `--verbose` adds verified scripts to human output.
+
+Human output has one `SEVERITY rule file:line message` line per finding followed by PASS/FAIL. Metadata findings use `pyproject.toml:0`. JSON contains `status`, `findings` (severity, rule, file, line, message) sorted by rule/file/line, and `verified_scripts` (script, table, target).
+
+For example, `mytool = "pkg.cli:main"` passes if `pkg/cli.py` defines `def main()` and README mentions `mytool`. Renaming that file without updating the target yields `script-target-module-missing` and exit 2.
+
+## Full rule table
+
+| Rule | Severity | Trigger and report |
+| --- | --- | --- |
+| `script-target-malformed` | HIGH | Target has no colon, an empty module/object, internal whitespace, or invalid dotted identifiers. Surrounding whitespace is stripped. Reports script, table and raw target; no further target checks for that script. |
+| `script-target-module-missing` | HIGH | Target module does not resolve to a source file in the supported layouts. Reports script, table and module. |
+| `script-target-symbol-missing` | HIGH | Resolved module lacks the first object segment. Reports script, table, module and missing symbol. |
+| `script-target-attr-missing` | HIGH | First object is a class but the next segment is absent from its directly defined methods. Reports script, table and missing method. Chains beyond that method, or attributes of non-class objects, are unchecked. |
+| `script-target-not-callable` | MEDIUM | First object is a plain data assignment. Functions, async functions, classes, imports, lambdas and call-result assignments pass. Only the first object segment is checked. |
+| `documented-command-missing` | HIGH | First token of a fenced or inline code command equals the project name (case/dash/underscore normalized), but is not an exactly declared script name. Reports doc file:line, token and declared names. Arbitrary other commands are ignored; skipped without a project name. |
+| `script-name-duplicate` | MEDIUM | Same name is declared in both scripts and gui-scripts. |
+| `script-undocumented` | MEDIUM | Script name never occurs as a whole word anywhere in scanned docs, including prose. Skipped when there is neither README.md nor docs markdown. |
+
+Verified targets are not findings. Both script tables receive the same checks. No pyproject.toml, no project table, or no script tables yields PASS with zero findings.
+
+## Static interpretation
+
+Modules resolve in this order: `src/pkg/mod.py`, `src/pkg/mod/__init__.py`, `pkg/mod.py`, `pkg/mod/__init__.py`. Single-segment modules and package `__init__.py` targets are supported. Namespace parent directories are allowed. The directories tests, .venv, __pycache__, dist, .git and .egg-info are not module evidence.
+
+Only the resolved module is parsed. Top-level functions, async functions, classes, Name assignment targets (including annotations), and imported names count as symbols. Re-exports count without importing or following them. Direct class methods include `__init__`. Assignments to lambda/call expressions count as callable or unknown; all other assigned values, including names and attributes, count as data. Definitions nested inside functions or conditional blocks are not collected.
+
+Docs scanned: top-level `*.md` including README.md, and recursive `docs/**/*.md`. Command claims come only from fenced code and inline code spans. Undocumented checks use full text. TOML uses stdlib tomllib on Python 3.11+, with a minimal quoted key/value regex fallback for script tables on older Python (and a simple project-name lookup).
+
+## Differentiation
+
+- **readme-claim-audit** audits pip install names against pyproject and docs flags, links, versions and make targets. This checks whether installed commands resolve to modules, symbols and callables; the rules do not overlap.
+- **api-claim-audit** audits symbols promised in docs code examples. This checks symbols promised in packaging metadata, using similar AST machinery with a different promise source; the rules do not overlap.
+- **dep-claim-audit** audits dependency declarations against imports. This audits entry-point declarations against source.
+- **pip-check, pipdeptree and importlib.metadata checks** inspect an installed environment at runtime. This tool is static and offline and works on a repository that has never been installed.
+- **twine check** validates package metadata for upload; it does not resolve entry-point targets to source symbols.
+
+## Honest limitations
+
+Static scanning misses dynamic symbols created by importlib, module `__getattr__` hooks, exec or eval. An existing symbol still counts even if a failing top-level import prevents actual import. Imported/re-exported names and call-result assignments have unknown runtime callability and pass. Decorators and runtime behavior are not evaluated.
+
+Attribute chains resolve only one class-method step. Further attributes and non-class attributes remain unchecked. setup.cfg and setup.py entry_points are not parsed. The documented-command rule catches only the project's own name, not arbitrary mistyped command names. It examines the first whitespace-separated code token, so shell prompts or wrappers can hide commands. script-undocumented is heuristic: a script documented only outside README/top-level markdown/docs is flagged; use `--ignore script-undocumented`.
+
+The fallback parser supports simple single-line quoted declarations, not full TOML syntax. Invalid TOML (with tomllib), unreadable files and invalid Python syntax produce input-error exit 1. The tool establishes static evidence, not that a built distribution includes the module or that a command will execute successfully.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+MIT licensed.

entry_claim_audit-0.1.0/README.md

@@ -0,0 +1,72 @@
+# entry-claim-audit
+
+Offline static CLI that checks Python packaging entry-point claims against source on disk. It checks `[project.scripts]` and `[project.gui-scripts]` targets for a module, symbol, and callability, and checks documented command names. It never executes project code, accesses the network, or reads .env contents. Reports contain rule names, paths, script names and targets, not unrelated file contents.
+
+Requires Python 3.9 or later. Runtime dependencies: none.
+
+## Usage
+
+```sh
+pip install .
+entry-claim-audit .
+entry-claim-audit /path/to/project --json
+entry-claim-audit . --fail-on HIGH
+entry-claim-audit . --ignore script-undocumented,script-target-not-callable
+entry-claim-audit . --verbose
+entry-claim-audit --version
+python -m entry_claim_audit .
+```
+
+The path defaults to `.`. Exit codes: 0 PASS, 2 FAIL, 1 usage/input error. Default failure threshold is MEDIUM; `--fail-on HIGH` still prints MEDIUM findings but does not fail for them. `--ignore RULE,...` drops those rules entirely, for example when scripts are documented elsewhere or a data-object target is intentional. `--verbose` adds verified scripts to human output.
+
+Human output has one `SEVERITY rule file:line message` line per finding followed by PASS/FAIL. Metadata findings use `pyproject.toml:0`. JSON contains `status`, `findings` (severity, rule, file, line, message) sorted by rule/file/line, and `verified_scripts` (script, table, target).
+
+For example, `mytool = "pkg.cli:main"` passes if `pkg/cli.py` defines `def main()` and README mentions `mytool`. Renaming that file without updating the target yields `script-target-module-missing` and exit 2.
+
+## Full rule table
+
+| Rule | Severity | Trigger and report |
+| --- | --- | --- |
+| `script-target-malformed` | HIGH | Target has no colon, an empty module/object, internal whitespace, or invalid dotted identifiers. Surrounding whitespace is stripped. Reports script, table and raw target; no further target checks for that script. |
+| `script-target-module-missing` | HIGH | Target module does not resolve to a source file in the supported layouts. Reports script, table and module. |
+| `script-target-symbol-missing` | HIGH | Resolved module lacks the first object segment. Reports script, table, module and missing symbol. |
+| `script-target-attr-missing` | HIGH | First object is a class but the next segment is absent from its directly defined methods. Reports script, table and missing method. Chains beyond that method, or attributes of non-class objects, are unchecked. |
+| `script-target-not-callable` | MEDIUM | First object is a plain data assignment. Functions, async functions, classes, imports, lambdas and call-result assignments pass. Only the first object segment is checked. |
+| `documented-command-missing` | HIGH | First token of a fenced or inline code command equals the project name (case/dash/underscore normalized), but is not an exactly declared script name. Reports doc file:line, token and declared names. Arbitrary other commands are ignored; skipped without a project name. |
+| `script-name-duplicate` | MEDIUM | Same name is declared in both scripts and gui-scripts. |
+| `script-undocumented` | MEDIUM | Script name never occurs as a whole word anywhere in scanned docs, including prose. Skipped when there is neither README.md nor docs markdown. |
+
+Verified targets are not findings. Both script tables receive the same checks. No pyproject.toml, no project table, or no script tables yields PASS with zero findings.
+
+## Static interpretation
+
+Modules resolve in this order: `src/pkg/mod.py`, `src/pkg/mod/__init__.py`, `pkg/mod.py`, `pkg/mod/__init__.py`. Single-segment modules and package `__init__.py` targets are supported. Namespace parent directories are allowed. The directories tests, .venv, __pycache__, dist, .git and .egg-info are not module evidence.
+
+Only the resolved module is parsed. Top-level functions, async functions, classes, Name assignment targets (including annotations), and imported names count as symbols. Re-exports count without importing or following them. Direct class methods include `__init__`. Assignments to lambda/call expressions count as callable or unknown; all other assigned values, including names and attributes, count as data. Definitions nested inside functions or conditional blocks are not collected.
+
+Docs scanned: top-level `*.md` including README.md, and recursive `docs/**/*.md`. Command claims come only from fenced code and inline code spans. Undocumented checks use full text. TOML uses stdlib tomllib on Python 3.11+, with a minimal quoted key/value regex fallback for script tables on older Python (and a simple project-name lookup).
+
+## Differentiation
+
+- **readme-claim-audit** audits pip install names against pyproject and docs flags, links, versions and make targets. This checks whether installed commands resolve to modules, symbols and callables; the rules do not overlap.
+- **api-claim-audit** audits symbols promised in docs code examples. This checks symbols promised in packaging metadata, using similar AST machinery with a different promise source; the rules do not overlap.
+- **dep-claim-audit** audits dependency declarations against imports. This audits entry-point declarations against source.
+- **pip-check, pipdeptree and importlib.metadata checks** inspect an installed environment at runtime. This tool is static and offline and works on a repository that has never been installed.
+- **twine check** validates package metadata for upload; it does not resolve entry-point targets to source symbols.
+
+## Honest limitations
+
+Static scanning misses dynamic symbols created by importlib, module `__getattr__` hooks, exec or eval. An existing symbol still counts even if a failing top-level import prevents actual import. Imported/re-exported names and call-result assignments have unknown runtime callability and pass. Decorators and runtime behavior are not evaluated.
+
+Attribute chains resolve only one class-method step. Further attributes and non-class attributes remain unchecked. setup.cfg and setup.py entry_points are not parsed. The documented-command rule catches only the project's own name, not arbitrary mistyped command names. It examines the first whitespace-separated code token, so shell prompts or wrappers can hide commands. script-undocumented is heuristic: a script documented only outside README/top-level markdown/docs is flagged; use `--ignore script-undocumented`.
+
+The fallback parser supports simple single-line quoted declarations, not full TOML syntax. Invalid TOML (with tomllib), unreadable files and invalid Python syntax produce input-error exit 1. The tool establishes static evidence, not that a built distribution includes the module or that a command will execute successfully.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+MIT licensed.

entry_claim_audit-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "entry-claim-audit"
+version = "0.1.0"
+description = "Offline static audits of Python entry-point claims"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+dependencies = []
+
+[project.scripts]
+entry-claim-audit = "entry_claim_audit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

entry_claim_audit-0.1.0/setup.cfg

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

entry_claim_audit-0.1.0/src/entry_claim_audit/__init__.py

@@ -0,0 +1,2 @@
+"""Static audits of Python packaging entry-point claims."""
+__version__ = '0.1.0'

entry_claim_audit-0.1.0/src/entry_claim_audit/__main__.py

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

entry_claim_audit-0.1.0/src/entry_claim_audit/audit.py

@@ -0,0 +1,155 @@
+"""Offline entry-point auditing; project modules are parsed, never imported."""
+import ast
+import re
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:  # Python 3.9–3.10
+    tomllib = None
+
+
+def fallback_metadata(text):
+    """Read only simple quoted key/value pairs in the two script tables."""
+    project = {}
+    table = None
+    for line in text.splitlines():
+        header = re.fullmatch(r'\s*\[([^]]+)\]\s*(?:#.*)?', line)
+        if header:
+            name = header.group(1)
+            table = project.setdefault(name.split('.')[1], {}) if name in ('project.scripts', 'project.gui-scripts') else None
+        elif table is not None:
+            pair = re.fullmatch(r'''\s*(?:"([^"\n]+)"|'([^'\n]+)'|([\w-]+))\s*=\s*(?:"([^"\n]*)"|'([^'\n]*)')\s*(?:#.*)?''', line)
+            if pair:
+                table[next(v for v in pair.groups()[:3] if v is not None)] = next(v for v in pair.groups()[3:] if v is not None)
+    # Name is needed solely for documented-command matching.
+    section = re.search(r'(?ms)^\s*\[project\]\s*\n(.*?)(?=^\s*\[|\Z)', text)
+    if section:
+        name = re.search(r'''(?m)^\s*name\s*=\s*["']([^"']+)["']''', section.group(1))
+        if name:
+            project['name'] = name.group(1)
+    return {'project': project}
+
+
+def resolve_module(root, module):
+    parts = module.split('.')
+    if any(p in {'tests', '.venv', '__pycache__', 'dist', '.git', '.egg-info'} or p.endswith('.egg-info') for p in parts):
+        return None
+    relative = Path(*parts)
+    for base in (root / 'src', root):
+        for candidate in (base / relative.with_suffix('.py'), base / relative / '__init__.py'):
+            if candidate.is_file() and candidate.resolve().is_relative_to(root.resolve()):
+                return candidate
+    return None
+
+
+def symbols(path):
+    tree = ast.parse(path.read_text(encoding='utf-8-sig'), filename=str(path))
+    result = {}
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            methods = {n.name for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))} if isinstance(node, ast.ClassDef) else None
+            result[node.name] = (True, methods)
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                result[alias.asname or alias.name.split('.')[0]] = (True, None)
+        elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            for target in targets:
+                if isinstance(target, ast.Name):
+                    result[target.id] = (isinstance(node.value, (ast.Lambda, ast.Call)), None)
+    return result
+
+
+def code_lines(text):
+    """Yield fenced and inline code with their original document line numbers."""
+    fence = None
+    for number, line in enumerate(text.splitlines(), 1):
+        marker = re.match(r'^\s*(`{3,}|~{3,})', line)
+        if marker:
+            token = marker.group(1)
+            if fence is None:
+                fence = token
+            elif token[0] == fence[0] and len(token) >= len(fence):
+                fence = None
+            continue
+        if fence:
+            yield number, line.strip()
+        else:
+            for match in re.finditer(r'(`+)(.+?)\1', line):
+                yield number, match.group(2).strip()
+
+
+def audit(path='.', fail_on='MEDIUM', ignore=()):
+    root = Path(path)
+    if not root.is_dir():
+        raise ValueError('project path must be a directory')
+    metadata = root / 'pyproject.toml'
+    data = {}
+    if metadata.is_file():
+        raw = metadata.read_text(encoding='utf-8')
+        data = tomllib.loads(raw) if tomllib else fallback_metadata(raw)
+    project = data.get('project', {})
+    if not isinstance(project, dict):
+        raise ValueError('project must be a table')
+    if not any(table in project for table in ('scripts', 'gui-scripts')):
+        return dict(status='PASS', findings=[], verified_scripts=[])
+    findings, verified = [], []
+    ignored = set(ignore)
+    def add(rule, severity, file, line, message):
+        if rule not in ignored:
+            findings.append(dict(rule=rule, severity=severity, file=file, line=line, message=message))
+    scripts = []
+    for table in ('scripts', 'gui-scripts'):
+        entries = project.get(table, {})
+        if not isinstance(entries, dict):
+            raise ValueError('entry-point declarations must be tables')
+        scripts.extend((name, table, target) for name, target in entries.items())
+    declared = {name for name, _, _ in scripts}
+    for name in sorted(set(project.get('scripts', {})) & set(project.get('gui-scripts', {}))):
+        add('script-name-duplicate', 'MEDIUM', 'pyproject.toml', 0, f'{name}: declared in scripts and gui-scripts')
+    for name, table, raw in scripts:
+        before = len(findings)
+        prefix = f'{name} ({table})'
+        target = raw.strip() if isinstance(raw, str) else ''
+        pattern = r'[^\W\d]\w*(?:\.[^\W\d]\w*)*:[^\W\d]\w*(?:\.[^\W\d]\w*)*'
+        if not re.fullmatch(pattern, target):
+            add('script-target-malformed', 'HIGH', 'pyproject.toml', 0, f'{prefix}: malformed target {raw!r}')
+            continue
+        module, obj = target.split(':')
+        source = resolve_module(root, module)
+        if source is None:
+            add('script-target-module-missing', 'HIGH', 'pyproject.toml', 0, f'{prefix}: module {module} missing')
+            continue
+        names = symbols(source)
+        segments = obj.split('.')
+        symbol = segments[0]
+        if symbol not in names:
+            add('script-target-symbol-missing', 'HIGH', 'pyproject.toml', 0, f'{prefix}: {module} symbol {symbol} missing')
+            continue
+        callable_, methods = names[symbol]
+        if methods is not None and len(segments) > 1 and segments[1] not in methods:
+            add('script-target-attr-missing', 'HIGH', 'pyproject.toml', 0, f'{prefix}: {module}:{symbol} method {segments[1]} missing')
+        if not callable_:
+            add('script-target-not-callable', 'MEDIUM', 'pyproject.toml', 0, f'{prefix}: {module}:{symbol} is a data assignment')
+        if len(findings) == before:
+            verified.append(dict(script=name, table=table, target=raw))
+    docs = set(root.glob('*.md'))
+    docs.update((root / 'docs').rglob('*.md'))
+    texts = [(p, p.read_text(encoding='utf-8')) for p in sorted(docs) if p.is_file() and p.resolve().is_relative_to(root.resolve())]
+    normalize = lambda value: value.lower().replace('_', '-')
+    project_name = project.get('name')
+    for doc, text in texts:
+        if project_name:
+            for line, command in code_lines(text):
+                tokens = command.split()
+                if tokens and normalize(tokens[0]) == normalize(project_name) and tokens[0] not in declared:
+                    add('documented-command-missing', 'HIGH', str(doc.relative_to(root)), line, f'{tokens[0]} is not declared; declared scripts: {", ".join(sorted(declared)) or "(none)"}')
+    has_docs = (root / 'README.md').is_file() or any(p.is_relative_to(root / 'docs') for p, _ in texts)
+    if has_docs:
+        for name in sorted(declared):
+            if not any(re.search(r'(?<!\w)' + re.escape(name) + r'(?!\w)', text) for _, text in texts):
+                add('script-undocumented', 'MEDIUM', 'pyproject.toml', 0, f'{name}: never mentioned in scanned docs')
+    findings.sort(key=lambda f: (f['rule'], f['file'], f['line'], f['message']))
+    failed = any(f['severity'] == 'HIGH' or fail_on == 'MEDIUM' for f in findings)
+    return dict(status='FAIL' if failed else 'PASS', findings=findings, verified_scripts=sorted(verified, key=lambda s: (s['script'], s['table'], s['target'])))

entry_claim_audit-0.1.0/src/entry_claim_audit/cli.py

@@ -0,0 +1,38 @@
+"""Command-line interface."""
+import argparse
+import json
+import sys
+from . import __version__
+from .audit import audit
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(1, f'{self.prog}: error: {message}\n')
+
+
+def main(argv=None):
+    parser = Parser(prog='entry-claim-audit')
+    parser.add_argument('path', nargs='?', default='.')
+    parser.add_argument('--json', action='store_true')
+    parser.add_argument('--fail-on', choices=['HIGH', 'MEDIUM'], default='MEDIUM')
+    parser.add_argument('--ignore', default='', metavar='RULE,...')
+    parser.add_argument('--verbose', action='store_true')
+    parser.add_argument('--version', action='version', version=__version__)
+    args = parser.parse_args(argv)
+    try:
+        result = audit(args.path, args.fail_on, args.ignore.split(','))
+    except (OSError, ValueError, SyntaxError) as exc:
+        # Never echo source fragments or unrelated file contents.
+        parser.exit(1, f'entry-claim-audit: unable to read or parse project ({type(exc).__name__})\n')
+    if args.json:
+        print(json.dumps(result))
+    else:
+        for f in result['findings']:
+            print(f"{f['severity']} {f['rule']} {f['file']}:{f['line']} {f['message']}")
+        if args.verbose:
+            for script in result['verified_scripts']:
+                print(f"verified {script['script']} ({script['table']}): {script['target']}")
+        print(f"{result['status']}: {len(result['findings'])} finding(s)")
+    return 2 if result['status'] == 'FAIL' else 0

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

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: entry-claim-audit
+Version: 0.1.0
+Summary: Offline static audits of Python entry-point claims
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# entry-claim-audit
+
+Offline static CLI that checks Python packaging entry-point claims against source on disk. It checks `[project.scripts]` and `[project.gui-scripts]` targets for a module, symbol, and callability, and checks documented command names. It never executes project code, accesses the network, or reads .env contents. Reports contain rule names, paths, script names and targets, not unrelated file contents.
+
+Requires Python 3.9 or later. Runtime dependencies: none.
+
+## Usage
+
+```sh
+pip install .
+entry-claim-audit .
+entry-claim-audit /path/to/project --json
+entry-claim-audit . --fail-on HIGH
+entry-claim-audit . --ignore script-undocumented,script-target-not-callable
+entry-claim-audit . --verbose
+entry-claim-audit --version
+python -m entry_claim_audit .
+```
+
+The path defaults to `.`. Exit codes: 0 PASS, 2 FAIL, 1 usage/input error. Default failure threshold is MEDIUM; `--fail-on HIGH` still prints MEDIUM findings but does not fail for them. `--ignore RULE,...` drops those rules entirely, for example when scripts are documented elsewhere or a data-object target is intentional. `--verbose` adds verified scripts to human output.
+
+Human output has one `SEVERITY rule file:line message` line per finding followed by PASS/FAIL. Metadata findings use `pyproject.toml:0`. JSON contains `status`, `findings` (severity, rule, file, line, message) sorted by rule/file/line, and `verified_scripts` (script, table, target).
+
+For example, `mytool = "pkg.cli:main"` passes if `pkg/cli.py` defines `def main()` and README mentions `mytool`. Renaming that file without updating the target yields `script-target-module-missing` and exit 2.
+
+## Full rule table
+
+| Rule | Severity | Trigger and report |
+| --- | --- | --- |
+| `script-target-malformed` | HIGH | Target has no colon, an empty module/object, internal whitespace, or invalid dotted identifiers. Surrounding whitespace is stripped. Reports script, table and raw target; no further target checks for that script. |
+| `script-target-module-missing` | HIGH | Target module does not resolve to a source file in the supported layouts. Reports script, table and module. |
+| `script-target-symbol-missing` | HIGH | Resolved module lacks the first object segment. Reports script, table, module and missing symbol. |
+| `script-target-attr-missing` | HIGH | First object is a class but the next segment is absent from its directly defined methods. Reports script, table and missing method. Chains beyond that method, or attributes of non-class objects, are unchecked. |
+| `script-target-not-callable` | MEDIUM | First object is a plain data assignment. Functions, async functions, classes, imports, lambdas and call-result assignments pass. Only the first object segment is checked. |
+| `documented-command-missing` | HIGH | First token of a fenced or inline code command equals the project name (case/dash/underscore normalized), but is not an exactly declared script name. Reports doc file:line, token and declared names. Arbitrary other commands are ignored; skipped without a project name. |
+| `script-name-duplicate` | MEDIUM | Same name is declared in both scripts and gui-scripts. |
+| `script-undocumented` | MEDIUM | Script name never occurs as a whole word anywhere in scanned docs, including prose. Skipped when there is neither README.md nor docs markdown. |
+
+Verified targets are not findings. Both script tables receive the same checks. No pyproject.toml, no project table, or no script tables yields PASS with zero findings.
+
+## Static interpretation
+
+Modules resolve in this order: `src/pkg/mod.py`, `src/pkg/mod/__init__.py`, `pkg/mod.py`, `pkg/mod/__init__.py`. Single-segment modules and package `__init__.py` targets are supported. Namespace parent directories are allowed. The directories tests, .venv, __pycache__, dist, .git and .egg-info are not module evidence.
+
+Only the resolved module is parsed. Top-level functions, async functions, classes, Name assignment targets (including annotations), and imported names count as symbols. Re-exports count without importing or following them. Direct class methods include `__init__`. Assignments to lambda/call expressions count as callable or unknown; all other assigned values, including names and attributes, count as data. Definitions nested inside functions or conditional blocks are not collected.
+
+Docs scanned: top-level `*.md` including README.md, and recursive `docs/**/*.md`. Command claims come only from fenced code and inline code spans. Undocumented checks use full text. TOML uses stdlib tomllib on Python 3.11+, with a minimal quoted key/value regex fallback for script tables on older Python (and a simple project-name lookup).
+
+## Differentiation
+
+- **readme-claim-audit** audits pip install names against pyproject and docs flags, links, versions and make targets. This checks whether installed commands resolve to modules, symbols and callables; the rules do not overlap.
+- **api-claim-audit** audits symbols promised in docs code examples. This checks symbols promised in packaging metadata, using similar AST machinery with a different promise source; the rules do not overlap.
+- **dep-claim-audit** audits dependency declarations against imports. This audits entry-point declarations against source.
+- **pip-check, pipdeptree and importlib.metadata checks** inspect an installed environment at runtime. This tool is static and offline and works on a repository that has never been installed.
+- **twine check** validates package metadata for upload; it does not resolve entry-point targets to source symbols.
+
+## Honest limitations
+
+Static scanning misses dynamic symbols created by importlib, module `__getattr__` hooks, exec or eval. An existing symbol still counts even if a failing top-level import prevents actual import. Imported/re-exported names and call-result assignments have unknown runtime callability and pass. Decorators and runtime behavior are not evaluated.
+
+Attribute chains resolve only one class-method step. Further attributes and non-class attributes remain unchecked. setup.cfg and setup.py entry_points are not parsed. The documented-command rule catches only the project's own name, not arbitrary mistyped command names. It examines the first whitespace-separated code token, so shell prompts or wrappers can hide commands. script-undocumented is heuristic: a script documented only outside README/top-level markdown/docs is flagged; use `--ignore script-undocumented`.
+
+The fallback parser supports simple single-line quoted declarations, not full TOML syntax. Invalid TOML (with tomllib), unreadable files and invalid Python syntax produce input-error exit 1. The tool establishes static evidence, not that a built distribution includes the module or that a command will execute successfully.
+
+## Development
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+python3 -m build
+```
+
+MIT licensed.

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

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

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1 @@
+entry_claim_audit

entry_claim_audit-0.1.0/tests/test_audit.py

@@ -0,0 +1,329 @@
+import contextlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+from entry_claim_audit.audit import audit, fallback_metadata
+from entry_claim_audit.cli import main
+
+
+class AuditTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        self.write('pyproject.toml', '[project]\nname="my-tool"\n[project.scripts]\nmytool="pkg.cli:main"\n')
+        self.write('pkg/cli.py', 'def main(): pass\n')
+        self.write('README.md', '`mytool --help`\n')
+
+    def write(self, name, text):
+        path = self.root / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding='utf-8')
+
+    def target(self, target, table='scripts', name='mytool'):
+        self.write('pyproject.toml', '[project]\nname="my-tool"\n[project.' + table + ']\n' + name + '=' + json.dumps(target) + '\n')
+
+    def check(self, rule=None, severity=None, **kwargs):
+        result = audit(self.root, **kwargs)
+        self.assertEqual([f['rule'] for f in result['findings']], [rule] if rule else [])
+        if severity:
+            self.assertEqual(result['findings'][0]['severity'], severity)
+        return result
+
+    def cli(self, *args):
+        output = io.StringIO()
+        with contextlib.redirect_stdout(output):
+            code = main([str(self.root), *args])
+        return code, output.getvalue()
+
+    def test_good(self):
+        self.assertEqual(self.check()['status'], 'PASS')
+
+    def test_good_cli(self):
+        self.assertEqual(self.cli()[0], 0)
+
+    def test_verified(self):
+        self.assertEqual(self.check()['verified_scripts'], [dict(script='mytool', table='scripts', target='pkg.cli:main')])
+
+    def test_missing_module(self):
+        self.target('pkg.nosuch:main')
+        self.check('script-target-module-missing', 'HIGH')
+        self.assertEqual(self.cli()[0], 2)
+
+    def test_missing_symbol(self):
+        self.write('pkg/cli.py', 'other = 1')
+        self.check('script-target-symbol-missing', 'HIGH')
+
+    def test_constant(self):
+        self.write('pkg/cli.py', 'main = 42')
+        self.assertEqual(self.check('script-target-not-callable', 'MEDIUM')['status'], 'FAIL')
+
+    def test_high_threshold(self):
+        self.write('pkg/cli.py', 'main = 42')
+        self.assertEqual(self.check('script-target-not-callable', fail_on='HIGH')['status'], 'PASS')
+        self.assertEqual(self.cli('--fail-on', 'HIGH')[0], 0)
+
+    def test_no_colon(self):
+        self.target('pkg.cli.main')
+        self.check('script-target-malformed', 'HIGH')
+
+    def test_empty_module(self):
+        self.target(':main')
+        self.check('script-target-malformed')
+
+    def test_empty_object(self):
+        self.target('pkg.cli:')
+        self.check('script-target-malformed')
+
+    def test_internal_space(self):
+        self.target('pkg.cli:ma in')
+        self.check('script-target-malformed')
+
+    def test_surrounding_space(self):
+        self.target('  pkg.cli:main  ')
+        self.check()
+
+    def test_double_colon(self):
+        self.target('pkg.cli::main')
+        self.check('script-target-malformed')
+
+    def test_invalid_dotted(self):
+        self.target('pkg..cli:main')
+        self.check('script-target-malformed')
+
+    def test_attr_missing(self):
+        self.write('pkg/cli.py', 'class Runner: pass')
+        self.target('pkg.cli:Runner.run')
+        self.check('script-target-attr-missing', 'HIGH')
+
+    def test_attr_present(self):
+        self.write('pkg/cli.py', 'class Runner:\n    def run(self): pass')
+        self.target('pkg.cli:Runner.run')
+        self.check()
+
+    def test_deep_attr(self):
+        self.write('pkg/cli.py', 'class Runner:\n    def run(self): pass')
+        self.target('pkg.cli:Runner.run.unknown')
+        self.check()
+
+    def test_function_attr(self):
+        self.target('pkg.cli:main.unknown')
+        self.check()
+
+    def test_class_callable(self):
+        self.write('pkg/cli.py', 'class main: pass')
+        self.check()
+
+    def test_async_callable(self):
+        self.write('pkg/cli.py', 'async def main(): pass')
+        self.check()
+
+    def test_reexport(self):
+        self.write('pkg/__init__.py', 'from .cli import main')
+        self.target('pkg:main')
+        self.check()
+
+    def test_import_alias(self):
+        self.write('pkg/cli.py', 'import nonexistent as main')
+        self.check()
+
+    def test_import_name(self):
+        self.write('pkg/cli.py', 'import main.submodule')
+        self.check()
+
+    def test_lambda(self):
+        self.write('pkg/cli.py', 'main = lambda: None')
+        self.check()
+
+    def test_call(self):
+        self.write('pkg/cli.py', 'main = factory()')
+        self.check()
+
+    def test_name_assignment(self):
+        self.write('pkg/cli.py', 'main = other')
+        self.check('script-target-not-callable')
+
+    def test_attribute_assignment(self):
+        self.write('pkg/cli.py', 'main = other.attr')
+        self.check('script-target-not-callable')
+
+    def test_annotated(self):
+        self.write('pkg/cli.py', 'main: int = 42')
+        self.check('script-target-not-callable')
+
+    def test_tests_only(self):
+        self.write('tests/cli.py', 'def main(): pass')
+        self.target('tests.cli:main')
+        self.check('script-target-module-missing', 'HIGH')
+
+    def test_src_module(self):
+        (self.root / 'pkg/cli.py').unlink()
+        self.write('src/pkg/cli.py', 'def main(): pass')
+        self.check()
+
+    def test_src_package(self):
+        self.write('src/other/__init__.py', 'def main(): pass')
+        self.target('other:main')
+        self.check()
+
+    def test_flat_single(self):
+        self.write('single.py', 'def main(): pass')
+        self.target('single:main')
+        self.check()
+
+    def test_src_single(self):
+        self.write('src/single.py', 'def main(): pass')
+        self.target('single:main')
+        self.check()
+
+    def test_nested_package(self):
+        self.write('pkg/sub/__init__.py', 'def main(): pass')
+        self.target('pkg.sub:main')
+        self.check()
+
+    def test_documented_missing(self):
+        self.write('README.md', 'mytool\n```sh\nmy-tool --help\n```')
+        self.check('documented-command-missing', 'HIGH')
+
+    def test_documented_inline(self):
+        self.write('README.md', 'mytool and `my-tool --help`')
+        self.check('documented-command-missing')
+
+    def test_normalized_name(self):
+        self.write('README.md', 'mytool and `MY_TOOL --help`')
+        self.check('documented-command-missing')
+
+    def test_prose_no_command(self):
+        self.write('README.md', 'mytool my-tool --help')
+        self.check()
+
+    def test_arbitrary_command(self):
+        self.write('README.md', 'mytool `pip install x` `git status`')
+        self.check()
+
+    def test_undocumented(self):
+        self.write('README.md', 'Nothing here')
+        self.check('script-undocumented', 'MEDIUM')
+
+    def test_docsless(self):
+        (self.root / 'README.md').unlink()
+        self.check()
+
+    def test_duplicate(self):
+        self.write('pyproject.toml', '[project.scripts]\nmytool="pkg.cli:main"\n[project.gui-scripts]\nmytool="pkg.cli:main"')
+        self.check('script-name-duplicate', 'MEDIUM')
+
+    def test_gui_bad(self):
+        self.target('pkg.nosuch:main', 'gui-scripts')
+        self.check('script-target-module-missing', 'HIGH')
+
+    def test_gui_good(self):
+        self.target('pkg.cli:main', 'gui-scripts')
+        self.check()
+
+    def test_no_scripts(self):
+        self.write('pyproject.toml', '[project]\nname="library"')
+        self.check()
+        self.assertEqual(self.cli()[0], 0)
+
+    def test_no_pyproject(self):
+        (self.root / 'pyproject.toml').unlink()
+        self.check()
+        self.assertEqual(self.cli()[0], 0)
+
+    def test_no_project(self):
+        self.write('pyproject.toml', '[tool.example]\na=1')
+        self.check()
+
+    def test_ignore(self):
+        self.target('missing:main')
+        self.check(ignore=['script-target-module-missing'])
+        self.assertEqual(self.cli('--ignore', 'script-target-module-missing')[0], 0)
+
+    def test_json_sorted(self):
+        self.target('missing:main')
+        self.write('README.md', '`my-tool --help`')
+        code, output = self.cli('--json')
+        result = json.loads(output)
+        self.assertEqual(code, 2)
+        self.assertEqual(result['findings'], sorted(result['findings'], key=lambda f: (f['rule'], f['file'], f['line'])))
+        self.assertEqual(output, self.cli('--json')[1])
+
+    def test_version(self):
+        with self.assertRaises(SystemExit) as caught:
+            with contextlib.redirect_stdout(io.StringIO()) as output:
+                main(['--version'])
+        self.assertEqual(caught.exception.code, 0)
+        self.assertEqual(output.getvalue().strip(), '0.1.0')
+
+    def test_usage_error(self):
+        with self.assertRaises(SystemExit) as caught:
+            with contextlib.redirect_stderr(io.StringIO()):
+                main(['--fail-on', 'LOW'])
+        self.assertEqual(caught.exception.code, 1)
+
+    def test_nested_doc(self):
+        self.write('README.md', 'Introduction')
+        self.write('docs/deep/usage.md', '`mytool --help`')
+        self.check()
+
+    def test_whole_word(self):
+        self.write('README.md', 'mytools')
+        self.check('script-undocumented')
+
+    def test_no_execution(self):
+        self.write('pkg/cli.py', 'raise RuntimeError()\ndef main(): pass')
+        self.check()
+
+    def test_nested_symbol_excluded(self):
+        self.write('pkg/cli.py', 'def outer():\n    def main(): pass')
+        self.check('script-target-symbol-missing')
+
+    def test_fallback(self):
+        with patch('entry_claim_audit.audit.tomllib', None):
+            self.check()
+
+    def test_fallback_gui(self):
+        self.target('pkg.cli:main', 'gui-scripts')
+        with patch('entry_claim_audit.audit.tomllib', None):
+            self.check()
+
+    def test_invalid_toml(self):
+        self.write('pyproject.toml', '[broken')
+        with self.assertRaises(SystemExit) as caught:
+            with contextlib.redirect_stderr(io.StringIO()):
+                self.cli()
+        self.assertEqual(caught.exception.code, 1)
+
+    def test_verbose(self):
+        self.assertIn('verified mytool', self.cli('--verbose')[1])
+
+    def test_tilde_fence(self):
+        self.write('README.md', 'mytool\n~~~sh\nmy-tool --help\n~~~')
+        self.check('documented-command-missing')
+
+    def test_no_scripts_with_project_command(self):
+        self.write('pyproject.toml', '[project]\nname="my-tool"')
+        self.write('README.md', '`my-tool --help`')
+        self.check()
+
+    def test_env_never_read(self):
+        self.write('.env', 'placeholder only')
+        original = Path.read_text
+        def guarded(path, *args, **kwargs):
+            self.assertNotEqual(path.name, '.env')
+            return original(path, *args, **kwargs)
+        with patch.object(Path, 'read_text', guarded):
+            self.check()
+
+    def test_dist_not_evidence(self):
+        self.write('dist/cli.py', 'def main(): pass')
+        self.target('dist.cli:main')
+        self.check('script-target-module-missing')
+
+
+if __name__ == '__main__':
+    unittest.main()