plugin-claim-audit 0.1.0__tar.gz

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,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,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,101 @@
1
+ # plugin-claim-audit
2
+
3
+ An offline static audit of documented third-party extensibility promises.
4
+ Version 0.1.0. Requires Python 3.9 or later; runtime dependencies are limited
5
+ to the Python standard library. Licensed under MIT.
6
+
7
+ Install with `python3 -m pip install .` and run:
8
+
9
+ ```sh
10
+ plugin-claim-audit [ROOT] --json --verbose --ignore 'vendor/*' --fail-on HIGH
11
+ python3 -m plugin_claim_audit .
12
+ ```
13
+
14
+ ROOT defaults to the current directory. Output is text or JSON with `status`,
15
+ `evidence`, `claims`, and `findings`. Text lists rule and severity; verbose
16
+ mode adds the relative path. Exit codes are 0 for success at the selected
17
+ threshold, 2 for findings at that threshold, and 1 for input or usage errors.
18
+ The default threshold is MEDIUM; HIGH still reports lower severity findings.
19
+ `--version` prints the version. `--ignore` accepts one or more POSIX relative
20
+ path globs and can be repeated.
21
+
22
+ The scanner reads root README.md and Markdown files beneath any docs path
23
+ component. It excludes fenced blocks, counts inline code, joins lines within
24
+ paragraphs, normalizes case and hyphens, and matches exact phrases at word
25
+ boundaries. Negative spans are removed before positive matching. One finding
26
+ per family is emitted, preferring a document outside tests. Documents beneath
27
+ tests produce MEDIUM findings; other documents produce HIGH findings.
28
+
29
+ Python files are parsed with AST without execution. Files beneath tests and
30
+ files whose names start with test_ are excluded. Symlinks are skipped and
31
+ .env files are never opened. Unreadable inputs and invalid Python are errors.
32
+
33
+ Evidence requires calls in the same module: metadata discovery paired with
34
+ loading, a Pluggy manager paired with registration, a Stevedore manager,
35
+ a directory scan containing a relevant literal paired with a variable module
36
+ import, or registry mutation paired with a module import. Ordinary import
37
+ aliases are resolved. Packaging declarations, fixed imports alone, comments,
38
+ and docstrings do not constitute evidence. This is a static heuristic: it does
39
+ not prove runtime reachability, data flow, or successful execution.
40
+
41
+ With no source, positive promises produce a finding and negative promises
42
+ pass. With no documented promise, the audit passes regardless of source.
43
+
44
+ The complete phrase vocabulary follows:
45
+
46
+ ```text
47
+ PLUGIN
48
+ plugin support
49
+ supports plugins
50
+ supports plugin
51
+ plugin system
52
+ plugins supported
53
+ plugin supported
54
+ third party plugins
55
+ third party plugin
56
+ custom plugins
57
+ custom plugin
58
+ plugin api
59
+ plugin architecture
60
+ plugin framework
61
+ plugin based
62
+ plugin model
63
+ extensible through plugins
64
+ extensible via plugins
65
+ extensible with plugins
66
+ extendable with plugins
67
+ extendable through plugins
68
+ extend with plugins
69
+ write plugins
70
+ write your own plugin
71
+ write your own plugins
72
+ install plugins
73
+ install third party plugins
74
+ load plugins
75
+ loads plugins
76
+ loading plugins
77
+ plugin discovery
78
+ discovers plugins
79
+ pluggable architecture
80
+ pluggable system
81
+ supports third party extensions
82
+
83
+ NOPLUGIN
84
+ no plugin support
85
+ does not support plugins
86
+ does not support plugin
87
+ no plugins
88
+ no plugin system
89
+ plugins are not supported
90
+ plugin support is not available
91
+ not extensible
92
+ not extendable
93
+ cannot be extended
94
+ no third party plugins
95
+ no custom plugins
96
+ does not load plugins
97
+ no plugin api
98
+ ```
99
+
100
+ Run tests with `python3 -m unittest discover`. Build distributions with
101
+ `python3 -m build` (requires the build frontend).
@@ -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,12 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ plugin_claim_audit/__init__.py
5
+ plugin_claim_audit/__main__.py
6
+ plugin_claim_audit/cli.py
7
+ plugin_claim_audit.egg-info/PKG-INFO
8
+ plugin_claim_audit.egg-info/SOURCES.txt
9
+ plugin_claim_audit.egg-info/dependency_links.txt
10
+ plugin_claim_audit.egg-info/entry_points.txt
11
+ plugin_claim_audit.egg-info/top_level.txt
12
+ tests/test_audit.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ plugin-claim-audit = plugin_claim_audit.cli:main
@@ -0,0 +1 @@
1
+ plugin_claim_audit
@@ -0,0 +1,17 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "plugin-claim-audit"
7
+ version = "0.1.0"
8
+ description = "An offline static audit of documented third-party extensibility promises"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+
13
+ [project.scripts]
14
+ plugin-claim-audit = "plugin_claim_audit.cli:main"
15
+
16
+ [tool.setuptools.packages.find]
17
+ include = ["plugin_claim_audit*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,243 @@
1
+ import contextlib
2
+ import io
3
+ import json
4
+ from pathlib import Path
5
+ import subprocess
6
+ import sys
7
+ import tempfile
8
+ import unittest
9
+ from unittest.mock import patch
10
+
11
+ from plugin_claim_audit.cli import audit, doc_claims, main, PLUGIN, NOPLUGIN
12
+
13
+ ROOT = Path(__file__).resolve().parents[1]
14
+ GOOD = [
15
+ 'import importlib.metadata as md\neps = md.entry_points()\nfor ep in eps: ep.load()',
16
+ 'import pluggy as pg\npm = pg.PluginManager("x")\npm.register(object())',
17
+ 'from stevedore import ExtensionManager\nExtensionManager("x")',
18
+ 'import os as o\nfrom importlib import import_module as load\nfor name in o.listdir("plugins/"): load(name)',
19
+ 'import importlib\nPLUGINS[name] = importlib.import_module("fixed")',
20
+ ]
21
+
22
+
23
+ class AuditTests(unittest.TestCase):
24
+ def setUp(self):
25
+ self.temp = tempfile.TemporaryDirectory(dir=str(ROOT / 'tests'))
26
+ self.addCleanup(self.temp.cleanup)
27
+ self.root = Path(self.temp.name)
28
+
29
+ def write(self, path, content):
30
+ target = self.root / path
31
+ target.parent.mkdir(parents=True, exist_ok=True)
32
+ target.write_text(content, encoding='utf-8')
33
+ return target
34
+
35
+ def cli(self, *args):
36
+ out, err = io.StringIO(), io.StringIO()
37
+ with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
38
+ code = main([str(self.root)] + list(args))
39
+ return code, out.getvalue(), err.getvalue()
40
+
41
+ def test_01_each_evidence_kind(self):
42
+ self.write('README.md', 'supports plugins')
43
+ for source in GOOD:
44
+ with self.subTest(source=source):
45
+ self.write('loader.py', source)
46
+ self.assertEqual(self.cli()[0], 0)
47
+ self.assertTrue(audit(self.root)['evidence'])
48
+
49
+ def test_02_false_positive_claim(self):
50
+ self.write('README.md', 'plugin support')
51
+ self.write('app.py', 'x = 1')
52
+ code, out, _ = self.cli('--json')
53
+ self.assertEqual(code, 2)
54
+ self.assertEqual(json.loads(out)['findings'], [{'rule': 'documented-plugin-claim-false', 'severity': 'HIGH', 'path': 'README.md'}])
55
+
56
+ def test_03_false_negative_claim(self):
57
+ self.write('README.md', 'no plugins')
58
+ self.write('loader.py', GOOD[0])
59
+ code, out, _ = self.cli('--json')
60
+ self.assertEqual(code, 2)
61
+ self.assertEqual(json.loads(out)['findings'], [{'rule': 'documented-no-plugin-claim-false', 'severity': 'HIGH', 'path': 'README.md'}])
62
+
63
+ def test_04_no_source_asymmetry(self):
64
+ self.write('README.md', 'supports plugins')
65
+ self.assertEqual(audit(self.root)['findings'][0]['severity'], 'HIGH')
66
+ self.write('README.md', 'no plugins')
67
+ self.assertEqual(self.cli()[0], 0)
68
+
69
+ def test_05_fenced_inline_wrapped(self):
70
+ for content in ['```text\nplugin support\n```', '~~~\nplugin support\n~~~']:
71
+ self.write('README.md', content)
72
+ self.assertEqual(audit(self.root)['claims'], [])
73
+ for content in ['`plugin support`', 'plugin\nsupport', 'PLUGIN-SUPPORT']:
74
+ self.write('README.md', content)
75
+ self.assertEqual(self.cli()[0], 2)
76
+ self.write('README.md', 'plugin\n\nsupport')
77
+ self.assertEqual(self.cli()[0], 0)
78
+
79
+ def test_06_span_removal(self):
80
+ for phrase in ['does not support plugins', 'no plugin support']:
81
+ self.assertEqual(doc_claims(phrase), {'NOPLUGIN'})
82
+ self.write('README.md', phrase)
83
+ self.assertEqual(self.cli()[0], 0)
84
+ self.write('loader.py', GOOD[0])
85
+ self.assertEqual([f['rule'] for f in audit(self.root)['findings']], ['documented-no-plugin-claim-false'])
86
+ (self.root / 'loader.py').unlink()
87
+
88
+ def test_07_bare_nouns_and_boundaries(self):
89
+ for text in ['the plugin handles requests', 'extensions are welcome', 'plugins extension extensible pluggable', 'plugin models', 'supports pluginsXYZ']:
90
+ self.assertEqual(doc_claims(text), set())
91
+
92
+ def test_08_not_evidence(self):
93
+ variants = [
94
+ 'import pluggy',
95
+ 'from importlib.metadata import entry_points\nentry_points()',
96
+ 'ep.load()',
97
+ 'import importlib\nimportlib.import_module("fixed")',
98
+ 'import os, importlib\nos.listdir("modules")\nimportlib.import_module(name)',
99
+ 'plugins = {}',
100
+ 'class PluginBase: pass',
101
+ 'import stevedore',
102
+ 'import importlib.metadata',
103
+ '# ep.load()\nx = "importlib.metadata.entry_points()"',
104
+ 'def plugin_loader(): pass',
105
+ 'self.plugins = []\nimport importlib\nimportlib.import_module("fixed")',
106
+ ]
107
+ self.write('README.md', 'plugin support')
108
+ for source in variants:
109
+ with self.subTest(source=source):
110
+ self.write('app.py', source)
111
+ self.assertFalse(audit(self.root)['evidence'])
112
+ self.assertEqual(self.cli()[0], 2)
113
+
114
+ def test_08_entry_disjointness(self):
115
+ self.write('README.md', 'plugin support')
116
+ self.write('pyproject.toml', '[project.scripts]\napp = "app:main"\n[project.entry-points."host.plugins"]\napp = "app:main"\n')
117
+ self.assertEqual(self.cli()[0], 2)
118
+ self.assertEqual(audit(self.root)['evidence'], [])
119
+
120
+ def test_08_pairing_cannot_cross_modules(self):
121
+ self.write('README.md', 'plugin support')
122
+ self.write('discover.py', 'from importlib.metadata import entry_points\nentry_points()')
123
+ self.write('load.py', 'ep.load()')
124
+ self.assertEqual(self.cli()[0], 2)
125
+
126
+ def test_09_medium_threshold(self):
127
+ self.write('tests/docs/guide.md', 'plugin support')
128
+ self.assertEqual(audit(self.root)['findings'][0]['severity'], 'MEDIUM')
129
+ self.assertEqual(self.cli()[0], 2)
130
+ code, out, _ = self.cli('--fail-on', 'HIGH', '--json')
131
+ self.assertEqual(code, 0)
132
+ self.assertEqual(len(json.loads(out)['findings']), 1)
133
+
134
+ def test_10_family_dedup_prefers_high(self):
135
+ self.write('tests/docs/guide.md', 'plugin support')
136
+ self.write('docs/z.md', 'plugin support')
137
+ self.write('docs/a.md', 'supports plugins')
138
+ findings = audit(self.root)['findings']
139
+ self.assertEqual(len(findings), 1)
140
+ self.assertEqual(findings[0]['path'], 'docs/a.md')
141
+ self.assertEqual(findings[0]['severity'], 'HIGH')
142
+
143
+ def test_11_cli_version_and_json(self):
144
+ out = io.StringIO()
145
+ with contextlib.redirect_stdout(out), self.assertRaises(SystemExit) as raised:
146
+ main(['--version'])
147
+ self.assertEqual(raised.exception.code, 0)
148
+ self.assertEqual(out.getvalue().strip(), '0.1.0')
149
+ code, out, _ = self.cli('--json')
150
+ self.assertEqual(code, 0)
151
+ self.assertEqual(set(json.loads(out)), {'status', 'claims', 'evidence', 'findings'})
152
+
153
+ def test_11_errors(self):
154
+ for args in [['missing'], ['--bogus'], ['--fail-on', 'LOW']]:
155
+ with contextlib.redirect_stderr(io.StringIO()):
156
+ self.assertEqual(main(args), 1)
157
+ self.write('bad.py', 'def !!!')
158
+ self.assertEqual(self.cli()[0], 1)
159
+ (self.root / 'bad.py').unlink()
160
+ original = Path.read_text
161
+ def denied(path, *a, **kw):
162
+ if path.name == 'README.md':
163
+ raise PermissionError('denied')
164
+ return original(path, *a, **kw)
165
+ self.write('README.md', '')
166
+ with patch.object(Path, 'read_text', denied):
167
+ self.assertEqual(self.cli()[0], 1)
168
+
169
+ def test_11_ignore_docs_and_evidence(self):
170
+ self.write('README.md', 'plugin support')
171
+ self.write('loader.py', GOOD[0])
172
+ self.assertEqual(self.cli('--ignore', '*.py')[0], 2)
173
+ self.assertEqual(self.cli('--ignore', 'README.md')[0], 0)
174
+ self.assertEqual(audit(self.root, ['README.md'])['claims'], [])
175
+
176
+ def test_11_text_verbose(self):
177
+ self.write('README.md', 'plugin support')
178
+ self.assertEqual(self.cli()[1], 'FAIL\ndocumented-plugin-claim-false HIGH\n')
179
+ self.assertIn('HIGH README.md', self.cli('--verbose')[1])
180
+
181
+ def test_11_module_entrypoint(self):
182
+ result = subprocess.run([sys.executable, '-m', 'plugin_claim_audit', str(self.root)], cwd=ROOT, capture_output=True, text=True)
183
+ self.assertEqual(result.returncode, 0, result.stderr)
184
+ self.assertEqual(result.stdout, 'PASS\n')
185
+
186
+ def test_11_console_declaration(self):
187
+ text = (ROOT / 'pyproject.toml').read_text()
188
+ self.assertIn('plugin-claim-audit = "plugin_claim_audit.cli:main"', text)
189
+
190
+ def test_12_self_audit(self):
191
+ result = audit(ROOT)
192
+ self.assertEqual(result['status'], 'PASS')
193
+ self.assertEqual(result['claims'], [])
194
+
195
+ def test_13_env_never_opened(self):
196
+ marker = 'ENV_GUARD_MARKER plugin support'
197
+ self.write('.env', marker)
198
+ self.write('docs/.env', marker)
199
+ original = Path.open
200
+ def guarded(path, *args, **kwargs):
201
+ if path.name == '.env':
202
+ raise AssertionError('.env opened')
203
+ return original(path, *args, **kwargs)
204
+ with patch.object(Path, 'open', guarded):
205
+ code, out, err = self.cli('--json')
206
+ self.assertEqual(code, 0)
207
+ self.assertNotIn(marker, out + err)
208
+
209
+ def test_aliases_and_additional_evidence_forms(self):
210
+ sources = [
211
+ 'from importlib.metadata import entry_points as eps\neps()\ne.load()',
212
+ 'from stevedore.driver import DriverManager as DM\nDM("x")',
213
+ 'import pathlib as p, importlib as i\np.Path("plugins").iterdir()\ni.import_module(name)',
214
+ 'from pathlib import Path as P\nfrom importlib import import_module\nP(".").glob("plugins/*.py")\nimport_module(name)',
215
+ 'import glob, importlib\nglob.iglob("plugins/*")\nimportlib.import_module(name)',
216
+ 'import importlib\nself.plugins.append(importlib.import_module("x"))',
217
+ 'import importlib\nself.registry.register(importlib.import_module("x"))',
218
+ ]
219
+ self.write('README.md', 'plugin support')
220
+ for source in sources:
221
+ with self.subTest(source=source):
222
+ self.write('app.py', source)
223
+ self.assertEqual(self.cli()[0], 0)
224
+
225
+ def test_test_sources_and_symlinks_excluded(self):
226
+ self.write('README.md', 'plugin support')
227
+ self.write('tests/loader.py', GOOD[0])
228
+ self.write('test_loader.py', GOOD[0])
229
+ self.write('ignored/loader.py', GOOD[0])
230
+ (self.root / 'linked.py').symlink_to(self.root / 'ignored/loader.py')
231
+ (self.root / 'linked_dir').symlink_to(self.root / 'ignored', target_is_directory=True)
232
+ self.assertEqual(audit(self.root, ['ignored'])['evidence'], [])
233
+
234
+ def test_all_phrases(self):
235
+ for phrase in PLUGIN:
236
+ self.assertEqual(doc_claims(phrase), {'PLUGIN'}, phrase)
237
+ for phrase in NOPLUGIN:
238
+ self.assertEqual(doc_claims(phrase), {'NOPLUGIN'}, phrase)
239
+ self.assertEqual(doc_claims('no plugins, but plugin api'), {'NOPLUGIN', 'PLUGIN'})
240
+
241
+
242
+ if __name__ == '__main__':
243
+ unittest.main()