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.
- plugin_claim_audit/__init__.py +2 -0
- plugin_claim_audit/__main__.py +3 -0
- plugin_claim_audit/cli.py +176 -0
- plugin_claim_audit-0.1.0.dist-info/METADATA +111 -0
- plugin_claim_audit-0.1.0.dist-info/RECORD +9 -0
- plugin_claim_audit-0.1.0.dist-info/WHEEL +5 -0
- plugin_claim_audit-0.1.0.dist-info/entry_points.txt +2 -0
- plugin_claim_audit-0.1.0.dist-info/licenses/LICENSE +21 -0
- plugin_claim_audit-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -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,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
|