@allansantos-dev/smart-tool 0.9.61 → 0.9.66
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 +142 -0
- package/README.md +65 -14
- 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/daemon_launcher.py +4 -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/endpoint_sync.py +4 -2
- package/hook_decision.py +62 -14
- package/install.py +2 -2
- 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 +10 -2
- package/setup_ui.py +21 -6
- package/smart_tool_daemon.py +66 -15
- package/usage_meter.py +6 -1
- package/version.py +1 -1
- package/web_fetch.py +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,147 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.66 - beta
|
|
4
|
+
|
|
5
|
+
- A daemon that starts while its port is busy retries that port for a few seconds, re-checking `/health`, before it
|
|
6
|
+
moves to the next candidate. A restart that overlapped the shutdown of the old daemon, two starts at once or a
|
|
7
|
+
loaded machine used to move the daemon to another port and rewrite the client files, leaving open Claude Code
|
|
8
|
+
sessions calling the old hook address (`smart_tool_daemon.py`, `tests/test_endpoint_sync.py`). The port preferred
|
|
9
|
+
at start also reads the Codex MCP address when Claude Code holds none (`endpoint_sync.py`).
|
|
10
|
+
- `daemon.json` is written whole (temporary file and replace) and a daemon removes it at exit only when its `pid` is
|
|
11
|
+
the one recorded, so an old daemon closing late no longer erases the announcement of the new one.
|
|
12
|
+
- The launcher and the installer take a daemon as up only when `/health` answers `status: ok`, not on any HTTP 200
|
|
13
|
+
from another program that now holds a stale port (`daemon_launcher.py`, `install.py`). The launcher waits up to
|
|
14
|
+
20 s for a start, enough for the port retry.
|
|
15
|
+
- README: the setup address and the port rule describe `daemon.json`.
|
|
16
|
+
|
|
17
|
+
## 0.9.65 - beta
|
|
18
|
+
|
|
19
|
+
- An entry paragraph of `functional.md` and `simple.md` records the code it was written for (`code="..."` in its
|
|
20
|
+
marker): when the body of the function changes under the same signature, `action=docs check=true` reports
|
|
21
|
+
`prose_stale` and the validation fails the markers check. Before, a paragraph describing old behaviour passed both
|
|
22
|
+
with score 100. Empty the block and run `write_prose=true` again, or rewrite it by hand and delete the stamp
|
|
23
|
+
(`doc_scope.py`, `doc_validate.py`, `doc_prose.py`, `tests/test_doc_scope.py`, `tests/test_doc_prose.py`).
|
|
24
|
+
- The code graph records a function handed over as a value (callback, thread target, signal handler, dispatch table,
|
|
25
|
+
`http.HandleFunc` handler) as a `reference` edge, in Python and Go. Dead-code candidates drop the functions used this
|
|
26
|
+
way or by module-level code, and unnamed `callback`/`anonymous` functions: on three real projects the list went from
|
|
27
|
+
13 to 5 and from 18 to 4, every removed one a real use (`code_graph.py`, `code_graph_go.py`, `doc_insights.py`,
|
|
28
|
+
`tests/test_code_graph_limits.py`, `tests/test_code_graph_go.py`, `tests/test_doc_insights.py`).
|
|
29
|
+
- `write_prose=true` rejects a paragraph that is not in English and asks again with the reason; the instruction also
|
|
30
|
+
tells the model to describe only what the context shows, not a behaviour guessed from the names of the functions it
|
|
31
|
+
calls, and not to open with "This feature". In the measured run 8 of 242 written paragraphs were in Portuguese
|
|
32
|
+
(`doc_prose.py`, `tests/test_doc_prose.py`).
|
|
33
|
+
- The calls of `write_prose=true` are counted in the usage meter under the `docs` purpose of the project
|
|
34
|
+
(`usage_meter.py`).
|
|
35
|
+
- A model failure is blamed on the role that made the call: when the docs model and the router model are the same model,
|
|
36
|
+
a timed-out `write_prose` call warned "router_model failed" and the setup screen counted it under the router
|
|
37
|
+
(`model_health.py`, `tests/test_model_health.py`).
|
|
38
|
+
- `write_prose=true` accepts a paragraph whose code span holds angle brackets, such as `logs/<name>.log` copied from a
|
|
39
|
+
docstring: it was rejected as HTML on every attempt (`doc_prose.py`, `tests/test_doc_prose.py`).
|
|
40
|
+
- Line numbers in `docs/scope` stay right in files with a form feed or other line separators Python's `splitlines`
|
|
41
|
+
splits on (`doc_check.py`, `doc_extras.py`, `tests/test_doc_check.py`, `tests/test_doc_extras.py`).
|
|
42
|
+
- The validation notes, instead of failing, a manifest command that runs a file which is not in the repository (a build
|
|
43
|
+
output such as `bin/...`) (`doc_validate.py`, `tests/test_doc_validate.py`).
|
|
44
|
+
|
|
45
|
+
## 0.9.64 - beta
|
|
46
|
+
|
|
47
|
+
- `project_manage action=docs write_prose=true` writes the empty prose blocks of `docs/scope` with the new docs model
|
|
48
|
+
role (`docs_model`, "Docs model" in the setup screen, filled with Claude Haiku 5.5 when the gateway has it). Each block
|
|
49
|
+
is a task of its kind (module, entry point, plain-language entry point, overview) with a fixed instruction and a
|
|
50
|
+
context read from the code (docstrings, signatures, source, flow, command line, tests, manifest and README), marked as
|
|
51
|
+
data the model must not obey. A paragraph is written only when every name, option and version it cites exists in the
|
|
52
|
+
code and its form fits the kind; a rejected one is asked again once with the reason, then left empty and reported with
|
|
53
|
+
its fix, without the model's text. A call stops after about 40 s, under the MCP client's tool timeout, and says how
|
|
54
|
+
many blocks are left; the regeneration that follows validates the prose again (`doc_prose.py`,
|
|
55
|
+
`tests/test_doc_prose.py`). The model was chosen by measuring seven candidates on 36 blocks of a real project each,
|
|
56
|
+
judged by Claude Opus 5.5 (`docs/research/2026-11-05-modelo-e-instrucao-da-prosa.md`).
|
|
57
|
+
- Structured output sends Anthropic's `output_config` only to Claude models: Gemini on the `vertex_ai` route ignored it
|
|
58
|
+
and answered loose text, so every structured call with a Gemini model failed (`tests/test_structured_output.py`).
|
|
59
|
+
|
|
60
|
+
## 0.9.63 - beta
|
|
61
|
+
|
|
62
|
+
- `action=docs generate=true` validates what it wrote, and `action=docs validate=true` runs the same validation alone:
|
|
63
|
+
every claim of `docs/scope` is checked against the code and the report `docs/scope/validation.md` gives pass/fail per
|
|
64
|
+
check with evidence, a score and the verdict (fail, pass with prose pending, or pass). The checks: anchors and
|
|
65
|
+
signatures, every relative link, line numbers, callers/calls/tests against the graph, the declared coverage and the
|
|
66
|
+
undocumented gaps, why each entry point is one and its flow, the scripts the manifests and `__main__` blocks run, the
|
|
67
|
+
command lines, the names, options and versions the written prose cites, the tests per entry point, link labels,
|
|
68
|
+
counts and the project name across pages, the glossary, navigation from the index, and the dependency versions. A
|
|
69
|
+
failing validation leads the guidance of `generate` (`tests/test_doc_validate.py`).
|
|
70
|
+
- `functional.md` gains a "Command line" section with the commands, arguments, options, defaults and help the code
|
|
71
|
+
declares with argparse (read from the syntax tree, loops over literal names expanded), and the functions a
|
|
72
|
+
`__main__` block runs are entry points. Links to entry points carry their file when the name repeats, and
|
|
73
|
+
`simple.md` takes the project name from `pyproject.toml`, `package.json`, `Cargo.toml` or `go.mod`.
|
|
74
|
+
- Go joins the code graph: functions, methods, types and interfaces with static calls resolved within the package and
|
|
75
|
+
through imports, so `graph`, `affected_tests`, the duplicate check and the documentation check read Go code. The
|
|
76
|
+
documentation check follows the revive `exported` rule: a doc comment must start with the declared name, and one
|
|
77
|
+
that does not is reported as malformed. On a real Go project: 262 symbols and 289 calls in 0.52 s
|
|
78
|
+
(`tests/test_code_graph_go.py`, `tests/test_doc_check.py`).
|
|
79
|
+
- `project_manage action=layers` declares the project's layers, highest first, each by path globs and annotations,
|
|
80
|
+
as import-linter's layers contract, ArchUnit and dependency-cruiser define them. Without a rule it suggests one from
|
|
81
|
+
folder names and annotations, with the files, symbols and calls between layers (down or against the order); a rule
|
|
82
|
+
passed in `layers` is a preview until `confirm=true` saves it to `.smart-tool/layers.json` (`tests/test_layers.py`).
|
|
83
|
+
- `action=pr_impact` (read-only) returns a Markdown impact report of the change set against `base`: touched functions
|
|
84
|
+
with their callers, documentation anchors left out of date in the changed files, and the tests to run with their
|
|
85
|
+
commands; it joins `code_impact`, `affected_tests` and the documentation check and publishes nothing
|
|
86
|
+
(`tests/test_pr_impact.py`).
|
|
87
|
+
- `action=docs generate=true` writes five more optional pages, on by default with opt-outs `hotspots`, `coupling`,
|
|
88
|
+
`dead_code`, `tour` and `glossary`: hotspots (commits × lines, the method code-maat publishes), hidden change coupling
|
|
89
|
+
(shared commits over average commits, bulk commits skipped, pairs that already import each other only counted),
|
|
90
|
+
dead-code candidates (no static caller, or only tests), an onboarding tour of the entry points, and a glossary of the
|
|
91
|
+
words in function names that also feeds `simple.md`. The `adr` page gains decision candidates from the git log (decision
|
|
92
|
+
wording or a dependency-manifest change) with drafts for the latest. Without readable git history the pages say so
|
|
93
|
+
(`tests/test_doc_insights.py`). No code of the GPL code-maat is used.
|
|
94
|
+
- `action=docs generate=true` also writes ten optional documents beside the scope, all from the code graph and all on
|
|
95
|
+
by default, each with its own opt-out in `docs_extras` of `config.json` (`structure`, `coverage`, `modules`, `tests`,
|
|
96
|
+
`configuration`, `dependencies`, `adr`, `flows`, `features_tests`, `index`; an unknown key or a non-boolean fails
|
|
97
|
+
naming the config path): the folder structure drawn without `tree`, the docstring coverage per folder, the module
|
|
98
|
+
Mermaid, the tests README linked to the functional anchors, the configuration the code reads (environment variables,
|
|
99
|
+
config files, ports), the external dependencies with the licenses of the installed packages only, the decision
|
|
100
|
+
record index with an ADR template, a Mermaid sequence per entry point, and the entry points × tests matrix. The flows
|
|
101
|
+
and matrix pages carry signature markers, so `action=docs check=true` and the edit hook cover them. The short index
|
|
102
|
+
goes between `smart-tool:index` markers in an existing `AGENTS.md` (or `llms.txt`) and is never created; regeneration
|
|
103
|
+
replaces only the block and unbalanced markers fail. Every page repeats the `truncated` warning of the graph
|
|
104
|
+
(`tests/test_doc_extras.py`). Measured: on Smart Tool itself 105 files, 910 KB (62 KB of them extras) in 8.0 s with
|
|
105
|
+
`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.
|
|
106
|
+
- `project_manage action=docs generate=true` writes the documentation scope to `docs/scope` from the code graph,
|
|
107
|
+
without a model: technical pages by folder, or by module when a folder has more than 150 public functions, with an
|
|
108
|
+
entry per public function (anchor `path::name`, signature, first
|
|
109
|
+
doc line, layer, callers, calls, the tests that reach it) and a Mermaid flow of the folders by layer;
|
|
110
|
+
`functional.md` with each entry point and the functions its calls reach, by layer; `simple.md`. The agent writes the
|
|
111
|
+
prose between prose markers and regeneration keeps it, as terraform-docs keeps the text around its block; a file
|
|
112
|
+
Smart Tool did not write is never overwritten. On a real Go project with three declared layers: 95 public
|
|
113
|
+
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
|
|
114
|
+
pages, the largest 53 KB (`tests/test_doc_scope.py`).
|
|
115
|
+
- Each documentation anchor records the signature it was generated from, like Swimm's smart tokens:
|
|
116
|
+
`action=docs check=true` lists anchors whose function changed signature or is gone and links to missing anchors,
|
|
117
|
+
`action=docs symbol=NAME` tells where a function is documented, and the documentation hook warns when an edit makes
|
|
118
|
+
a documented entry out of date. The link lives in the documents and the query, never inside docstrings.
|
|
119
|
+
- The edit hook now keeps documentation in the docstring by default: `doc_mode` defaults to `require` (was `remind`)
|
|
120
|
+
and the new `comment_mode` (`require`, `remind`, `off`; default `require`) blocks, among the comments an edit adds or
|
|
121
|
+
changes in a code file, commented-out code, ticket, version and history tags, a loose block above a function instead
|
|
122
|
+
of its docstring and a block of more than two lines inside a body. A short comment that says why, directives and
|
|
123
|
+
dividers pass. Opt out with `"doc_mode": "off"` and `"comment_mode": "off"` (or Off on both cards of the setup
|
|
124
|
+
screen); a setting already saved is kept, so documentation generated afterwards finds every function documented in
|
|
125
|
+
place (`tests/test_comment_check.py`).
|
|
126
|
+
|
|
127
|
+
## 0.9.62 - beta
|
|
128
|
+
|
|
129
|
+
- The code graph keeps up to 100,000 symbols and 250,000 edges (calls and dependencies); before, it stopped at 8,000
|
|
130
|
+
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,
|
|
131
|
+
of which the graph kept 8,000 and 6,852. The Python analyzer passes its limits to the JS/TS and Java analyzers, and
|
|
132
|
+
`truncated` is set only when a symbol or an edge was really left out, including symbols of several languages that
|
|
133
|
+
fit one by one but not together; before, `counts.symbols` could report 8,190 for a project with 17,651
|
|
134
|
+
(`tests/test_code_graph_limits.py`).
|
|
135
|
+
- The Java analyzer starts in 0.2 s instead of 1.1 s. java-parser reaches chevrotain's sources and lodash one module
|
|
136
|
+
file per function, 744 files read on every run; with Node's `module.registerHooks` the analyzer loads chevrotain's
|
|
137
|
+
own bundle and lodash's single file instead, with byte-identical output on 167 and 199 real files (36 files: 1.76 s
|
|
138
|
+
→ 0.84 s; 199 files: 6.91 s → 3.80 s). A Node without `registerHooks` loads java-parser as published.
|
|
139
|
+
- Duplicate and documentation checks analyze many TypeScript or Java files in one analyzer run per language instead
|
|
140
|
+
of one run per file (`doc_check.analyze_files`): 36 Java files took 28.7 s before.
|
|
141
|
+
- A search in a folder of the system's temporary folder runs natively unless a registered project holds it. The
|
|
142
|
+
session folder used to count as a project there, so the redirected `smart_search` registered and indexed a copy
|
|
143
|
+
made for a measurement or a build (`tests/test_router.py`).
|
|
144
|
+
|
|
3
145
|
## 0.9.61 - beta
|
|
4
146
|
|
|
5
147
|
- Old Camoufox builds leave the user's cache. camoufox 0.5.6 installs each build in its own folder and never deletes
|
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.66 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.66 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
|
|
@@ -105,7 +105,9 @@ version came out minutes ago); `~/.smart-tool` is kept. It downloads [uv](https:
|
|
|
105
105
|
verified) and a private Python 3.12 into `~/.smart-tool/runtime`, with nothing added to `PATH` and, in the registry, only two per-user (HKCU) keys that make the notification buttons work, then
|
|
106
106
|
copies Smart Tool to `%LOCALAPPDATA%\Programs\SmartTool` with its own virtual environment,
|
|
107
107
|
installs the web runtime, registers a per-user Scheduled Task that starts the tray at logon and starts the daemon on
|
|
108
|
-
`http://127.0.0.1:8765
|
|
108
|
+
`http://127.0.0.1:8765`. A busy port is retried for a few seconds (the old daemon may still be closing) and the port
|
|
109
|
+
the clients already hold is kept; another free port is used, and announced in `~/.smart-tool/data/daemon.json`, only
|
|
110
|
+
when a program keeps the port.
|
|
109
111
|
|
|
110
112
|
State lives in `~/.smart-tool`: `config.json`, your model adapters in `adapters/` and indexes, caches and logs in
|
|
111
113
|
`data/`. Secrets (API keys) are encrypted with Windows DPAPI for your user.
|
|
@@ -115,15 +117,15 @@ searches, the router's tier and sufficiency decisions, the index profile and the
|
|
|
115
117
|
`temperature`, and the answer is validated against the schema before use. A stop other than a normal one (cut at the
|
|
116
118
|
token limit, refusal), an empty answer, a missing field or a value outside an enum fails the call with its reason
|
|
117
119
|
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
|
|
120
|
+
`mode` is `auto` (default: `output_config` for the Claude models whose route, the id prefix before the first dot, is
|
|
121
|
+
in `output_config_routes`, which is `["vertex_ai"]` by default; `response_format`, applied on every gateway route, for
|
|
122
|
+
all others, Bedrock and Gemini on Vertex included), `response_format` or `output_config`; `output_config` for a model
|
|
123
|
+
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
124
|
are left out of the request and the code that reads the answer keeps enforcing them.
|
|
123
125
|
|
|
124
126
|
## Set up
|
|
125
127
|
|
|
126
|
-
Open the setup screen from the tray icon ("Open settings") or at `http://127.0.0.1:8765/setup
|
|
128
|
+
Open the setup screen from the tray icon ("Open settings") or at `/setup` on the daemon address in `~/.smart-tool/data/daemon.json` (`http://127.0.0.1:8765/setup` by default). It opens on
|
|
127
129
|
**Overview**: everything Smart Tool needs, checked on this machine, with what needs you first and a button that takes
|
|
128
130
|
you to the fix. The side menu groups the rest under Connect (Agents, Models, Web search), Behavior (Agent rules,
|
|
129
131
|
Redirects) and Maintenance (Setup audit, Startup).
|
|
@@ -133,7 +135,8 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
133
135
|
`https://openrouter.ai/api/v1`, `http://localhost:11434/v1`), and an optional API key. Saving tests `/models` first.
|
|
134
136
|
2. **Models**: embedding, rerank (optional; without it results use the hybrid order), the router model (small, no
|
|
135
137
|
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`)
|
|
138
|
+
scout model (the short answer of `smart_scout`), the research model and the docs model (the prose of the generated
|
|
139
|
+
documentation). Any id the gateway accepts works; the catalog is
|
|
137
140
|
shown as suggestions. Empty roles are filled with the recommended models the gateway offers.
|
|
138
141
|
|
|
139
142
|
When a new version recommends other models than the ones you use, a Windows notification (**Apply now**, **Don't
|
|
@@ -208,19 +211,67 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
208
211
|
- **Advise only**: the native tool runs; the agent receives the same advice next to the result and decides.
|
|
209
212
|
- **Off**: no routing.
|
|
210
213
|
|
|
211
|
-
**Documentation on edit** checks the public functions an edit touches (Python docstrings, JSDoc, Javadoc
|
|
212
|
-
|
|
214
|
+
**Documentation on edit** checks the public functions an edit touches (Python docstrings, JSDoc, Javadoc, and Go
|
|
215
|
+
doc comments, which must start with the declared name as the revive `exported` rule asks), in Claude Code edits and
|
|
216
|
+
Codex patches. Private (`_name`, `#name`, `private`), nested and override (`@Override`,
|
|
213
217
|
`@override`) functions are exempt, as in pydocstyle, eslint-plugin-jsdoc and Checkstyle, and a JSDoc above a set of
|
|
214
218
|
TypeScript overloads documents the implementation:
|
|
215
|
-
- **
|
|
219
|
+
- **Require** (default): an edit that leaves a touched function without a docstring is blocked until it adds one.
|
|
220
|
+
- **Remind**: the edit runs and the agent is told which touched functions have no docstring, and which
|
|
216
221
|
documented ones changed their signature, with their callers, the tests calling them and the command that runs those tests
|
|
217
222
|
(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
223
|
- **Off**: no checks.
|
|
220
224
|
|
|
225
|
+
**Comments in the wrong place** keeps the documentation in the docstring, where `action=docs` reads it. Of the
|
|
226
|
+
comments an edit adds or changes in a code file (not tests), it blocks four kinds: commented-out code (the ruff
|
|
227
|
+
`ERA001` rule), a ticket, version or history tag (`PEDIDO 1304`, `JIRA-12`, `added in v2.1`), a loose comment block
|
|
228
|
+
right above a function instead of its docstring, and a block of more than two lines inside a function body. A
|
|
229
|
+
short comment that says why (`// The gateway drops the first frame after a reconnect.`) passes, as do directives
|
|
230
|
+
(`# noqa`, `//go:build`, `// eslint-disable`), dividers and comments the edit did not touch. `comment_mode` in
|
|
231
|
+
`config.json`: `require` (default, the edit is blocked until the comment is fixed), `remind` (the edit runs and the
|
|
232
|
+
agent is told) or `off`. To turn the whole rule off set `"doc_mode": "off"` and `"comment_mode": "off"` in
|
|
233
|
+
`~/.smart-tool/config.json`, or pick Off on both cards of the setup screen. A setting you already saved stays as
|
|
234
|
+
saved; only a config without the key follows the new default.
|
|
235
|
+
|
|
221
236
|
A documented function edited only in its body is not mentioned. `project_manage` with `action=docs` lists the
|
|
222
237
|
public functions still without a docstring, for documenting a project that started without them.
|
|
223
238
|
|
|
239
|
+
**Documentation scope**: `action=layers` declares the project's layers, highest first (entry points, services,
|
|
240
|
+
domain, data access), each by path globs and annotations, as import-linter's layers contract, ArchUnit and
|
|
241
|
+
dependency-cruiser define them. Without a rule it suggests one from folder names (`cmd`, `handler`, `service`,
|
|
242
|
+
`repository`...) and annotations (`@RestController`, `@Service`, `@app.route`...), with the calls between layers;
|
|
243
|
+
passing `layers` previews a rule and the same `layers` with `confirm=true` saves it to `.smart-tool/layers.json`.
|
|
244
|
+
`action=docs generate=true` writes `docs/scope` in the project from the code graph, without a model: a technical page
|
|
245
|
+
per folder (a page per module when the folder has more than 150 public functions) with an entry per public function
|
|
246
|
+
(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
|
|
247
|
+
public functions of the highest layer and every `main`) and the functions its calls reach, by layer; and
|
|
248
|
+
`simple.md`. `action=docs write_prose=true` writes the empty prose blocks with the docs model (Claude Haiku 5.5 by
|
|
249
|
+
default): each block gets an instruction for its kind (module, entry point, plain-language entry, overview) and a
|
|
250
|
+
context read from the code, and a paragraph is written only when every name, option and version it cites exists in
|
|
251
|
+
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
|
|
252
|
+
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
|
|
253
|
+
or entry point is gone, and never overwrites a file that Smart Tool did not write. Each anchor records the signature
|
|
254
|
+
it was generated from: `action=docs check=true` lists anchors whose function changed signature or is gone, links
|
|
255
|
+
to missing anchors and entry paragraphs written for an older body of their function (the `code="..."` stamp of the
|
|
256
|
+
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
|
|
257
|
+
when an edit makes a documented entry out of date. The link lives in the documents, never inside docstrings.
|
|
258
|
+
The same run writes fifteen optional documents under `docs/scope/extras`, all from the graph and the git log: folder
|
|
259
|
+
structure, docstring coverage per folder, module Mermaid, tests README, configuration read by the code, dependencies
|
|
260
|
+
with the licenses of installed packages, decision index with an ADR template and the decision candidates found in the
|
|
261
|
+
git log, a sequence per entry point, the entry points × tests matrix, hotspots (commits × lines), hidden change
|
|
262
|
+
coupling (files that change together without an import), dead-code candidates, an onboarding tour of the entry
|
|
263
|
+
points and a glossary of the words the code uses (which also feeds `simple.md`). Each is on by default; turn one
|
|
264
|
+
off with `"docs_extras": {"modules": false}` in `config.json` (keys: `structure`, `coverage`, `modules`, `tests`,
|
|
265
|
+
`configuration`, `dependencies`, `adr`, `flows`, `features_tests`, `hotspots`, `coupling`, `dead_code`, `tour`,
|
|
266
|
+
`glossary`, `index`). The history pages say so on the page when the folder has no readable git history. `index`
|
|
267
|
+
keeps a short index of the documentation between `smart-tool:index` markers in an existing `AGENTS.md` or
|
|
268
|
+
`llms.txt`; it never creates the file and rewrites only the block.
|
|
269
|
+
|
|
270
|
+
**Impact of a change**: `project_manage action=pr_impact [base=main]` returns a Markdown report of the change set
|
|
271
|
+
against `base` (default `HEAD`): the touched functions with their callers, the documentation anchors left out of
|
|
272
|
+
date, and the tests to run with their commands. It reads only; publishing it as a pull-request comment is left to
|
|
273
|
+
the CI step that calls it.
|
|
274
|
+
|
|
224
275
|
**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
276
|
|
|
226
277
|
**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 +296,7 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
245
296
|
count before the project is reindexed. `run_all` is true, with
|
|
246
297
|
the reason, when a configuration or lockfile changed or a changed code file is outside the import graph. Go is read
|
|
247
298
|
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
|
|
299
|
+
package that imports it (`go test ./pkg ...`); the Rust documentation and duplicate hooks stay silent.
|
|
249
300
|
|
|
250
301
|
`project_manage` with `action=setup_audit` and a `project_root` (or `python setup_audit.py --project <folder>`)
|
|
251
302
|
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
|
|