@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 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.61 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
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.61 install
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` (another free port is used, and announced, if 8765 is taken).
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 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
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`. It opens on
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`) and the research model. Any id the gateway accepts works; the catalog is
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), in
212
- Claude Code edits and Codex patches. Private (`_name`, `#name`, `private`), nested and override (`@Override`,
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
- - **Remind** (default): the edit runs and the agent is told which touched functions have no docstring, and which
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 Go and Rust documentation and duplicate hooks stay silent.
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, 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