@allansantos-dev/smart-tool 0.9.57 → 0.9.65
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.
- package/CHANGELOG.md +198 -0
- package/README.md +61 -12
- package/affected_tests.py +1 -1
- package/atomic_io.py +8 -2
- package/code_graph.py +25 -8
- package/code_graph_go.py +526 -12
- package/code_graph_java.mjs +19 -10
- package/code_graph_js.cjs +9 -7
- package/comment_check.py +210 -0
- package/config.py +36 -4
- package/doc_check.py +120 -20
- package/doc_cli.py +239 -0
- package/doc_extras.py +561 -0
- package/doc_insights.py +300 -0
- package/doc_prose.py +371 -0
- package/doc_scope.py +869 -0
- package/doc_validate.py +717 -0
- package/duplicates.py +15 -7
- package/hook_decision.py +62 -14
- package/install.py +59 -1
- package/install_runtime.py +30 -4
- package/layers.py +237 -0
- package/locales/pt-BR.json +10 -1
- package/model_client.py +10 -5
- package/model_defaults.py +9 -6
- package/model_health.py +9 -3
- package/model_upgrade.py +1 -1
- package/package.json +1 -1
- package/pr_impact.py +84 -0
- package/project_insights_ui.py +1 -1
- package/project_maps_ui.py +1 -1
- package/redirect_rule.py +20 -8
- package/setup_ui.py +21 -6
- package/smart_tool_daemon.py +118 -18
- package/usage_meter.py +6 -1
- package/version.py +1 -1
- package/web_adapters/browser/prune_camoufox.py +66 -0
- package/web_fetch.py +1 -1
package/doc_cli.py
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
"""Command-line interfaces the Python code declares with argparse and the functions its `__main__` blocks run, read
|
|
2
|
+
from the syntax tree without running anything."""
|
|
3
|
+
import ast
|
|
4
|
+
import posixpath
|
|
5
|
+
|
|
6
|
+
_GROUPS = ("add_argument_group", "add_mutually_exclusive_group")
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def _constant(node, bound):
|
|
10
|
+
if isinstance(node, ast.Constant):
|
|
11
|
+
return node.value
|
|
12
|
+
if isinstance(node, ast.Name):
|
|
13
|
+
return bound.get(node.id)
|
|
14
|
+
return None
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _text(node, bound):
|
|
18
|
+
"""Text of a help or description argument: the literal, an f-string with its holes as {expression}, or the source
|
|
19
|
+
of any other expression in backticks."""
|
|
20
|
+
value = _constant(node, bound)
|
|
21
|
+
if isinstance(value, str):
|
|
22
|
+
return value
|
|
23
|
+
if isinstance(node, ast.JoinedStr):
|
|
24
|
+
return "".join(p.value if isinstance(p, ast.Constant) else "{" + ast.unparse(p.value) + "}" for p in node.values)
|
|
25
|
+
return f"`{ast.unparse(node)}`"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class _Scope:
|
|
29
|
+
"""argparse objects of one function body (or of the module's top level), followed statement by statement."""
|
|
30
|
+
|
|
31
|
+
def __init__(self, path, function, found):
|
|
32
|
+
self.path, self.function, self.found = path, function, found
|
|
33
|
+
self.names, self.bound, self.definition = {}, {}, None
|
|
34
|
+
|
|
35
|
+
def _define(self, line, shared=False):
|
|
36
|
+
self.definition = {"path": self.path, "function": self.function, "line": line, "shared": shared, "commands": {}}
|
|
37
|
+
self.found.append(self.definition)
|
|
38
|
+
return self.definition
|
|
39
|
+
|
|
40
|
+
def _command(self, definition, words, help_text, line):
|
|
41
|
+
return definition["commands"].setdefault(words, {"words": list(words), "help": help_text, "line": line,
|
|
42
|
+
"arguments": []})
|
|
43
|
+
|
|
44
|
+
def call(self, node):
|
|
45
|
+
"""The argparse handle an expression yields: (kind, definition, words) or None."""
|
|
46
|
+
if isinstance(node, ast.Name):
|
|
47
|
+
return self.names.get(node.id)
|
|
48
|
+
if not isinstance(node, ast.Call):
|
|
49
|
+
return None
|
|
50
|
+
func = node.func
|
|
51
|
+
method = func.attr if isinstance(func, ast.Attribute) else func.id if isinstance(func, ast.Name) else None
|
|
52
|
+
keywords = {k.arg: k.value for k in node.keywords if k.arg}
|
|
53
|
+
if method == "ArgumentParser":
|
|
54
|
+
definition = self._define(node.lineno)
|
|
55
|
+
described = keywords.get("description")
|
|
56
|
+
self._command(definition, (), _text(described, self.bound) if described is not None else "", node.lineno)
|
|
57
|
+
return ("parser", definition, ())
|
|
58
|
+
if not isinstance(func, ast.Attribute):
|
|
59
|
+
return None
|
|
60
|
+
base = self.call(func.value)
|
|
61
|
+
if base is None and method == "add_argument" and isinstance(func.value, ast.Name):
|
|
62
|
+
definition = self.definition if self.definition and self.definition["shared"] else self._define(node.lineno, True)
|
|
63
|
+
self._command(definition, (), "", node.lineno)
|
|
64
|
+
base = ("parser", definition, ())
|
|
65
|
+
self.names[func.value.id] = base
|
|
66
|
+
if base is None:
|
|
67
|
+
return None
|
|
68
|
+
kind, definition, words = base
|
|
69
|
+
if kind == "parser" and method == "add_subparsers":
|
|
70
|
+
return ("subparsers", definition, words)
|
|
71
|
+
if kind == "subparsers" and method == "add_parser" and node.args:
|
|
72
|
+
name = _constant(node.args[0], self.bound)
|
|
73
|
+
words = words + (name if isinstance(name, str) else f"<{ast.unparse(node.args[0])}>",)
|
|
74
|
+
told = keywords.get("help", keywords.get("description"))
|
|
75
|
+
self._command(definition, words, _text(told, self.bound) if told is not None else "", node.lineno)
|
|
76
|
+
return ("parser", definition, words)
|
|
77
|
+
if kind in ("parser", "group") and method in _GROUPS:
|
|
78
|
+
return ("group", definition, words)
|
|
79
|
+
if kind in ("parser", "group") and method == "add_argument":
|
|
80
|
+
flags = [_constant(a, self.bound) for a in node.args]
|
|
81
|
+
argument = {"flags": [f for f in flags if isinstance(f, str)], "line": node.lineno,
|
|
82
|
+
"help": _text(keywords["help"], self.bound) if "help" in keywords else ""}
|
|
83
|
+
for key in ("default", "required", "choices", "action", "nargs", "metavar"):
|
|
84
|
+
if key in keywords:
|
|
85
|
+
argument[key] = ast.unparse(keywords[key])
|
|
86
|
+
self._command(definition, words, "", node.lineno)["arguments"].append(argument)
|
|
87
|
+
return None
|
|
88
|
+
|
|
89
|
+
def block(self, statements):
|
|
90
|
+
for statement in statements:
|
|
91
|
+
if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
|
|
92
|
+
continue
|
|
93
|
+
if isinstance(statement, (ast.Assign, ast.AnnAssign)) and statement.value is not None:
|
|
94
|
+
handle = self.call(statement.value)
|
|
95
|
+
targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
|
|
96
|
+
for target in targets:
|
|
97
|
+
if isinstance(target, ast.Name):
|
|
98
|
+
if handle:
|
|
99
|
+
self.names[target.id] = handle
|
|
100
|
+
else:
|
|
101
|
+
self.names.pop(target.id, None)
|
|
102
|
+
elif isinstance(statement, (ast.Expr, ast.Return)) and statement.value is not None:
|
|
103
|
+
self.call(statement.value)
|
|
104
|
+
elif isinstance(statement, ast.For):
|
|
105
|
+
self._loop(statement)
|
|
106
|
+
else:
|
|
107
|
+
for field in ("body", "orelse", "finalbody"):
|
|
108
|
+
self.block(getattr(statement, field, None) or [])
|
|
109
|
+
for handler in getattr(statement, "handlers", None) or []:
|
|
110
|
+
self.block(handler.body)
|
|
111
|
+
|
|
112
|
+
def _loop(self, statement):
|
|
113
|
+
"""A loop over a literal list of names runs its body once per item with the loop variables bound."""
|
|
114
|
+
items = statement.iter.elts if isinstance(statement.iter, (ast.Tuple, ast.List)) else None
|
|
115
|
+
target = statement.target
|
|
116
|
+
names = [target.id] if isinstance(target, ast.Name) else \
|
|
117
|
+
[t.id if isinstance(t, ast.Name) else None for t in target.elts] if isinstance(target, ast.Tuple) else None
|
|
118
|
+
if not items or names is None:
|
|
119
|
+
self.block(statement.body)
|
|
120
|
+
return
|
|
121
|
+
for item in items:
|
|
122
|
+
values = [item] if len(names) == 1 else item.elts if isinstance(item, (ast.Tuple, ast.List)) else None
|
|
123
|
+
if values is None or len(values) != len(names):
|
|
124
|
+
self.block(statement.body)
|
|
125
|
+
return
|
|
126
|
+
for name, value in zip(names, values):
|
|
127
|
+
if name:
|
|
128
|
+
self.bound[name] = value.value if isinstance(value, ast.Constant) else None
|
|
129
|
+
self.block(statement.body)
|
|
130
|
+
for name in names:
|
|
131
|
+
self.bound.pop(name, None)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def definitions(path, source):
|
|
135
|
+
"""argparse command lines declared in one Python file.
|
|
136
|
+
|
|
137
|
+
Parameters: path (str) project-relative path; source (str) the file's text.
|
|
138
|
+
Returns: list of {'path', 'function' (None at module level), 'line', 'shared' (options added to a parser the function
|
|
139
|
+
receives), 'commands': [{'words', 'help', 'line', 'arguments': [{'flags', 'help', 'line', 'default', ...}]}]}.
|
|
140
|
+
"""
|
|
141
|
+
if "argparse" not in source and "add_argument" not in source:
|
|
142
|
+
return []
|
|
143
|
+
try:
|
|
144
|
+
tree = ast.parse(source)
|
|
145
|
+
except (SyntaxError, ValueError):
|
|
146
|
+
return []
|
|
147
|
+
found = []
|
|
148
|
+
_Scope(path, None, found).block(tree.body)
|
|
149
|
+
for node in ast.walk(tree):
|
|
150
|
+
if isinstance(node, ast.ClassDef):
|
|
151
|
+
for child in node.body:
|
|
152
|
+
if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
|
153
|
+
child._owner = node.name
|
|
154
|
+
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
|
155
|
+
owner = getattr(node, "_owner", None)
|
|
156
|
+
_Scope(path, f"{owner}.{node.name}" if owner else node.name, found).block(node.body)
|
|
157
|
+
for definition in found:
|
|
158
|
+
definition["commands"] = sorted(definition["commands"].values(), key=lambda c: (c["line"], c["words"]))
|
|
159
|
+
return [d for d in found if any(c["arguments"] or c["words"] for c in d["commands"])]
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _is_main_guard(test):
|
|
163
|
+
return (isinstance(test, ast.Compare) and isinstance(test.left, ast.Name) and test.left.id == "__name__"
|
|
164
|
+
and len(test.comparators) == 1 and isinstance(test.comparators[0], ast.Constant)
|
|
165
|
+
and test.comparators[0].value == "__main__")
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _module_file(path, module, level, files):
|
|
169
|
+
"""Project path of the module an import names, or None when it is not a project file."""
|
|
170
|
+
base = posixpath.dirname(path).split("/") if path.count("/") else []
|
|
171
|
+
if level:
|
|
172
|
+
base = base[:len(base) - (level - 1)] if level > 1 else base
|
|
173
|
+
parts = base + (module.split(".") if module else [])
|
|
174
|
+
else:
|
|
175
|
+
parts = module.split(".") if module else []
|
|
176
|
+
stem = "/".join(p for p in parts if p)
|
|
177
|
+
for candidate in (f"{stem}.py", f"{stem}/__init__.py"):
|
|
178
|
+
if candidate in files:
|
|
179
|
+
return candidate
|
|
180
|
+
return None
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def launched(path, source, files):
|
|
184
|
+
"""Functions a `__main__` block of a Python file runs: (project path, function name) pairs.
|
|
185
|
+
|
|
186
|
+
Parameters: path (str) project-relative path; source (str) the file's text; files (set) project-relative paths.
|
|
187
|
+
"""
|
|
188
|
+
if "__main__" not in source:
|
|
189
|
+
return []
|
|
190
|
+
try:
|
|
191
|
+
tree = ast.parse(source)
|
|
192
|
+
except (SyntaxError, ValueError):
|
|
193
|
+
return []
|
|
194
|
+
imported = {}
|
|
195
|
+
for node in ast.walk(tree):
|
|
196
|
+
if isinstance(node, ast.ImportFrom):
|
|
197
|
+
target = _module_file(path, node.module, node.level, files)
|
|
198
|
+
if target:
|
|
199
|
+
imported.update({(a.asname or a.name): (target, a.name) for a in node.names})
|
|
200
|
+
local = {n.name for n in tree.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
|
|
201
|
+
found = []
|
|
202
|
+
for node in tree.body:
|
|
203
|
+
if isinstance(node, ast.If) and _is_main_guard(node.test):
|
|
204
|
+
for inner in ast.walk(ast.Module(body=node.body, type_ignores=[])):
|
|
205
|
+
if isinstance(inner, ast.Call) and isinstance(inner.func, ast.Name):
|
|
206
|
+
name = inner.func.id
|
|
207
|
+
pair = (path, name) if name in local else imported.get(name)
|
|
208
|
+
if pair and pair not in found:
|
|
209
|
+
found.append(pair)
|
|
210
|
+
return found
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def _argument(argument):
|
|
214
|
+
details = []
|
|
215
|
+
for key, label in (("default", "default"), ("choices", "one of"), ("nargs", "nargs"), ("metavar", "shown as")):
|
|
216
|
+
if key in argument:
|
|
217
|
+
details.append(f"{label} `{argument[key]}`")
|
|
218
|
+
if argument.get("required") == "True":
|
|
219
|
+
details.append("required")
|
|
220
|
+
if argument.get("action") in ("'store_true'", "'store_false'", "'count'", "'version'"):
|
|
221
|
+
details.append(argument["action"].strip("'").replace("store_", "sets "))
|
|
222
|
+
help_text = " ".join(argument["help"].split())
|
|
223
|
+
return (f" - {', '.join(f'`{f}`' for f in argument['flags']) or '(no name)'}"
|
|
224
|
+
+ (f" ({'; '.join(details)})" if details else "") + (f": {help_text}" if help_text else ""))
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def command_title(command):
|
|
228
|
+
"""How the documentation names a command: its words, or 'without a command' for the parser itself."""
|
|
229
|
+
return f"`{' '.join(command['words'])}`" if command["words"] else "Without a command"
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
def lines(definition):
|
|
233
|
+
"""Markdown list of a command line's commands, each with its arguments and options and their defaults."""
|
|
234
|
+
out = []
|
|
235
|
+
for command in definition["commands"]:
|
|
236
|
+
help_text = " ".join(command["help"].split())
|
|
237
|
+
out.append(f"- {command_title(command)} (line {command['line']})" + (f": {help_text}" if help_text else ""))
|
|
238
|
+
out += [_argument(a) for a in command["arguments"]]
|
|
239
|
+
return out
|