@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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,203 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.65 - beta
|
|
4
|
+
|
|
5
|
+
- An entry paragraph of `functional.md` and `simple.md` records the code it was written for (`code="..."` in its
|
|
6
|
+
marker): when the body of the function changes under the same signature, `action=docs check=true` reports
|
|
7
|
+
`prose_stale` and the validation fails the markers check. Before, a paragraph describing old behaviour passed both
|
|
8
|
+
with score 100. Empty the block and run `write_prose=true` again, or rewrite it by hand and delete the stamp
|
|
9
|
+
(`doc_scope.py`, `doc_validate.py`, `doc_prose.py`, `tests/test_doc_scope.py`, `tests/test_doc_prose.py`).
|
|
10
|
+
- The code graph records a function handed over as a value (callback, thread target, signal handler, dispatch table,
|
|
11
|
+
`http.HandleFunc` handler) as a `reference` edge, in Python and Go. Dead-code candidates drop the functions used this
|
|
12
|
+
way or by module-level code, and unnamed `callback`/`anonymous` functions: on three real projects the list went from
|
|
13
|
+
13 to 5 and from 18 to 4, every removed one a real use (`code_graph.py`, `code_graph_go.py`, `doc_insights.py`,
|
|
14
|
+
`tests/test_code_graph_limits.py`, `tests/test_code_graph_go.py`, `tests/test_doc_insights.py`).
|
|
15
|
+
- `write_prose=true` rejects a paragraph that is not in English and asks again with the reason; the instruction also
|
|
16
|
+
tells the model to describe only what the context shows, not a behaviour guessed from the names of the functions it
|
|
17
|
+
calls, and not to open with "This feature". In the measured run 8 of 242 written paragraphs were in Portuguese
|
|
18
|
+
(`doc_prose.py`, `tests/test_doc_prose.py`).
|
|
19
|
+
- The calls of `write_prose=true` are counted in the usage meter under the `docs` purpose of the project
|
|
20
|
+
(`usage_meter.py`).
|
|
21
|
+
- A model failure is blamed on the role that made the call: when the docs model and the router model are the same model,
|
|
22
|
+
a timed-out `write_prose` call warned "router_model failed" and the setup screen counted it under the router
|
|
23
|
+
(`model_health.py`, `tests/test_model_health.py`).
|
|
24
|
+
- `write_prose=true` accepts a paragraph whose code span holds angle brackets, such as `logs/<name>.log` copied from a
|
|
25
|
+
docstring: it was rejected as HTML on every attempt (`doc_prose.py`, `tests/test_doc_prose.py`).
|
|
26
|
+
- Line numbers in `docs/scope` stay right in files with a form feed or other line separators Python's `splitlines`
|
|
27
|
+
splits on (`doc_check.py`, `doc_extras.py`, `tests/test_doc_check.py`, `tests/test_doc_extras.py`).
|
|
28
|
+
- The validation notes, instead of failing, a manifest command that runs a file which is not in the repository (a build
|
|
29
|
+
output such as `bin/...`) (`doc_validate.py`, `tests/test_doc_validate.py`).
|
|
30
|
+
|
|
31
|
+
## 0.9.64 - beta
|
|
32
|
+
|
|
33
|
+
- `project_manage action=docs write_prose=true` writes the empty prose blocks of `docs/scope` with the new docs model
|
|
34
|
+
role (`docs_model`, "Docs model" in the setup screen, filled with Claude Haiku 5.5 when the gateway has it). Each block
|
|
35
|
+
is a task of its kind (module, entry point, plain-language entry point, overview) with a fixed instruction and a
|
|
36
|
+
context read from the code (docstrings, signatures, source, flow, command line, tests, manifest and README), marked as
|
|
37
|
+
data the model must not obey. A paragraph is written only when every name, option and version it cites exists in the
|
|
38
|
+
code and its form fits the kind; a rejected one is asked again once with the reason, then left empty and reported with
|
|
39
|
+
its fix, without the model's text. A call stops after about 40 s, under the MCP client's tool timeout, and says how
|
|
40
|
+
many blocks are left; the regeneration that follows validates the prose again (`doc_prose.py`,
|
|
41
|
+
`tests/test_doc_prose.py`). The model was chosen by measuring seven candidates on 36 blocks of a real project each,
|
|
42
|
+
judged by Claude Opus 5.5 (`docs/research/2026-11-05-modelo-e-instrucao-da-prosa.md`).
|
|
43
|
+
- Structured output sends Anthropic's `output_config` only to Claude models: Gemini on the `vertex_ai` route ignored it
|
|
44
|
+
and answered loose text, so every structured call with a Gemini model failed (`tests/test_structured_output.py`).
|
|
45
|
+
|
|
46
|
+
## 0.9.63 - beta
|
|
47
|
+
|
|
48
|
+
- `action=docs generate=true` validates what it wrote, and `action=docs validate=true` runs the same validation alone:
|
|
49
|
+
every claim of `docs/scope` is checked against the code and the report `docs/scope/validation.md` gives pass/fail per
|
|
50
|
+
check with evidence, a score and the verdict (fail, pass with prose pending, or pass). The checks: anchors and
|
|
51
|
+
signatures, every relative link, line numbers, callers/calls/tests against the graph, the declared coverage and the
|
|
52
|
+
undocumented gaps, why each entry point is one and its flow, the scripts the manifests and `__main__` blocks run, the
|
|
53
|
+
command lines, the names, options and versions the written prose cites, the tests per entry point, link labels,
|
|
54
|
+
counts and the project name across pages, the glossary, navigation from the index, and the dependency versions. A
|
|
55
|
+
failing validation leads the guidance of `generate` (`tests/test_doc_validate.py`).
|
|
56
|
+
- `functional.md` gains a "Command line" section with the commands, arguments, options, defaults and help the code
|
|
57
|
+
declares with argparse (read from the syntax tree, loops over literal names expanded), and the functions a
|
|
58
|
+
`__main__` block runs are entry points. Links to entry points carry their file when the name repeats, and
|
|
59
|
+
`simple.md` takes the project name from `pyproject.toml`, `package.json`, `Cargo.toml` or `go.mod`.
|
|
60
|
+
- Go joins the code graph: functions, methods, types and interfaces with static calls resolved within the package and
|
|
61
|
+
through imports, so `graph`, `affected_tests`, the duplicate check and the documentation check read Go code. The
|
|
62
|
+
documentation check follows the revive `exported` rule: a doc comment must start with the declared name, and one
|
|
63
|
+
that does not is reported as malformed. On a real Go project: 262 symbols and 289 calls in 0.52 s
|
|
64
|
+
(`tests/test_code_graph_go.py`, `tests/test_doc_check.py`).
|
|
65
|
+
- `project_manage action=layers` declares the project's layers, highest first, each by path globs and annotations,
|
|
66
|
+
as import-linter's layers contract, ArchUnit and dependency-cruiser define them. Without a rule it suggests one from
|
|
67
|
+
folder names and annotations, with the files, symbols and calls between layers (down or against the order); a rule
|
|
68
|
+
passed in `layers` is a preview until `confirm=true` saves it to `.smart-tool/layers.json` (`tests/test_layers.py`).
|
|
69
|
+
- `action=pr_impact` (read-only) returns a Markdown impact report of the change set against `base`: touched functions
|
|
70
|
+
with their callers, documentation anchors left out of date in the changed files, and the tests to run with their
|
|
71
|
+
commands; it joins `code_impact`, `affected_tests` and the documentation check and publishes nothing
|
|
72
|
+
(`tests/test_pr_impact.py`).
|
|
73
|
+
- `action=docs generate=true` writes five more optional pages, on by default with opt-outs `hotspots`, `coupling`,
|
|
74
|
+
`dead_code`, `tour` and `glossary`: hotspots (commits × lines, the method code-maat publishes), hidden change coupling
|
|
75
|
+
(shared commits over average commits, bulk commits skipped, pairs that already import each other only counted),
|
|
76
|
+
dead-code candidates (no static caller, or only tests), an onboarding tour of the entry points, and a glossary of the
|
|
77
|
+
words in function names that also feeds `simple.md`. The `adr` page gains decision candidates from the git log (decision
|
|
78
|
+
wording or a dependency-manifest change) with drafts for the latest. Without readable git history the pages say so
|
|
79
|
+
(`tests/test_doc_insights.py`). No code of the GPL code-maat is used.
|
|
80
|
+
- `action=docs generate=true` also writes ten optional documents beside the scope, all from the code graph and all on
|
|
81
|
+
by default, each with its own opt-out in `docs_extras` of `config.json` (`structure`, `coverage`, `modules`, `tests`,
|
|
82
|
+
`configuration`, `dependencies`, `adr`, `flows`, `features_tests`, `index`; an unknown key or a non-boolean fails
|
|
83
|
+
naming the config path): the folder structure drawn without `tree`, the docstring coverage per folder, the module
|
|
84
|
+
Mermaid, the tests README linked to the functional anchors, the configuration the code reads (environment variables,
|
|
85
|
+
config files, ports), the external dependencies with the licenses of the installed packages only, the decision
|
|
86
|
+
record index with an ADR template, a Mermaid sequence per entry point, and the entry points × tests matrix. The flows
|
|
87
|
+
and matrix pages carry signature markers, so `action=docs check=true` and the edit hook cover them. The short index
|
|
88
|
+
goes between `smart-tool:index` markers in an existing `AGENTS.md` (or `llms.txt`) and is never created; regeneration
|
|
89
|
+
replaces only the block and unbalanced markers fail. Every page repeats the `truncated` warning of the graph
|
|
90
|
+
(`tests/test_doc_extras.py`). Measured: on Smart Tool itself 105 files, 910 KB (62 KB of them extras) in 8.0 s with
|
|
91
|
+
`check` clean in 2.0 s; on a Go project with three layers 25 files, 104 KB (22 KB extras) in 1.2 s, `check` clean.
|
|
92
|
+
- `project_manage action=docs generate=true` writes the documentation scope to `docs/scope` from the code graph,
|
|
93
|
+
without a model: technical pages by folder, or by module when a folder has more than 150 public functions, with an
|
|
94
|
+
entry per public function (anchor `path::name`, signature, first
|
|
95
|
+
doc line, layer, callers, calls, the tests that reach it) and a Mermaid flow of the folders by layer;
|
|
96
|
+
`functional.md` with each entry point and the functions its calls reach, by layer; `simple.md`. The agent writes the
|
|
97
|
+
prose between prose markers and regeneration keeps it, as terraform-docs keeps the text around its block; a file
|
|
98
|
+
Smart Tool did not write is never overwritten. On a real Go project with three declared layers: 95 public
|
|
99
|
+
functions on 11 pages, 16 entry points, 15 files and 71 KB in 1.2 s; on Smart Tool itself, 803 public functions on 90
|
|
100
|
+
pages, the largest 53 KB (`tests/test_doc_scope.py`).
|
|
101
|
+
- Each documentation anchor records the signature it was generated from, like Swimm's smart tokens:
|
|
102
|
+
`action=docs check=true` lists anchors whose function changed signature or is gone and links to missing anchors,
|
|
103
|
+
`action=docs symbol=NAME` tells where a function is documented, and the documentation hook warns when an edit makes
|
|
104
|
+
a documented entry out of date. The link lives in the documents and the query, never inside docstrings.
|
|
105
|
+
- The edit hook now keeps documentation in the docstring by default: `doc_mode` defaults to `require` (was `remind`)
|
|
106
|
+
and the new `comment_mode` (`require`, `remind`, `off`; default `require`) blocks, among the comments an edit adds or
|
|
107
|
+
changes in a code file, commented-out code, ticket, version and history tags, a loose block above a function instead
|
|
108
|
+
of its docstring and a block of more than two lines inside a body. A short comment that says why, directives and
|
|
109
|
+
dividers pass. Opt out with `"doc_mode": "off"` and `"comment_mode": "off"` (or Off on both cards of the setup
|
|
110
|
+
screen); a setting already saved is kept, so documentation generated afterwards finds every function documented in
|
|
111
|
+
place (`tests/test_comment_check.py`).
|
|
112
|
+
|
|
113
|
+
## 0.9.62 - beta
|
|
114
|
+
|
|
115
|
+
- The code graph keeps up to 100,000 symbols and 250,000 edges (calls and dependencies); before, it stopped at 8,000
|
|
116
|
+
and 20,000. A real Node project already had 8,103 symbols, and a 968-file one had 17,651 symbols and 16,695 calls,
|
|
117
|
+
of which the graph kept 8,000 and 6,852. The Python analyzer passes its limits to the JS/TS and Java analyzers, and
|
|
118
|
+
`truncated` is set only when a symbol or an edge was really left out, including symbols of several languages that
|
|
119
|
+
fit one by one but not together; before, `counts.symbols` could report 8,190 for a project with 17,651
|
|
120
|
+
(`tests/test_code_graph_limits.py`).
|
|
121
|
+
- The Java analyzer starts in 0.2 s instead of 1.1 s. java-parser reaches chevrotain's sources and lodash one module
|
|
122
|
+
file per function, 744 files read on every run; with Node's `module.registerHooks` the analyzer loads chevrotain's
|
|
123
|
+
own bundle and lodash's single file instead, with byte-identical output on 167 and 199 real files (36 files: 1.76 s
|
|
124
|
+
→ 0.84 s; 199 files: 6.91 s → 3.80 s). A Node without `registerHooks` loads java-parser as published.
|
|
125
|
+
- Duplicate and documentation checks analyze many TypeScript or Java files in one analyzer run per language instead
|
|
126
|
+
of one run per file (`doc_check.analyze_files`): 36 Java files took 28.7 s before.
|
|
127
|
+
- A search in a folder of the system's temporary folder runs natively unless a registered project holds it. The
|
|
128
|
+
session folder used to count as a project there, so the redirected `smart_search` registered and indexed a copy
|
|
129
|
+
made for a measurement or a build (`tests/test_router.py`).
|
|
130
|
+
|
|
131
|
+
## 0.9.61 - beta
|
|
132
|
+
|
|
133
|
+
- Old Camoufox builds leave the user's cache. camoufox 0.5.6 installs each build in its own folder and never deletes
|
|
134
|
+
the previous one, so the cache grew by about 2.5 GB per build (8.2 GB on this machine, 2.5 GB of it in use). After
|
|
135
|
+
an update has been verified, the installer runs `web_adapters/browser/prune_camoufox.py`, which deletes the builds
|
|
136
|
+
of the active build's repository older than the active one and logs each removal with its size and the total freed.
|
|
137
|
+
It removes nothing when `pinned` is set in Camoufox's `config.json` or no build is active, and never touches the
|
|
138
|
+
active build, a newer one or another repository's. Each folder is renamed to a hidden name in `browsers/` before it
|
|
139
|
+
is deleted, which Windows refuses while a file inside is open, so a build in use is kept whole and logged; a
|
|
140
|
+
deletion cut short is finished on the next run. A failed pruning is reported and the update stays
|
|
141
|
+
(`tests/test_prune_camoufox.py`, `tests/test_install_legacy.py`). Research:
|
|
142
|
+
`docs/research/2026-11-04-camoufox-cache-pruning.md`.
|
|
143
|
+
|
|
144
|
+
## 0.9.60 - beta
|
|
145
|
+
|
|
146
|
+
- A new `package-lock.json` reaches every install. `install_runtime.py` ran `npm ci` only when a parser file was
|
|
147
|
+
missing, so an install that already had them kept the old TypeScript, java-parser, Angular compiler and Playwright
|
|
148
|
+
MCP. After `npm ci` succeeds it now records the lock's SHA-256 in `node_modules/.smart-tool-lock.sha256`; a lock
|
|
149
|
+
that differs runs `npm ci` again, and `install_runtime.py --check` reports `node_packages: missing`, so an update
|
|
150
|
+
runs the dependency step for an install whose packages came from another lock, including one installed before this
|
|
151
|
+
version (`tests/test_install_runtime.py`). npm's own `node_modules/.package-lock.json` is not compared, because npm
|
|
152
|
+
ignores it whenever another tool touched the tree.
|
|
153
|
+
- A newer Camoufox browser build for the same library version arrives on every update. Since 0.9.59 an update whose
|
|
154
|
+
dependency files did not change skipped `fetch_camoufox.py`, so a new build reached an install only when one of
|
|
155
|
+
those files changed. When the dependency step is skipped, the installer now runs `fetch_camoufox.py` before stopping
|
|
156
|
+
the service. Camoufox compares the active build with the newest supported release, downloads a newer one into its
|
|
157
|
+
own folder and switches to it only after the SHA-256 check, so the running browser keeps its files and the stop
|
|
158
|
+
window does not grow. A failed download ends the update before anything was stopped or copied
|
|
159
|
+
(`tests/test_install_legacy.py`).
|
|
160
|
+
|
|
161
|
+
## 0.9.59 - beta
|
|
162
|
+
|
|
163
|
+
- An update keeps open Claude Code sessions connected. The installer ran pip and `install_runtime.py` while the
|
|
164
|
+
service was stopped, about 48 s on a current machine, and Claude Code stops reconnecting after 5 attempts (about
|
|
165
|
+
15 s), so every open session lost Smart Tool until `/mcp` (33 times in Claude Code's logs from 2026-10-02 to
|
|
166
|
+
2026-11-04). After a completed update the installer records a SHA-256 of the files that decide the dependencies
|
|
167
|
+
(`requirements.txt`, `install_runtime.py`, `node_locator.py`, the Node `package.json` and `package-lock.json`, the
|
|
168
|
+
browser `requirements.txt`, `fetch_camoufox.py` and `ranged_download.py`) in `.dependencies.sha256`; the next update
|
|
169
|
+
whose files match skips that step and says so. A changed file, a missing record or a missing venv runs it as before,
|
|
170
|
+
and an update rolled back after the step leaves the old record (`tests/test_install_legacy.py`).
|
|
171
|
+
- A restart keeps the port the clients already know. The service tried the default port first, so a restart after
|
|
172
|
+
it had moved to another port went back to the default and cut every session still on the other one; it now tries
|
|
173
|
+
the port in the clients' configuration first, then the default, then any free port (`tests/test_endpoint_sync.py`).
|
|
174
|
+
- A search inside `$(...)` or `` `...` `` is judged in the folder its segment runs in. The redirect hook decided every
|
|
175
|
+
substitution of a command with the folder at its start, so `cd outside; echo $(grep -rn x .)` was redirected as a
|
|
176
|
+
search of the session folder, and a `cd` inside a substitution moved the commands after it; a substitution is now
|
|
177
|
+
decided with the state of its own segment, and its `cd` stays inside it (`tests/test_router.py`).
|
|
178
|
+
- The test files can run in one process (`python -m unittest a b ...`, as the `affected_tests` command suggests).
|
|
179
|
+
Classes replaced functions of shared modules in `setUpClass` without restoring them, and the gateway tests left a
|
|
180
|
+
user adapter folder behind, so 21 tests failed and 8 errored together while each file passed alone; the
|
|
181
|
+
replacements now go through `mock.patch.object` with a class cleanup (`tests/_env.py`, `patch_for_class`).
|
|
182
|
+
- `server/discover`, which Claude Code 2.1.316 sends before `initialize`, keeps its JSON-RPC -32601 answer: the
|
|
183
|
+
daemon speaks protocol 2025-06-18, and a client that gets any error other than -32022 falls back to `initialize`, as
|
|
184
|
+
the protocol revision that defines the method asks (`tests/test_mcp_transport.py`).
|
|
185
|
+
|
|
186
|
+
## 0.9.58 - beta
|
|
187
|
+
|
|
188
|
+
- Claude Code no longer drops the Smart Tool connection while the service is up. `GET /mcp` and `DELETE /mcp` answer
|
|
189
|
+
405 with `Allow: POST`, as the MCP Streamable HTTP transport allows for a server with no server-initiated stream and
|
|
190
|
+
no client-ended sessions; they answered 404, which the MCP SDK client treats as a broken connection: Claude Code's
|
|
191
|
+
logs held two `Failed to open SSE stream: Not Found` per connection, 4,838 between 2026-10-02 and 2026-11-04, and the
|
|
192
|
+
connection was later closed "with errors" and reopened. A DELETE elsewhere answers 404 instead of 501
|
|
193
|
+
(`tests/test_mcp_transport.py`).
|
|
194
|
+
- A tool call longer than a minute reaches Claude Code. Claude Code aborts an MCP request whose response has not
|
|
195
|
+
started within 60 s, so a long `web_search`, `web_fetch` or `smart_scout` ended in `The operation timed out.` (202
|
|
196
|
+
times in the same logs). A `tools/call` from a client that accepts `text/event-stream` and still running after 10 s
|
|
197
|
+
is answered as an SSE stream: headers at once, a comment every 15 s, and the result as its only event. A faster call,
|
|
198
|
+
or a client that does not accept SSE, gets the single JSON body as before (`tests/test_mcp_transport.py`; diagnosis
|
|
199
|
+
in `docs/research/2026-11-04-mcp-client-drops.md`).
|
|
200
|
+
|
|
3
201
|
## 0.9.57 - beta
|
|
4
202
|
|
|
5
203
|
- Codex runs Smart Tool's hooks with no `/hooks` step. Installing or updating the Codex redirect hook or the
|
package/README.md
CHANGED
|
@@ -17,7 +17,7 @@ registered as the `playwright` server where this machine lets a browser be drive
|
|
|
17
17
|
An optional hook routes the agent's native Grep/Glob/Read/Bash/WebSearch/WebFetch calls to these tools when they
|
|
18
18
|
are cheaper, or just tells the agent what Smart Tool would do.
|
|
19
19
|
|
|
20
|
-
**Status:** 0.9.
|
|
20
|
+
**Status:** 0.9.65 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
|
|
21
21
|
|
|
22
22
|
## How it works
|
|
23
23
|
|
|
@@ -83,7 +83,7 @@ gateway such as Ollama, nothing about your code leaves the machine.
|
|
|
83
83
|
## Install
|
|
84
84
|
|
|
85
85
|
```powershell
|
|
86
|
-
npx @allansantos-dev/smart-tool@0.9.
|
|
86
|
+
npx @allansantos-dev/smart-tool@0.9.65 install
|
|
87
87
|
```
|
|
88
88
|
|
|
89
89
|
Updates install themselves, on by default: the tray checks npm when it starts (at logon) and every 24 h, and when there
|
|
@@ -115,10 +115,10 @@ searches, the router's tier and sufficiency decisions, the index profile and the
|
|
|
115
115
|
`temperature`, and the answer is validated against the schema before use. A stop other than a normal one (cut at the
|
|
116
116
|
token limit, refusal), an empty answer, a missing field or a value outside an enum fails the call with its reason
|
|
117
117
|
instead of passing as an empty result. The `structured_output` object of `config.json` chooses the format:
|
|
118
|
-
`mode` is `auto` (default: `output_config` for the models whose route, the id prefix before the first dot, is
|
|
119
|
-
`output_config_routes`, which is `["vertex_ai"]` by default; `response_format`, applied on every gateway route, for
|
|
120
|
-
others, Bedrock included), `response_format` or `output_config`; `output_config` for a
|
|
121
|
-
refused. `unsupported_keywords` lists the schema keywords the gateway does not apply (`maxItems`, `minLength`...); they
|
|
118
|
+
`mode` is `auto` (default: `output_config` for the Claude models whose route, the id prefix before the first dot, is
|
|
119
|
+
in `output_config_routes`, which is `["vertex_ai"]` by default; `response_format`, applied on every gateway route, for
|
|
120
|
+
all others, Bedrock and Gemini on Vertex included), `response_format` or `output_config`; `output_config` for a model
|
|
121
|
+
that is not Claude or for a route outside the list is refused. `unsupported_keywords` lists the schema keywords the gateway does not apply (`maxItems`, `minLength`...); they
|
|
122
122
|
are left out of the request and the code that reads the answer keeps enforcing them.
|
|
123
123
|
|
|
124
124
|
## Set up
|
|
@@ -133,7 +133,8 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
133
133
|
`https://openrouter.ai/api/v1`, `http://localhost:11434/v1`), and an optional API key. Saving tests `/models` first.
|
|
134
134
|
2. **Models**: embedding, rerank (optional; without it results use the hybrid order), the router model (small, no
|
|
135
135
|
reasoning: web search tier order and result checks), the index classification model (also reviews block patterns), the
|
|
136
|
-
scout model (the short answer of `smart_scout`)
|
|
136
|
+
scout model (the short answer of `smart_scout`), the research model and the docs model (the prose of the generated
|
|
137
|
+
documentation). Any id the gateway accepts works; the catalog is
|
|
137
138
|
shown as suggestions. Empty roles are filled with the recommended models the gateway offers.
|
|
138
139
|
|
|
139
140
|
When a new version recommends other models than the ones you use, a Windows notification (**Apply now**, **Don't
|
|
@@ -208,19 +209,67 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
208
209
|
- **Advise only**: the native tool runs; the agent receives the same advice next to the result and decides.
|
|
209
210
|
- **Off**: no routing.
|
|
210
211
|
|
|
211
|
-
**Documentation on edit** checks the public functions an edit touches (Python docstrings, JSDoc, Javadoc
|
|
212
|
-
|
|
212
|
+
**Documentation on edit** checks the public functions an edit touches (Python docstrings, JSDoc, Javadoc, and Go
|
|
213
|
+
doc comments, which must start with the declared name as the revive `exported` rule asks), in Claude Code edits and
|
|
214
|
+
Codex patches. Private (`_name`, `#name`, `private`), nested and override (`@Override`,
|
|
213
215
|
`@override`) functions are exempt, as in pydocstyle, eslint-plugin-jsdoc and Checkstyle, and a JSDoc above a set of
|
|
214
216
|
TypeScript overloads documents the implementation:
|
|
215
|
-
- **
|
|
217
|
+
- **Require** (default): an edit that leaves a touched function without a docstring is blocked until it adds one.
|
|
218
|
+
- **Remind**: the edit runs and the agent is told which touched functions have no docstring, and which
|
|
216
219
|
documented ones changed their signature, with their callers, the tests calling them and the command that runs those tests
|
|
217
220
|
(from the code graph, only when it is already cached: the hook never waits for an analysis).
|
|
218
|
-
- **Require**: an edit that leaves a touched function without a docstring is blocked until it adds one.
|
|
219
221
|
- **Off**: no checks.
|
|
220
222
|
|
|
223
|
+
**Comments in the wrong place** keeps the documentation in the docstring, where `action=docs` reads it. Of the
|
|
224
|
+
comments an edit adds or changes in a code file (not tests), it blocks four kinds: commented-out code (the ruff
|
|
225
|
+
`ERA001` rule), a ticket, version or history tag (`PEDIDO 1304`, `JIRA-12`, `added in v2.1`), a loose comment block
|
|
226
|
+
right above a function instead of its docstring, and a block of more than two lines inside a function body. A
|
|
227
|
+
short comment that says why (`// The gateway drops the first frame after a reconnect.`) passes, as do directives
|
|
228
|
+
(`# noqa`, `//go:build`, `// eslint-disable`), dividers and comments the edit did not touch. `comment_mode` in
|
|
229
|
+
`config.json`: `require` (default, the edit is blocked until the comment is fixed), `remind` (the edit runs and the
|
|
230
|
+
agent is told) or `off`. To turn the whole rule off set `"doc_mode": "off"` and `"comment_mode": "off"` in
|
|
231
|
+
`~/.smart-tool/config.json`, or pick Off on both cards of the setup screen. A setting you already saved stays as
|
|
232
|
+
saved; only a config without the key follows the new default.
|
|
233
|
+
|
|
221
234
|
A documented function edited only in its body is not mentioned. `project_manage` with `action=docs` lists the
|
|
222
235
|
public functions still without a docstring, for documenting a project that started without them.
|
|
223
236
|
|
|
237
|
+
**Documentation scope**: `action=layers` declares the project's layers, highest first (entry points, services,
|
|
238
|
+
domain, data access), each by path globs and annotations, as import-linter's layers contract, ArchUnit and
|
|
239
|
+
dependency-cruiser define them. Without a rule it suggests one from folder names (`cmd`, `handler`, `service`,
|
|
240
|
+
`repository`...) and annotations (`@RestController`, `@Service`, `@app.route`...), with the calls between layers;
|
|
241
|
+
passing `layers` previews a rule and the same `layers` with `confirm=true` saves it to `.smart-tool/layers.json`.
|
|
242
|
+
`action=docs generate=true` writes `docs/scope` in the project from the code graph, without a model: a technical page
|
|
243
|
+
per folder (a page per module when the folder has more than 150 public functions) with an entry per public function
|
|
244
|
+
(anchor `path::name`, signature, first doc line, layer, callers, calls and the tests that reach it) and a Mermaid flow of the folders by layer; `functional.md` with each entry point (the
|
|
245
|
+
public functions of the highest layer and every `main`) and the functions its calls reach, by layer; and
|
|
246
|
+
`simple.md`. `action=docs write_prose=true` writes the empty prose blocks with the docs model (Claude Haiku 5.5 by
|
|
247
|
+
default): each block gets an instruction for its kind (module, entry point, plain-language entry, overview) and a
|
|
248
|
+
context read from the code, and a paragraph is written only when every name, option and version it cites exists in
|
|
249
|
+
the code and it is in English; a rejected one is asked again once with the reason, then reported with its fix. A call stops after about
|
|
250
|
+
40 s and says how many blocks are left. The prose can also be written by hand between the markers; regenerating keeps it, reports blocks whose module
|
|
251
|
+
or entry point is gone, and never overwrites a file that Smart Tool did not write. Each anchor records the signature
|
|
252
|
+
it was generated from: `action=docs check=true` lists anchors whose function changed signature or is gone, links
|
|
253
|
+
to missing anchors and entry paragraphs written for an older body of their function (the `code="..."` stamp of the
|
|
254
|
+
block; delete it after rewriting the paragraph by hand), `action=docs validate=true` checks every claim of `docs/scope` against the code and writes `docs/scope/validation.md`, `action=docs symbol=NAME` tells where a function is documented, and the documentation hook warns
|
|
255
|
+
when an edit makes a documented entry out of date. The link lives in the documents, never inside docstrings.
|
|
256
|
+
The same run writes fifteen optional documents under `docs/scope/extras`, all from the graph and the git log: folder
|
|
257
|
+
structure, docstring coverage per folder, module Mermaid, tests README, configuration read by the code, dependencies
|
|
258
|
+
with the licenses of installed packages, decision index with an ADR template and the decision candidates found in the
|
|
259
|
+
git log, a sequence per entry point, the entry points × tests matrix, hotspots (commits × lines), hidden change
|
|
260
|
+
coupling (files that change together without an import), dead-code candidates, an onboarding tour of the entry
|
|
261
|
+
points and a glossary of the words the code uses (which also feeds `simple.md`). Each is on by default; turn one
|
|
262
|
+
off with `"docs_extras": {"modules": false}` in `config.json` (keys: `structure`, `coverage`, `modules`, `tests`,
|
|
263
|
+
`configuration`, `dependencies`, `adr`, `flows`, `features_tests`, `hotspots`, `coupling`, `dead_code`, `tour`,
|
|
264
|
+
`glossary`, `index`). The history pages say so on the page when the folder has no readable git history. `index`
|
|
265
|
+
keeps a short index of the documentation between `smart-tool:index` markers in an existing `AGENTS.md` or
|
|
266
|
+
`llms.txt`; it never creates the file and rewrites only the block.
|
|
267
|
+
|
|
268
|
+
**Impact of a change**: `project_manage action=pr_impact [base=main]` returns a Markdown report of the change set
|
|
269
|
+
against `base` (default `HEAD`): the touched functions with their callers, the documentation anchors left out of
|
|
270
|
+
date, and the tests to run with their commands. It reads only; publishing it as a pull-request comment is left to
|
|
271
|
+
the CI step that calls it.
|
|
272
|
+
|
|
224
273
|
**Dependency check on edit**: an edit of `package.json`, `requirements*.txt` or `go.mod` that adds or changes a dependency lists the OSV advisory IDs of up to 5 of them (exact version, or the lower bound of `^`, `~`, `~=` and `>=`), answered from a 6 h disk cache or one 2.5 s batch call that sends only package names and versions; when OSV cannot answer, the reminder says the check was skipped and the edit goes on. `dependency_mode` in `config.json`: `warn` (default) or `off`.
|
|
225
274
|
|
|
226
275
|
**PDFs** inside a project are indexed as text with `[page N]` markers (20 MiB, 300 pages and 20 s per file; a scanned, password-protected or corrupt PDF is skipped with the reason), so `smart_search` returns the page that holds a passage. **Presentations and workbooks** (`.pptx`, `.xlsx`) are indexed the
|
|
@@ -245,7 +294,7 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
245
294
|
count before the project is reindexed. `run_all` is true, with
|
|
246
295
|
the reason, when a configuration or lockfile changed or a changed code file is outside the import graph. Go is read
|
|
247
296
|
by package: a file that imports a package depends on every file of it, so a changed package selects the tests of every
|
|
248
|
-
package that imports it (`go test ./pkg ...`); the
|
|
297
|
+
package that imports it (`go test ./pkg ...`); the Rust documentation and duplicate hooks stay silent.
|
|
249
298
|
|
|
250
299
|
`project_manage` with `action=setup_audit` and a `project_root` (or `python setup_audit.py --project <folder>`)
|
|
251
300
|
reports what Claude Code and Codex actually load for that folder (settings layers, enabled plugins of both,
|
package/affected_tests.py
CHANGED
|
@@ -353,7 +353,7 @@ def affected(root, base="HEAD", limit=30, view_id=None):
|
|
|
353
353
|
"index scope)"})
|
|
354
354
|
if not_analyzed:
|
|
355
355
|
run_all.append(f"{len(not_analyzed)} changed code file(s) outside the import graph; see not_analyzed")
|
|
356
|
-
touched = [s for s in by_id.values() if s["path"] in changes and s.get("kind") not in ("module", "class", "interface")
|
|
356
|
+
touched = [s for s in by_id.values() if s["path"] in changes and s.get("kind") not in ("module", "class", "interface", "type")
|
|
357
357
|
and (changes[s["path"]]["lines"] is None
|
|
358
358
|
or changes[s["path"]]["lines"].intersection(range(s["start_line"], s["end_line"] + 1)))]
|
|
359
359
|
touched = [s for s in touched if not any(o is not s and o["path"] == s["path"] and o in touched
|
package/atomic_io.py
CHANGED
|
@@ -56,7 +56,7 @@ def sweep_orphans(final_path, max_age_s=ORPHAN_AGE_S):
|
|
|
56
56
|
pass
|
|
57
57
|
|
|
58
58
|
|
|
59
|
-
def _write_and_replace(final_path, data, encoding=None):
|
|
59
|
+
def _write_and_replace(final_path, data, encoding=None, permissions=0o600):
|
|
60
60
|
sweep_orphans(final_path)
|
|
61
61
|
tmp_path = tmp_path_for(final_path)
|
|
62
62
|
try:
|
|
@@ -64,7 +64,7 @@ def _write_and_replace(final_path, data, encoding=None):
|
|
|
64
64
|
# conteúdo); `0o600` é o pedido de permissão restrita onde o SO honra (no Windows
|
|
65
65
|
# só liga o atributo read-only — lá a confidencialidade vem da ACL do diretório).
|
|
66
66
|
flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
|
|
67
|
-
fd = os.open(tmp_path, flags,
|
|
67
|
+
fd = os.open(tmp_path, flags, permissions)
|
|
68
68
|
mode = "wb" if encoding is None else "w"
|
|
69
69
|
extra = {} if encoding is None else {"encoding": encoding, "newline": ""}
|
|
70
70
|
with os.fdopen(fd, mode, **extra) as f:
|
|
@@ -92,3 +92,9 @@ def write_secret_bytes(final_path, data):
|
|
|
92
92
|
def write_secret_text(final_path, text, encoding="utf-8"):
|
|
93
93
|
"""Mesmo contrato de `write_secret_bytes`, para conteúdo textual (JSON de token)."""
|
|
94
94
|
_write_and_replace(final_path, text, encoding=encoding)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def write_text(final_path, text, encoding="utf-8"):
|
|
98
|
+
"""Atomic text write of a file other programs and people read and edit (project files): the same temp, fsync and
|
|
99
|
+
replace as write_secret_text, with the permissions the user's umask gives a new file."""
|
|
100
|
+
_write_and_replace(final_path, text, encoding=encoding, permissions=0o666)
|
package/code_graph.py
CHANGED
|
@@ -23,13 +23,14 @@ import web_document_graph
|
|
|
23
23
|
import code_graph_go
|
|
24
24
|
import document_text
|
|
25
25
|
|
|
26
|
-
VERSION =
|
|
26
|
+
VERSION = 5
|
|
27
27
|
SOURCE_EXTENSIONS = ('.py','.go','.mod','.java','.js','.jsx','.ts','.tsx','.mjs','.cjs','.mts','.cts','.json','.html','.htm','.css','.scss','.sass','.less','.md','.markdown')
|
|
28
28
|
MAX_OVERLAY_BYTES = 5 * 1024 * 1024
|
|
29
29
|
MAX_FILES = 3000
|
|
30
30
|
MAX_TEXT = 24 * 1024 * 1024
|
|
31
|
-
MAX_SYMBOLS =
|
|
32
|
-
MAX_EDGES =
|
|
31
|
+
MAX_SYMBOLS = 100000
|
|
32
|
+
MAX_EDGES = 250000
|
|
33
|
+
ANALYZER_LIMITS = {'symbols': MAX_SYMBOLS, 'edges': MAX_EDGES}
|
|
33
34
|
_CACHE = collections.OrderedDict()
|
|
34
35
|
_LOCK = threading.Lock()
|
|
35
36
|
_ANALYSIS_SLOTS = threading.BoundedSemaphore(2)
|
|
@@ -97,6 +98,7 @@ def _snapshot(path):
|
|
|
97
98
|
def _python_graph(sources):
|
|
98
99
|
trees, symbols, dependencies, calls, unresolved, diagnostics = {}, [], [], [], [], []
|
|
99
100
|
decls, aliases, scopes, classes, owners, shadow_scopes, node_symbols = {}, {}, {}, {}, {}, {}, {}
|
|
101
|
+
dropped = {'symbols': 0, 'calls': 0}
|
|
100
102
|
def bind_import(path,scope,name,binding):
|
|
101
103
|
table=aliases[path].setdefault(scope,{})
|
|
102
104
|
table[name]=binding if name not in table or table[name]==binding else None
|
|
@@ -121,6 +123,7 @@ def _python_graph(sources):
|
|
|
121
123
|
scopes[id(node)]=qual;node_symbols[id(node)]=sym
|
|
122
124
|
if isinstance(node,ast.ClassDef):classes[path][qual]=node
|
|
123
125
|
if len(symbols)<MAX_SYMBOLS:symbols.append(sym)
|
|
126
|
+
else:dropped['symbols']+=1
|
|
124
127
|
owner=sym
|
|
125
128
|
owners[id(node)]=qual
|
|
126
129
|
for child in ast.iter_child_nodes(node):collect(child,qual,owner)
|
|
@@ -175,6 +178,7 @@ def _python_graph(sources):
|
|
|
175
178
|
rest=(([imported] if imported and imported!='*' else [])+parts[length:])
|
|
176
179
|
return decls.get(target_path,{}).get(tuple(rest))
|
|
177
180
|
return None
|
|
181
|
+
function_names={s['name'].split('.')[-1] for s in symbols if s['kind']=='function'}
|
|
178
182
|
for path,tree in trees.items():
|
|
179
183
|
module={'id':path+'::<module>','path':path,'name':'<module>','start_line':1,'end_line':1,'kind':'module','language':'python'}
|
|
180
184
|
used_module=False
|
|
@@ -216,8 +220,20 @@ def _python_graph(sources):
|
|
|
216
220
|
if target:
|
|
217
221
|
if owner is module:used_module=True
|
|
218
222
|
if len(calls)<MAX_EDGES:calls.append({'source':owner['id'],'target':target['id'],'line':n.lineno,'kind':'construct' if target['kind']=='class' else 'call','resolution':'static'})
|
|
223
|
+
else:dropped['calls']+=1
|
|
219
224
|
elif len(unresolved)<1000:
|
|
220
225
|
unresolved.append({'path':path,'line':n.lineno,'expression':expr or '<dynamic expression>','reason':'External, dynamic or unresolved target in this snapshot.'})
|
|
226
|
+
# A function handed over as a value (callback, thread target, dispatch table) runs later through the receiver.
|
|
227
|
+
skipped={id(n.func) for n in local if isinstance(n,ast.Call)}|{id(n.value) for n in local if isinstance(n,ast.Attribute)}
|
|
228
|
+
for n in local:
|
|
229
|
+
if not isinstance(n,(ast.Name,ast.Attribute)) or not isinstance(n.ctx,ast.Load) or id(n) in skipped \
|
|
230
|
+
or (n.id if isinstance(n,ast.Name) else n.attr) not in function_names:
|
|
231
|
+
continue
|
|
232
|
+
target=resolve(path,qual,chain(n),shadow,instances)
|
|
233
|
+
if target and target['kind']=='function' and target['id']!=owner['id']:
|
|
234
|
+
if owner is module:used_module=True
|
|
235
|
+
if len(calls)<MAX_EDGES:calls.append({'source':owner['id'],'target':target['id'],'line':n.lineno,'kind':'reference','resolution':'static'})
|
|
236
|
+
else:dropped['calls']+=1
|
|
221
237
|
for child in ast.iter_child_nodes(node):
|
|
222
238
|
if isinstance(child,(ast.FunctionDef,ast.AsyncFunctionDef,ast.ClassDef)):
|
|
223
239
|
visit_scope(child,scopes[id(child)])
|
|
@@ -231,7 +247,7 @@ def _python_graph(sources):
|
|
|
231
247
|
visit_scope(tree)
|
|
232
248
|
if used_module:symbols.append(module)
|
|
233
249
|
return {'symbols':symbols,'dependencies':dependencies[:MAX_EDGES],'calls':calls,'unresolved':unresolved,
|
|
234
|
-
'diagnostics':diagnostics,'parsed':list(trees),'truncated':
|
|
250
|
+
'diagnostics':diagnostics,'parsed':list(trees),'truncated':any(dropped.values()) or len(dependencies)>MAX_EDGES}
|
|
235
251
|
|
|
236
252
|
|
|
237
253
|
NODE_HEAP_MB = (1024, 4096)
|
|
@@ -262,7 +278,7 @@ def _javascript_graph(sources, all_paths=None):
|
|
|
262
278
|
try:
|
|
263
279
|
return _run_analyzer('code_graph_js.cjs',
|
|
264
280
|
json.dumps({'files':[{'path':path,'text':text} for path,text in relevant.items()],
|
|
265
|
-
'paths':list(all_paths or sources)},ensure_ascii=False),
|
|
281
|
+
'paths':list(all_paths or sources),'limits':ANALYZER_LIMITS},ensure_ascii=False),
|
|
266
282
|
'The TypeScript analyzer did not finish. Check the local code-analysis runtime.')
|
|
267
283
|
except (OSError,subprocess.TimeoutExpired,ValueError,RuntimeError) as exc:
|
|
268
284
|
return {'diagnostics':[{'path':'JavaScript/TypeScript','reason':str(exc)[:250]}],'parsed':[],'retryable':True}
|
|
@@ -272,7 +288,7 @@ def _java_graph(sources):
|
|
|
272
288
|
files=[{'path':path,'text':text} for path,text in sources.items() if path.lower().endswith('.java')]
|
|
273
289
|
if not files:return {}
|
|
274
290
|
try:
|
|
275
|
-
return _run_analyzer('code_graph_java.mjs',json.dumps({'files':files},ensure_ascii=False),
|
|
291
|
+
return _run_analyzer('code_graph_java.mjs',json.dumps({'files':files,'limits':ANALYZER_LIMITS},ensure_ascii=False),
|
|
276
292
|
'The Java analyzer did not finish. Check the local runtime.')
|
|
277
293
|
except (OSError,ValueError,RuntimeError,subprocess.TimeoutExpired) as exc:
|
|
278
294
|
return {'diagnostics':[{'path':'Java','reason':str(exc)[:250]}],'parsed':[],'retryable':True}
|
|
@@ -285,10 +301,11 @@ def _analyze(path):
|
|
|
285
301
|
def _analyze_sources(files,sources,diagnostics,truncated):
|
|
286
302
|
merged={'symbols':[],'dependencies':[],'calls':[],'unresolved':[],'diagnostics':diagnostics,'parsed':[]}
|
|
287
303
|
retryable=False
|
|
288
|
-
for output in (_python_graph(sources),_javascript_graph(sources,[f['path'] for f in files]),_java_graph(sources),code_graph_go.analyze(sources),web_document_graph.analyze(sources,[f['path'] for f in files])):
|
|
304
|
+
for output in (_python_graph(sources),_javascript_graph(sources,[f['path'] for f in files]),_java_graph(sources),code_graph_go.analyze(sources,ANALYZER_LIMITS),web_document_graph.analyze(sources,[f['path'] for f in files])):
|
|
289
305
|
for key in merged:merged[key].extend(output.get(key,[]))
|
|
290
306
|
truncated |= output.get('truncated',False)
|
|
291
307
|
retryable |= output.get('retryable',False)
|
|
308
|
+
truncated |= len(merged['symbols'])>MAX_SYMBOLS
|
|
292
309
|
by_id={sym['id']:sym for sym in merged['symbols'][:MAX_SYMBOLS]}
|
|
293
310
|
# Relações repetidas preservam contagem e locais de chamada sem poluir o desenho.
|
|
294
311
|
def collapse(rows,fields):
|
|
@@ -479,7 +496,7 @@ def build(root,view_id=None,storage_id=None,file_path=None,background=False):
|
|
|
479
496
|
data.update(views=inventory['views'],selected=inventory['selected'],current_view=inventory['current_view'],
|
|
480
497
|
message=inventory['message'],read_only=True,source='indexed_snapshot',generated_at=time.time(),
|
|
481
498
|
limits={'files':MAX_FILES,'symbols':MAX_SYMBOLS,'edges':MAX_EDGES,'display_nodes_default':120},
|
|
482
|
-
languages=['Java','Angular','Python','JavaScript','TypeScript','JSX','TSX','HTML','CSS','Markdown'],cache_hit=was_cached)
|
|
499
|
+
languages=['Java','Angular','Python','JavaScript','TypeScript','JSX','TSX','Go','HTML','CSS','Markdown'],cache_hit=was_cached)
|
|
483
500
|
return _focus(data,file_path) if file_path else data
|
|
484
501
|
|
|
485
502
|
|