@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 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.57 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
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.57 install
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 in
119
- `output_config_routes`, which is `["vertex_ai"]` by default; `response_format`, applied on every gateway route, for all
120
- others, Bedrock included), `response_format` or `output_config`; `output_config` for a route outside the list is
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`) and the research model. Any id the gateway accepts works; the catalog is
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), in
212
- Claude Code edits and Codex patches. Private (`_name`, `#name`, `private`), nested and override (`@Override`,
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
- - **Remind** (default): the edit runs and the agent is told which touched functions have no docstring, and which
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 Go and Rust documentation and duplicate hooks stay silent.
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, 0o600)
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 = 3
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 = 8000
32
- MAX_EDGES = 20000
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':len(symbols)>=MAX_SYMBOLS or len(dependencies)>MAX_EDGES}
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