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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2 @@
1
+ """Static documentation and source auditing."""
2
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,176 @@
1
+ """Offline AST and Markdown auditing; source is never executed."""
2
+ import argparse
3
+ import ast
4
+ import fnmatch
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ import re
9
+ import sys
10
+
11
+ from . import __version__
12
+
13
+ PLUGIN = (
14
+ 'plugin support', 'supports plugins', 'supports plugin', 'plugin system',
15
+ 'plugins supported', 'plugin supported', 'third party plugins',
16
+ 'third party plugin', 'custom plugins', 'custom plugin', 'plugin api',
17
+ 'plugin architecture', 'plugin framework', 'plugin based', 'plugin model',
18
+ 'extensible through plugins', 'extensible via plugins',
19
+ 'extensible with plugins', 'extendable with plugins',
20
+ 'extendable through plugins', 'extend with plugins', 'write plugins',
21
+ 'write your own plugin', 'write your own plugins', 'install plugins',
22
+ 'install third party plugins', 'load plugins', 'loads plugins',
23
+ 'loading plugins', 'plugin discovery', 'discovers plugins',
24
+ 'pluggable architecture', 'pluggable system', 'supports third party extensions',
25
+ )
26
+ NOPLUGIN = (
27
+ 'no plugin support', 'does not support plugins', 'does not support plugin',
28
+ 'no plugins', 'no plugin system', 'plugins are not supported',
29
+ 'plugin support is not available', 'not extensible', 'not extendable',
30
+ 'cannot be extended', 'no third party plugins', 'no custom plugins',
31
+ 'does not load plugins', 'no plugin api',
32
+ )
33
+
34
+
35
+ def pattern(phrases):
36
+ return re.compile(r'\b(?:' + '|'.join(re.escape(p) for p in sorted(phrases, key=len, reverse=True)) + r')\b')
37
+
38
+
39
+ def doc_claims(text):
40
+ lines = []
41
+ fence = None
42
+ for line in text.splitlines():
43
+ match = re.match(r'^\s{0,3}(`{3,}|~{3,})', line)
44
+ if fence:
45
+ if re.match(r'^\s{0,3}' + re.escape(fence[0]) + '{' + str(len(fence)) + r',}\s*$', line):
46
+ fence = None
47
+ continue
48
+ if match:
49
+ fence = match.group(1)
50
+ lines.append('')
51
+ else:
52
+ lines.append(line)
53
+ result = set()
54
+ for paragraph in re.split(r'\n\s*\n', '\n'.join(lines)):
55
+ normal = re.sub(r'\s+', ' ', paragraph.lower().replace('-', ' '))
56
+ if pattern(NOPLUGIN).search(normal):
57
+ result.add('NOPLUGIN')
58
+ normal = pattern(NOPLUGIN).sub(' ', normal)
59
+ if pattern(PLUGIN).search(normal):
60
+ result.add('PLUGIN')
61
+ return result
62
+
63
+
64
+ def evidence_kinds(source, filename):
65
+ tree = ast.parse(source, filename=filename)
66
+ aliases = {}
67
+ pluggy = False
68
+ for node in ast.walk(tree):
69
+ if isinstance(node, ast.Import):
70
+ for alias in node.names:
71
+ aliases[alias.asname or alias.name.split('.')[0]] = alias.name if alias.asname else alias.name.split('.')[0]
72
+ pluggy |= alias.name == 'pluggy'
73
+ elif isinstance(node, ast.ImportFrom):
74
+ pluggy |= node.module == 'pluggy'
75
+ for alias in node.names:
76
+ aliases[alias.asname or alias.name] = (node.module or '') + '.' + alias.name
77
+
78
+ def dotted(node):
79
+ if isinstance(node, ast.Name):
80
+ return aliases.get(node.id, node.id)
81
+ if isinstance(node, ast.Attribute):
82
+ return dotted(node.value) + '.' + node.attr
83
+ if isinstance(node, ast.Call):
84
+ return dotted(node.func)
85
+ return ''
86
+
87
+ calls = [n for n in ast.walk(tree) if isinstance(n, ast.Call)]
88
+ names = [dotted(n.func) for n in calls]
89
+ attr = lambda name: any(isinstance(n.func, ast.Attribute) and n.func.attr == name for n in calls)
90
+ dynamic = any(dotted(n.func) == 'importlib.import_module' and n.args and not (isinstance(n.args[0], ast.Constant) and isinstance(n.args[0].value, str)) for n in calls)
91
+ imported = 'importlib.import_module' in names
92
+ scans = {'os.listdir', 'os.scandir', 'glob.glob', 'glob.iglob', 'pathlib.Path.glob', 'pathlib.Path.iterdir'}
93
+ scan = False
94
+ registry = False
95
+ for n in calls:
96
+ if dotted(n.func) in scans:
97
+ # Include the Path constructor receiver as well as explicit arguments.
98
+ scan |= any(isinstance(c, ast.Constant) and isinstance(c.value, str) and 'plugin' in c.value.lower() for c in ast.walk(n))
99
+ if isinstance(n.func, ast.Attribute) and n.func.attr in {'append', 'register', 'add'}:
100
+ registry |= isinstance(n.func.value, ast.Attribute) and n.func.value.attr in {'plugins', 'registry'}
101
+ for n in ast.walk(tree):
102
+ targets = n.targets if isinstance(n, ast.Assign) else [n.target] if isinstance(n, (ast.AnnAssign, ast.AugAssign)) else []
103
+ for target in targets:
104
+ for t in ast.walk(target):
105
+ if isinstance(t, ast.Subscript) and 'plugin' in dotted(t.value).lower():
106
+ registry = True
107
+ result = []
108
+ if 'importlib.metadata.entry_points' in names and attr('load'):
109
+ result.append('entry-points')
110
+ if pluggy and any(n.endswith('PluginManager') for n in names) and attr('register'):
111
+ result.append('pluggy')
112
+ if any(n in {'stevedore.extension.ExtensionManager', 'stevedore.driver.DriverManager', 'stevedore.ExtensionManager', 'stevedore.DriverManager'} for n in names):
113
+ result.append('stevedore')
114
+ if scan and dynamic:
115
+ result.append('directory')
116
+ if registry and imported:
117
+ result.append('registry')
118
+ return result
119
+
120
+
121
+ def audit(root, ignores=()):
122
+ root = Path(root)
123
+ if not root.is_dir():
124
+ raise ValueError('ROOT must be a directory')
125
+ claims, evidence = [], []
126
+ def walk_error(error):
127
+ raise error
128
+ for directory, dirs, files in os.walk(root, followlinks=False, onerror=walk_error):
129
+ dirs[:] = sorted(d for d in dirs if not Path(directory, d).is_symlink() and not any(fnmatch.fnmatchcase(Path(directory, d).relative_to(root).as_posix(), g) for g in ignores))
130
+ for name in sorted(files):
131
+ path = Path(directory, name)
132
+ rel = path.relative_to(root)
133
+ posix = rel.as_posix()
134
+ if path.is_symlink() or name == '.env' or any(fnmatch.fnmatchcase(posix, g) for g in ignores):
135
+ continue
136
+ if (posix == 'README.md' or ('docs' in rel.parts[:-1] and path.suffix.lower() == '.md')):
137
+ for family in sorted(doc_claims(path.read_text(encoding='utf-8'))):
138
+ claims.append({'family': family, 'path': posix})
139
+ if path.suffix == '.py' and 'tests' not in rel.parts and not name.startswith('test_'):
140
+ for kind in evidence_kinds(path.read_text(encoding='utf-8'), posix):
141
+ evidence.append({'kind': kind, 'path': posix})
142
+ findings = []
143
+ for family, false in [('PLUGIN', not evidence), ('NOPLUGIN', bool(evidence))]:
144
+ candidates = [c for c in claims if c['family'] == family]
145
+ if false and candidates:
146
+ chosen = min(candidates, key=lambda c: ('tests' in Path(c['path']).parts, c['path']))
147
+ findings.append({'rule': 'documented-' + ('plugin' if family == 'PLUGIN' else 'no-plugin') + '-claim-false', 'severity': 'MEDIUM' if 'tests' in Path(chosen['path']).parts else 'HIGH', 'path': chosen['path']})
148
+ return {'status': 'FAIL' if findings else 'PASS', 'evidence': evidence, 'claims': claims, 'findings': findings}
149
+
150
+
151
+ class Parser(argparse.ArgumentParser):
152
+ def error(self, message):
153
+ raise ValueError(message)
154
+
155
+
156
+ def main(argv=None):
157
+ parser = Parser(prog='plugin-claim-audit')
158
+ parser.add_argument('root', nargs='?', default='.')
159
+ parser.add_argument('--json', action='store_true')
160
+ parser.add_argument('--verbose', action='store_true')
161
+ parser.add_argument('--ignore', nargs='+', action='extend', default=[])
162
+ parser.add_argument('--fail-on', choices=['HIGH', 'MEDIUM'], default='MEDIUM')
163
+ parser.add_argument('--version', action='version', version=__version__)
164
+ try:
165
+ args = parser.parse_args(argv)
166
+ result = audit(args.root, args.ignore)
167
+ if args.json:
168
+ print(json.dumps(result))
169
+ else:
170
+ print(result['status'])
171
+ for f in result['findings']:
172
+ print(f['rule'], f['severity'], *([f['path']] if args.verbose else []))
173
+ return 2 if any(f['severity'] == 'HIGH' or args.fail_on == 'MEDIUM' for f in result['findings']) else 0
174
+ except (ValueError, OSError, SyntaxError, UnicodeError) as exc:
175
+ print('error: ' + str(exc), file=sys.stderr)
176
+ return 1
@@ -0,0 +1,111 @@
1
+ Metadata-Version: 2.4
2
+ Name: plugin-claim-audit
3
+ Version: 0.1.0
4
+ Summary: An offline static audit of documented third-party extensibility promises
5
+ License-Expression: MIT
6
+ Requires-Python: >=3.9
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Dynamic: license-file
10
+
11
+ # plugin-claim-audit
12
+
13
+ An offline static audit of documented third-party extensibility promises.
14
+ Version 0.1.0. Requires Python 3.9 or later; runtime dependencies are limited
15
+ to the Python standard library. Licensed under MIT.
16
+
17
+ Install with `python3 -m pip install .` and run:
18
+
19
+ ```sh
20
+ plugin-claim-audit [ROOT] --json --verbose --ignore 'vendor/*' --fail-on HIGH
21
+ python3 -m plugin_claim_audit .
22
+ ```
23
+
24
+ ROOT defaults to the current directory. Output is text or JSON with `status`,
25
+ `evidence`, `claims`, and `findings`. Text lists rule and severity; verbose
26
+ mode adds the relative path. Exit codes are 0 for success at the selected
27
+ threshold, 2 for findings at that threshold, and 1 for input or usage errors.
28
+ The default threshold is MEDIUM; HIGH still reports lower severity findings.
29
+ `--version` prints the version. `--ignore` accepts one or more POSIX relative
30
+ path globs and can be repeated.
31
+
32
+ The scanner reads root README.md and Markdown files beneath any docs path
33
+ component. It excludes fenced blocks, counts inline code, joins lines within
34
+ paragraphs, normalizes case and hyphens, and matches exact phrases at word
35
+ boundaries. Negative spans are removed before positive matching. One finding
36
+ per family is emitted, preferring a document outside tests. Documents beneath
37
+ tests produce MEDIUM findings; other documents produce HIGH findings.
38
+
39
+ Python files are parsed with AST without execution. Files beneath tests and
40
+ files whose names start with test_ are excluded. Symlinks are skipped and
41
+ .env files are never opened. Unreadable inputs and invalid Python are errors.
42
+
43
+ Evidence requires calls in the same module: metadata discovery paired with
44
+ loading, a Pluggy manager paired with registration, a Stevedore manager,
45
+ a directory scan containing a relevant literal paired with a variable module
46
+ import, or registry mutation paired with a module import. Ordinary import
47
+ aliases are resolved. Packaging declarations, fixed imports alone, comments,
48
+ and docstrings do not constitute evidence. This is a static heuristic: it does
49
+ not prove runtime reachability, data flow, or successful execution.
50
+
51
+ With no source, positive promises produce a finding and negative promises
52
+ pass. With no documented promise, the audit passes regardless of source.
53
+
54
+ The complete phrase vocabulary follows:
55
+
56
+ ```text
57
+ PLUGIN
58
+ plugin support
59
+ supports plugins
60
+ supports plugin
61
+ plugin system
62
+ plugins supported
63
+ plugin supported
64
+ third party plugins
65
+ third party plugin
66
+ custom plugins
67
+ custom plugin
68
+ plugin api
69
+ plugin architecture
70
+ plugin framework
71
+ plugin based
72
+ plugin model
73
+ extensible through plugins
74
+ extensible via plugins
75
+ extensible with plugins
76
+ extendable with plugins
77
+ extendable through plugins
78
+ extend with plugins
79
+ write plugins
80
+ write your own plugin
81
+ write your own plugins
82
+ install plugins
83
+ install third party plugins
84
+ load plugins
85
+ loads plugins
86
+ loading plugins
87
+ plugin discovery
88
+ discovers plugins
89
+ pluggable architecture
90
+ pluggable system
91
+ supports third party extensions
92
+
93
+ NOPLUGIN
94
+ no plugin support
95
+ does not support plugins
96
+ does not support plugin
97
+ no plugins
98
+ no plugin system
99
+ plugins are not supported
100
+ plugin support is not available
101
+ not extensible
102
+ not extendable
103
+ cannot be extended
104
+ no third party plugins
105
+ no custom plugins
106
+ does not load plugins
107
+ no plugin api
108
+ ```
109
+
110
+ Run tests with `python3 -m unittest discover`. Build distributions with
111
+ `python3 -m build` (requires the build frontend).
@@ -0,0 +1,9 @@
1
+ plugin_claim_audit/__init__.py,sha256=rCKAQhCqIjkGCHEPFQe2iujh7Z4BeOnqJ4vAYsEhNrA,70
2
+ plugin_claim_audit/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
3
+ plugin_claim_audit/cli.py,sha256=wpi9JICI7DSNkP5xspcKV8yNxKCAEbdcU4cT9Uq9fLg,8331
4
+ plugin_claim_audit-0.1.0.dist-info/licenses/LICENSE,sha256=-jHJSf_o65zcfnMYsfFuESxtWKR99Uk6cT6KtTWD8uw,1088
5
+ plugin_claim_audit-0.1.0.dist-info/METADATA,sha256=fUQYB4yec4wHKtVvXEs85aq5JrfLSEE03JLWvwnua_M,3630
6
+ plugin_claim_audit-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
7
+ plugin_claim_audit-0.1.0.dist-info/entry_points.txt,sha256=rrRwU7vkHkqx_iuFbrd14-EJA4aK531yu9Zyy1j1Tr4,67
8
+ plugin_claim_audit-0.1.0.dist-info/top_level.txt,sha256=okqMkwgKLnWXmbzf91lUhiJ2cqX9rjDNa952VBEOVKU,19
9
+ plugin_claim_audit-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ plugin-claim-audit = plugin_claim_audit.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 plugin-claim-audit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ plugin_claim_audit