@allansantos-dev/smart-tool 0.9.79 → 0.9.80

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,72 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.80 - beta
4
+
5
+ - The document converter keeps its results in one folder per version, `%LOCALAPPDATA%\SmartTool\cache\<version>\convert`,
6
+ named by a hash of the file content, the engine and the OCR flag: the same file read again is answered from that folder
7
+ without starting the engine, a second run creates no file, two runs at once make one, a failed read leaves nothing, and
8
+ the folders of older versions are deleted the first time it is used. It no longer makes a new temporary folder in the
9
+ system temp for every read. Tests: `tests/test_document_converter.py`.
10
+ - The edit hook also notes a credential an edit writes, in any file: only on the lines the edit adds or changes, and only
11
+ for shapes that cannot be anything else (GitHub, Slack, Stripe live, Anthropic and npm tokens, Google API keys, AWS
12
+ access key ids and secret key lines, a private-key header at the start of a line). Lines that say they are an example are
13
+ skipped, the note names the file and line and never repeats the value, and it never blocks. Tests:
14
+ `tests/test_credential_check.py`.
15
+ - `project_manage action=pr_impact` adds two sections: the files that usually change in the same commits as the diff's files
16
+ and are missing from it (the history coupling of `doc_insights`, import-linked pairs left out), and the decision notes and
17
+ commit messages that name a touched function. A single-word function name counts only as a code reference (backticks or a
18
+ call), because words such as `load` or `report` are ordinary prose: measured on this repository, the bare-word match
19
+ returned unrelated notes for most single-word names. Tests: `tests/test_pr_impact.py`, `tests/test_code_health.py`.
20
+ - The dependency check reads `Cargo.toml` (crates.io: the dependency, dev-dependency and build-dependency tables, `target.*`
21
+ and `workspace.dependencies`; path, git and `workspace = true` entries are not registry packages) and `pom.xml` (Maven:
22
+ `groupId:artifactId`, `${property}` versions resolved from the pom's own properties; a range or a version inherited from a
23
+ parent or BOM is reported as not verified), on an edit and in the audit. The OSV names `crates.io` and `Maven` come from
24
+ the OSV schema. Tests: `tests/test_dependency_manifests.py`.
25
+ - Web search page: a table of who asked the recent searches, one row per client and project folder (sessions, calls,
26
+ failures, last call, how the requester was attributed), read from the log the search tiers already write; the text of a
27
+ search is never recorded. Tests: `tests/test_web_search_requesters.py`.
28
+ - Startup page: an automatic update card with the switch (the same `auto_update` key as the tray menu), the installed
29
+ version, the last npm check, the last update, a failed automatic try and the manual command, read from the state file with
30
+ no network call; the switch is refused while `SMART_TOOL_AUTO_UPDATE=off` is set, as in the tray. Tests:
31
+ `tests/test_update_card.py`.
32
+ - The browsers Smart Tool starts with Chromium (the Playwright MCP server the agent drives, its start-up probe, the
33
+ Tier 4 crawl) no longer scan USB devices: they carry `WebUsbDeviceDetection` in their `--disable-features`. The scan
34
+ ran a few seconds after launch and froze a USB microphone that was recording. Chromium keeps only the last
35
+ `--disable-features` switch and Playwright appends the caller's arguments after its own list, so the switch repeats
36
+ the list of the Playwright bundle in use and adds the feature; a bundle where that list cannot be found fails loudly.
37
+ Existing installs pick it up on the next update. Tests: `tests/test_chromium_flags.py`
38
+ (`docs/research/2026-11-17-webusb-do-navegador-de-automacao.md`).
39
+ - `web_fetch` reads Word, PowerPoint and Excel files by URL (docx, pptx, xlsx): by content type, or by the extension
40
+ in the URL when the server sends a generic binary type, through the extractor the index uses and its archive guards.
41
+ A file that cannot be read says why. Tests: `tests/test_web_fetch.py`.
42
+ - `project_manage action=deps` lists the OSV advisories of every dependency the project's manifests declare, in
43
+ batches of 100 per ecosystem (the edit notice shares the cache). `smart_search mode=dossier history=true` also
44
+ searches commit messages, and `smart_search decision_notes=true` appends the project's decision notes to a search
45
+ answer; both default to off. Tests: `tests/test_sister_candidates.py`.
46
+ - `read_document` also reads HTML (`.html`, `.htm`), CSV and EPUB files with no new dependency: the standard HTML and
47
+ CSV parsers, and the archive guards of the Office formats for the epub package (its chapters are read in spine
48
+ order). A page or book in an encoding the reader cannot use, or over the text budget, fails with the reason. Tests:
49
+ `tests/test_document_formats.py`.
50
+ - The dependency check reads `pyproject.toml` (`project.dependencies` and `project.optional-dependencies`; Poetry
51
+ tables are not read), both on an edit and in the audit. `project_manage action=deps` asks OSV about the version a
52
+ `package-lock.json` beside a `package.json` resolved when it satisfies the range (a stale lock, or a dependency missing
53
+ from it, keeps the lower bound of the range). The setup audit runs the same check for every registered project and
54
+ reports a warning per manifest with advisories, or a note when OSV cannot answer; the 6-hour advisory cache keeps the
55
+ 30-minute schedule from asking again. `read_document` and the index read `.xlsm` workbooks like `.xlsx` (XML parts
56
+ only; `.xlsb`, `.xls`, `.ppt` and `.pptm` stay unread). Tests: `tests/test_second_lens.py`.
57
+ - `project_manage action=pr_impact` lists the tests that reach each touched function, the functions no test reaches and
58
+ the notes the edit hook would have added to the whole diff, so commits made without the hook get the same checks.
59
+ New actions `hotspots`, `dead_code`, `import_cycles` and `comments` answer the questions the generated pages hold
60
+ without writing them. `layer_mode` (default `warn`, on the setup screen) flags an edit that adds a call from a lower
61
+ layer to a higher one of the confirmed layers. `smart_search` takes `folder` and `layer`, applied before ranking. The
62
+ setup screen shows the 30-day model use over every project and an hourly volume alert (twice the busiest hour of the
63
+ purpose's previous week, at least 100, mutable for 7 days, never a notification). Tests: `tests/test_pr_impact.py`,
64
+ `tests/test_code_health.py`, `tests/test_layer_check.py`, `tests/test_search_scope.py`,
65
+ `tests/test_usage_overview.py`.
66
+ - `smart_scout` answers with the best excerpt of a PDF, docx, pptx or xlsx: the window is chosen from the lines the
67
+ index stored for the file (`indexer.indexed_lines`) instead of falling back to the search snippet, and the document
68
+ is never extracted again. A file the index holds no lines of keeps the snippet. Tests: `tests/test_scout.py`.
69
+
3
70
  ## 0.9.79 - beta
4
71
 
5
72
  - A graph cut by its limits says what it left out: `left_out` with the files, symbols and call or import relations
package/README.md CHANGED
@@ -8,7 +8,7 @@ A local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharpe
8
8
  | `smart_scout` | Answers a question about the code with the lines that answer it: reads the candidate files inside Smart Tool and returns `path:lines` with the literal text, so the files never enter the agent's context; with a `scout_model`, a small model also writes a short answer and keeps only the lines that support it; a question about why something is as it is (why, reason, decided) also lists up to three decision notes from the notes the project keeps about its intent, as ids with one excerpt each |
9
9
  | `web_search` / `web_search_result` | Web search across several sources in parallel, in the query language and in English, with a cache shared across sessions; `depth="research"` runs a multi-round research loop |
10
10
  | `web_fetch` | Reads a known URL and returns only the answer to your prompt, written by a small model; pages are cached for 24 h. Pages over 60,000 characters are not cut: the model reads the parts closest to the prompt (needs an `embedding_model`) |
11
- | `read_document` | Reads a PDF, Word, PowerPoint or Excel file as compact text, a range at a time: type, size, page/slide/sheet count and estimated tokens first, then only the pages, slides or sheets asked for (`range="3-5"`), so the file never enters the agent's context whole. Opt-in: the native Read is not redirected. Scanned PDFs fail with that reason (no OCR) |
11
+ | `read_document` | Reads a PDF, Word, PowerPoint, Excel, HTML, CSV or EPUB file as compact text, a range at a time: type, size, page/slide/sheet/part/chapter count and estimated tokens first, then only the units asked for (`range="3-5"`), so the file never enters the agent's context whole. Opt-in: the native Read is not redirected. Scanned PDFs fail with that reason (no OCR) |
12
12
  | `project_manage` | Registers and indexes projects, shows coverage, code maps, duplicated functions and index storage; `graph` with `symbol` tells what changing a function touches: callers, calls, the tests that reach it and the files that import it |
13
13
 
14
14
  Agents that must click, type or log in also get Microsoft's [Playwright MCP](https://github.com/microsoft/playwright-mcp),
@@ -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.79 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
20
+ **Status:** 0.9.80 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
21
21
 
22
22
  ## How it works
23
23
 
@@ -59,7 +59,8 @@ session on the machine, so the same question asked twice costs nothing the secon
59
59
  **Reading a page.** `web_fetch` takes a URL and a question. It downloads the page over plain HTTP; when the page only
60
60
  shows its content with JavaScript, it opens it in a headless browser ([Moli](https://github.com/lexmount/moli)
61
61
  first, Chromium as the fallback), which never reaches this machine or your local network. PDFs are read as text, page
62
- by page. A small model then reads the page and returns only the answer, with the source.
62
+ by page, and so are Word, PowerPoint and Excel files (docx, pptx, xlsx), by content type or by the extension of the URL
63
+ when the server sends a generic binary type. A small model then reads the page and returns only the answer, with the source.
63
64
  The agent receives a paragraph instead of the whole page.
64
65
 
65
66
  **Steering the agent (optional hook).** Agents keep reaching for their built-in tools out of habit. The hook sees
@@ -83,7 +84,7 @@ gateway such as Ollama, nothing about your code leaves the machine.
83
84
  ## Install
84
85
 
85
86
  ```powershell
86
- npx @allansantos-dev/smart-tool@0.9.79 install
87
+ npx @allansantos-dev/smart-tool@0.9.80 install
87
88
  ```
88
89
 
89
90
  Updates install themselves, on by default: the tray checks npm when it starts (at logon) and every 24 h, and when there
@@ -143,10 +144,13 @@ Redirects) and Maintenance (Setup audit, Startup).
143
144
  show again**) and the **New recommended models** card on this page offer them: nothing changes until you apply, the
144
145
  models you had are kept, and **Switch back to my previous models** undoes it. The **Model failures (last 24 h)** table
145
146
  groups the failed gateway calls by type (429, 503, other 5xx, timeout, connection, authentication) and role, with the count, the first and last time and one sample, and shows the calls per purpose; a model that fails half of its calls (5 or more) also raises a
146
- notification and a tray alert. A failure inside a tool call also comes back as a warning line in the tool answer;
147
+ notification and a tray alert. The **Model use (last 30 days)** card adds the calls, failures and, when the gateway
148
+ reports them, tokens and cost per purpose over every project, and flags a purpose whose calls in one hour pass twice
149
+ its own busiest hour of the previous week (and at least 100); the flag has **Mute for 7 days** and never raises a
150
+ notification. A failure inside a tool call also comes back as a warning line in the tool answer;
147
151
  calls made by a hook or by background work (index scope and profile, block-pattern proposals) have no answer to
148
- carry it, so they show only in the table, the log and the notification. The local embedder is not in that table or in
149
- the usage meter: it is a sidecar on your machine with no price, and its state is the **Local models** section.
152
+ carry it, so they show only in the table, the log and the notification. The embeddings home records its calls and failures there like any other model, with no price; its
153
+ state, and the reason when it cannot identify its model, is the **Embedder** section.
150
154
  3. **Agents**: register the MCP server in Claude Code or Codex (runs their official `mcp add` command), install the
151
155
  hook and choose its behavior under **Agent rules**. A hook written by an older Smart Tool shows as outdated, with
152
156
  what an update changes; updating previews the entry and rewrites only Smart Tool's, after a backup. Every
@@ -268,16 +272,38 @@ Redirects) and Maintenance (Setup audit, Startup).
268
272
  `llms.txt`; it never creates the file and rewrites only the block.
269
273
 
270
274
  **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
-
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`.
275
+ against `base` (default `HEAD`): the touched functions with their callers and the tests that reach them (the ones no
276
+ test reaches are listed apart), the documentation anchors left out of date, the decision notes and commits that name
277
+ a touched function (a single-word name counts only as a code reference), the files that usually change in the same
278
+ commits and are missing from the diff, the notes the edit hook would have added to the whole diff (comments, copies,
279
+ dependency advisories, credentials) and the tests to run with their commands. It reads
280
+ only; publishing it as a pull-request comment is left to the CI step that calls it.
281
+
282
+ **Shape of the project**: `project_manage action=hotspots` ranks the code files by commits times lines (the
283
+ riskiest to change), `dead_code` lists the functions no code calls and those only tests call (static call graph,
284
+ candidates to read before deleting), `import_cycles` lists the groups of files that import each other, and
285
+ `comments` lists comments in the wrong place across the code files (commented-out code, history tags, loose docs,
286
+ long inline blocks), for code written before the edit hook existed. Each takes `limit` and writes nothing.
287
+
288
+ **Layers on edit**: when the project has confirmed layers (`.smart-tool/layers.json`), an edit that adds a call from
289
+ a lower layer to a function of a higher one is flagged to the agent; it never blocks. `layer_mode` in
290
+ `config.json`: `warn` (default) or `off`, also on the setup screen.
291
+
292
+ **Folder and layer in a search**: `smart_search folder="<path>"` (or a list) and `layer="<name>"` restrict the
293
+ search to a folder of the project or to one of its confirmed layers, by their path globs. The filter runs before
294
+ the ranking, so the results are the best inside the scope, not a cut of the global list.
295
+
296
+ **Credential check on edit**: the lines an edit adds or changes in any file are checked for credential shapes that cannot be
297
+ anything else (GitHub, Slack, Stripe live, Anthropic and npm tokens, Google API keys, AWS access key ids and secret key lines, a
298
+ private-key header at the start of a line); the note names the file and line, never repeats the value and never blocks, and a
299
+ line that says it is an example is skipped.
300
+
301
+ **Dependency check on edit**: an edit of `package.json`, `requirements*.txt`, `pyproject.toml` (`project.dependencies` and `project.optional-dependencies`; Poetry tables are not read), `go.mod`, `Cargo.toml` (crates.io registry dependencies) or `pom.xml` (Maven, plain or property-resolved versions) 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`.
276
302
 
277
303
  **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
278
304
  same way: text of each slide under `[slide N]` with the speaker notes under `[notes N]`, each sheet under `[sheet NAME]` with one
279
- tab-separated line per row (cached formula values; 100,000 rows or 1 MiB of text at most). Older formats (`.ppt`, `.xls`,
280
- `.xlsm`) are not read.
305
+ tab-separated line per row (cached formula values; 100,000 rows or 1 MiB of text at most). A macro-enabled `.xlsm` is read
306
+ like an `.xlsx` (its XML parts only, no macro runs). Older formats (`.ppt`, `.xls`, `.xlsb`, `.pptm`) are not read.
281
307
 
282
308
  **Block patterns waiting for you** are shown in one approval panel: 8 per page, the ones that would have blocked
283
309
  the most logged calls first, a filter over pattern, reason and example, and bulk accept or reject of the selected
@@ -306,6 +332,17 @@ Redirects) and Maintenance (Setup audit, Startup).
306
332
  unregisters them and deletes their index files (never the project's own files) and writes a manifest in
307
333
  `junk-manifests`. The daemon applies the same test at start.
308
334
 
335
+ `project_manage action=deps project_root="<project>"` lists the known OSV advisories of every dependency the manifests
336
+ of the project declare (`package.json`, `requirements*.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`), not only the ones an edit changed;
337
+ a `package.json` with a `package-lock.json` beside it is checked at the locked version when it satisfies the range. Only package
338
+ names and versions leave the machine, in batches of 100 per ecosystem. The setup audit runs the same check for every
339
+ registered project (a warning per manifest with advisories; the 6 h cache keeps it from asking OSV on every run).
340
+
341
+ `smart_search mode=dossier history=true` also searches the messages of the commits that have a body, and
342
+ `smart_search decision_notes=true` appends the decision notes of the project (research notes, backlog, CLAUDE.md,
343
+ AGENTS.md and commit messages) to a search answer; both are off by default, and the first read of a repository's
344
+ history can take longer than the dossier budget, which the answer then says.
345
+
309
346
  `project_manage` with `action=setup_audit` and a `project_root` (or `python setup_audit.py --project <folder>`)
310
347
  reports what Claude Code and Codex actually load for that folder (settings layers, enabled plugins of both,
311
348
  hooks, MCP servers, skills, CLAUDE.md and AGENTS.md) and where they collide: several hooks deciding on the same tool in
@@ -335,10 +372,20 @@ Redirects) and Maintenance (Setup audit, Startup).
335
372
  definition in `~/.codex/config.toml`, as `/hooks` would, so no `/hooks` step is left; an entry Codex does not trust
336
373
  shows "Not approved in Codex", and **Update** records it. It is off by default. The hook script
337
374
  (`hooks/session_audit.py`) only asks the running service and prints nothing when the service is down.
338
- 4. **Local models** (optional): if the mcp-memory embedding sidecar is installed on the machine, its local embedder
339
- can serve as a fallback (or preferred) embedding model.
375
+ 4. **Embedder**: the embeddings home (casa-de-embeddings, the embedding service of this machine, found through
376
+ `~/.casa-de-embeddings/run/daemon.json`) is the default; the gateway's `embedding_model` and `rerank_model` are used
377
+ only when you choose **Gateway** here, never in place of a stopped home. The home's embedder is identified by the
378
+ `model_sha256` and `dimension` of its `/info`; a home that answers without them is reported as an error, never
379
+ replaced silently by lexical search. Rerank goes through the home's connector to the rerank host configured in it;
380
+ without one, results keep the hybrid order and say so. Switching the embedder re-embeds each project in the
381
+ background, one at a time: the old index keeps answering, the folder switches to the new index when it is complete,
382
+ and the vectors of the old model are then deleted. While the home is not running, a folder indexed with another model
383
+ keeps answering from that index and is not updated.
340
384
  5. **Web search providers** work without keys on their free public tiers; add your own key for more volume. Set your
341
- own contact (e-mail or URL) if you want public APIs such as Wikimedia to see it in the User-Agent.
385
+ own contact (e-mail or URL) if you want public APIs such as Wikimedia to see it in the User-Agent. The same page lists
386
+ who asked the recent searches (client and project folder, never the text of a search).
387
+ 6. **Automatic updates** (Startup page): the switch the tray menu also has, with the installed version, the last npm check,
388
+ the last update and a failed automatic try; no network call is made to draw it.
342
389
 
343
390
  ## Writing a model adapter
344
391
 
@@ -390,7 +437,7 @@ fails to load is listed in the setup screen with its error and does not affect t
390
437
  ## Uninstall
391
438
 
392
439
  ```powershell
393
- npx @allansantos-dev/smart-tool@0.9.79 uninstall [--target DIR] [--keep-data]
440
+ npx @allansantos-dev/smart-tool@0.9.80 uninstall [--target DIR] [--keep-data]
394
441
  ```
395
442
 
396
443
  It asks nothing and opens no window. It stops the tray and the daemon, removes the logon task, the hook entries of Smart
@@ -29,6 +29,7 @@ import time
29
29
  import tomllib
30
30
 
31
31
  import atomic_io
32
+ import chromium_flags
32
33
  import codex_config
33
34
  import endpoint_sync
34
35
  import install_runtime
@@ -44,14 +45,19 @@ CONFIG_PATH = os.path.join(paths.DATA_DIR, "playwright-mcp.json")
44
45
  HANDSHAKE_PATH = os.path.join(paths.DATA_DIR, "playwright-mcp-handshake.json")
45
46
  PROXY = os.path.join(os.path.dirname(os.path.abspath(__file__)), "lazy_mcp_proxy.py")
46
47
  AGENT_UA_MARK = "SmartToolAgentBrowser"
48
+ MCP_PLAYWRIGHT_BUNDLE = install_runtime.NODE_DIR / "node_modules" / "playwright-core" / "lib" / "coreBundle.js"
47
49
  OUTPUT_MAX_BYTES = 100 * 1024 * 1024
48
50
  PROBE_TIMEOUT_S = 60
49
51
  DENIED_TOOLS = ("browser_run_code_unsafe",)
50
52
  _CODEX_TABLE_RE = re.compile(rf"^\[mcp_servers\.{SERVER}\][ \t]*\r?\n", re.M)
51
- _CHROMIUM_PROBE = ("from playwright.sync_api import sync_playwright\n"
53
+ _CHROMIUM_PROBE = ("import sys\n"
54
+ f"sys.path.insert(0, {os.path.dirname(os.path.abspath(__file__))!r})\n"
55
+ "import chromium_flags\n"
56
+ "from playwright.sync_api import sync_playwright\n"
52
57
  "with sync_playwright() as p:\n"
53
58
  " print(p.chromium.executable_path)\n"
54
- " b = p.chromium.launch(headless=True); print(b.new_page().evaluate('navigator.userAgent')); b.close()")
59
+ " b = p.chromium.launch(headless=True, args=chromium_flags.python_chromium_args())\n"
60
+ " print(b.new_page().evaluate('navigator.userAgent')); b.close()")
55
61
 
56
62
 
57
63
  def chromium():
@@ -100,7 +106,8 @@ def write_config(user_agent):
100
106
  a CORS request does not count it as an author header, so no preflight is added; a header in extraHTTPHeaders
101
107
  forced one on every cross-origin fetch and font."""
102
108
  os.makedirs(os.path.dirname(CONFIG_PATH), exist_ok=True)
103
- config = {"browser": {"contextOptions": {"userAgent": f"{user_agent} {AGENT_UA_MARK}"}}}
109
+ config = {"browser": {"launchOptions": {"args": [chromium_flags.disable_features_arg(MCP_PLAYWRIGHT_BUNDLE)]},
110
+ "contextOptions": {"userAgent": f"{user_agent} {AGENT_UA_MARK}"}}}
104
111
  atomic_io.write_secret_text(CONFIG_PATH, json.dumps(config, indent=1))
105
112
  return CONFIG_PATH
106
113
 
@@ -8,6 +8,8 @@ import threading
8
8
  import time
9
9
  import uuid
10
10
 
11
+ import process_limits
12
+
11
13
  START_TIMEOUT_S = 45
12
14
  START_FAILURE_COOLDOWN_S = 60
13
15
  SERVICE_IDLE_S = 300
@@ -28,37 +30,6 @@ class BrowserExited(RuntimeError):
28
30
  pass
29
31
 
30
32
 
31
- def _kill_on_close_job():
32
- import ctypes
33
- from ctypes import wintypes
34
-
35
- class IoCounters(ctypes.Structure):
36
- _fields_ = [(name, ctypes.c_ulonglong) for name in
37
- ("read_ops", "write_ops", "other_ops", "read_bytes", "write_bytes", "other_bytes")]
38
-
39
- class BasicLimits(ctypes.Structure):
40
- _fields_ = [("per_process_time", ctypes.c_longlong), ("per_job_time", ctypes.c_longlong),
41
- ("flags", wintypes.DWORD), ("min_ws", ctypes.c_size_t), ("max_ws", ctypes.c_size_t),
42
- ("active_processes", wintypes.DWORD), ("affinity", ctypes.c_size_t),
43
- ("priority", wintypes.DWORD), ("scheduling", wintypes.DWORD)]
44
-
45
- class ExtendedLimits(ctypes.Structure):
46
- _fields_ = [("basic", BasicLimits), ("io", IoCounters), ("process_memory", ctypes.c_size_t),
47
- ("job_memory", ctypes.c_size_t), ("peak_process_memory", ctypes.c_size_t),
48
- ("peak_job_memory", ctypes.c_size_t)]
49
-
50
- kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
51
- kernel32.CreateJobObjectW.restype = wintypes.HANDLE
52
- job = kernel32.CreateJobObjectW(None, None)
53
- if not job:
54
- raise ctypes.WinError(ctypes.get_last_error())
55
- limits = ExtendedLimits()
56
- limits.basic.flags = 0x2000 # JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
57
- if not kernel32.SetInformationJobObject(wintypes.HANDLE(job), 9, ctypes.byref(limits), ctypes.sizeof(limits)):
58
- raise ctypes.WinError(ctypes.get_last_error())
59
- return kernel32, job
60
-
61
-
62
33
  class BrowserService:
63
34
  def __init__(self, executable, script):
64
35
  self.executable = executable
@@ -126,7 +97,7 @@ class BrowserService:
126
97
  # Kill-on-close job: the browser tree dies with the daemon even when the daemon is killed hard.
127
98
  try:
128
99
  if self.job is None:
129
- self.job = _kill_on_close_job()
100
+ self.job = process_limits.kill_on_close_job()
130
101
  kernel32, job = self.job
131
102
  import ctypes
132
103
  from ctypes import wintypes
@@ -0,0 +1,30 @@
1
+ """Chromium switches carried by every automation browser launch of Smart Tool.
2
+
3
+ `WebUsbDeviceDetection` makes Chromium enumerate USB devices a few seconds after launch, which freezes a USB
4
+ microphone that is recording. Chromium keeps only the last `--disable-features` switch, and Playwright puts its own
5
+ list first and appends the caller's arguments, so a lone switch would drop Playwright's list: the switch built here
6
+ repeats the list of the Playwright bundle the browser is launched by and adds the feature to it.
7
+ """
8
+ import re
9
+ from pathlib import Path
10
+
11
+ WEB_USB_FEATURE = "WebUsbDeviceDetection"
12
+ _FEATURE_LIST = re.compile(r"\bdisabledFeatures = \[(.*?)\]\.filter\(", re.S)
13
+ _FEATURE_NAME = re.compile(r'^\s*"([A-Za-z0-9]+)"', re.M)
14
+
15
+
16
+ def disable_features_arg(bundle):
17
+ """The single `--disable-features` switch for a launch through the Playwright driver bundle `bundle`
18
+ (coreBundle.js): that bundle's own list plus WebUsbDeviceDetection. RuntimeError when the list is not found, so a
19
+ Playwright upgrade that moves it fails loudly instead of launching without the switch."""
20
+ found = _FEATURE_LIST.search(Path(bundle).read_text(encoding="utf-8"))
21
+ names = _FEATURE_NAME.findall(found.group(1)) if found else []
22
+ if not names:
23
+ raise RuntimeError(f"No disabledFeatures list in {bundle}; chromium_flags must follow this Playwright version.")
24
+ return "--disable-features=" + ",".join([*names, WEB_USB_FEATURE])
25
+
26
+
27
+ def python_chromium_args():
28
+ """Launch arguments for Chromium started by the Python Playwright package that is imported here."""
29
+ import playwright
30
+ return [disable_features_arg(Path(playwright.__file__).parent / "driver" / "package" / "lib" / "coreBundle.js")]
package/code_health.py ADDED
@@ -0,0 +1,180 @@
1
+ """Questions about the shape of a project that the code graph and the git history answer without writing documentation:
2
+ which code files are the riskiest to change, which functions nothing calls, which imports form a cycle and which
3
+ comments sit where they should not.
4
+
5
+ The same tables the `docs/scope` pages hold (`doc_insights`), asked directly by `project_manage`; nothing is written.
6
+ """
7
+ import code_graph
8
+ import comment_check
9
+ import doc_check
10
+ import doc_insights
11
+ import doc_scope
12
+
13
+ DEFAULT_LIMIT = 25
14
+
15
+
16
+ def _model(root, view_id):
17
+ model = doc_scope._Model(root, view_id)
18
+ if not model.graph.get("symbols"):
19
+ raise ValueError(f"The code graph of {root} is empty: index the project first (project_manage action=index).")
20
+ return model
21
+
22
+
23
+ def hotspots(root, view_id=None, limit=DEFAULT_LIMIT):
24
+ """Code files ranked by the commits that touched them times their lines.
25
+
26
+ Parameters: root (str) project folder; view_id (str or None) index view; limit (int) rows returned.
27
+ Returns: dict {"files": [{"path", "commits", "lines", "score", "last_change"}], "total": int, "commits_read": int,
28
+ "note": str}; `note` is the reason no history could be read (not a git repository), otherwise "".
29
+ Raises: ValueError when the code graph is empty.
30
+ """
31
+ model = _model(root, view_id)
32
+ commits, note = doc_insights.history(root)
33
+ rows = [] if note else doc_insights.hotspots(model, commits)
34
+ files = [{"path": path, "commits": count, "lines": lines, "score": count * lines, "last_change": doc_insights._date(last)}
35
+ for path, count, lines, last in rows[:limit]]
36
+ return {"files": files, "total": len(rows), "commits_read": len(commits), "note": note or ""}
37
+
38
+
39
+ def dead_code(root, view_id=None, limit=DEFAULT_LIMIT):
40
+ """Functions nothing calls and functions only tests call, from the static call graph.
41
+
42
+ Parameters: root (str) project folder; view_id (str or None) index view; limit (int) entries per list.
43
+ Returns: dict {"no_caller": [...], "only_tests": [...], "counts": {"no_caller", "only_tests"}, "note": str}; each entry
44
+ is {"name", "path", "line", "public"}. Candidates only: a call through a framework, a decorator registration,
45
+ reflection or a name built at run time is not seen.
46
+ Raises: ValueError when the code graph is empty.
47
+ """
48
+ model = _model(root, view_id)
49
+ alone, tested = doc_insights.dead_code(model, model.entry_points())
50
+
51
+ def entry(anchor):
52
+ function = model.function_of[anchor]
53
+ return {"name": function["name"], "path": function["path"], "line": function["start"],
54
+ "public": bool(function["required"])}
55
+
56
+ return {"no_caller": [entry(a) for a in alone[:limit]], "only_tests": [entry(a) for a in tested[:limit]],
57
+ "counts": {"no_caller": len(alone), "only_tests": len(tested)},
58
+ "note": "Candidates from the static call graph (Python and Go only): read each one before deleting it."}
59
+
60
+
61
+ def coupled_with(root, paths, view_id=None, limit=DEFAULT_LIMIT):
62
+ """Files that usually change in the same commits as the given ones, left out of the given set.
63
+
64
+ Parameters: root (str) project folder; paths (list of str) project-relative changed files; view_id (str or None) index
65
+ view; limit (int) rows returned. Pairs where one file imports the other are skipped: the call graph already shows them.
66
+ Returns: dict {"files": [{"path", "with", "shared", "degree"}], "note": str}, strongest first, one row per partner;
67
+ degree is a percentage; `note` is the reason no history could be read, otherwise "".
68
+ Raises: ValueError when the code graph is empty.
69
+ """
70
+ model = _model(root, view_id)
71
+ commits, note = doc_insights.history(root)
72
+ if note:
73
+ return {"files": [], "note": note}
74
+ changed, rows, seen = set(paths), [], set()
75
+ for first, second, shared, degree, linked in doc_insights.coupling(model, commits):
76
+ if linked or (first in changed) == (second in changed):
77
+ continue
78
+ partner, anchor = (second, first) if first in changed else (first, second)
79
+ if partner not in seen:
80
+ seen.add(partner)
81
+ rows.append({"path": partner, "with": anchor, "shared": shared, "degree": int(degree * 100)})
82
+ return {"files": rows[:limit], "note": ""}
83
+
84
+
85
+ def _pop_component(stack, on_stack, node):
86
+ """Members of the component rooted at `node`, taken off the Tarjan stack."""
87
+ group = []
88
+ member = None
89
+ while member != node:
90
+ member = stack.pop()
91
+ on_stack.discard(member)
92
+ group.append(member)
93
+ return sorted(group)
94
+
95
+
96
+ def _components(edges):
97
+ """Strongly connected components of size above one, and self-loops, of a directed graph (Tarjan, no recursion).
98
+
99
+ Parameters: edges (dict) node -> set of the nodes it points to.
100
+ Returns: list of sorted node lists.
101
+ """
102
+ index, low, stack, on_stack, found = {}, {}, [], set(), []
103
+ for start in sorted(edges):
104
+ if start in index:
105
+ continue
106
+ index[start] = low[start] = len(index)
107
+ stack.append(start)
108
+ on_stack.add(start)
109
+ work = [(start, iter(sorted(edges[start])))]
110
+ while work:
111
+ node, children = work[-1]
112
+ descended = False
113
+ for child in children:
114
+ if child not in index:
115
+ index[child] = low[child] = len(index)
116
+ stack.append(child)
117
+ on_stack.add(child)
118
+ work.append((child, iter(sorted(edges[child]))))
119
+ descended = True
120
+ break
121
+ if child in on_stack:
122
+ low[node] = min(low[node], index[child])
123
+ if descended:
124
+ continue
125
+ work.pop()
126
+ if work:
127
+ parent = work[-1][0]
128
+ low[parent] = min(low[parent], low[node])
129
+ if low[node] == index[node]:
130
+ group = _pop_component(stack, on_stack, node)
131
+ if len(group) > 1 or node in edges[node]:
132
+ found.append(group)
133
+ return found
134
+
135
+
136
+ def import_cycles(root, view_id=None, limit=DEFAULT_LIMIT):
137
+ """Groups of files that import each other, directly or through a chain.
138
+
139
+ Parameters: root (str) project folder; view_id (str or None) index view; limit (int) cycles returned.
140
+ Returns: dict {"cycles": [{"files": [...], "size": int}], "total": int, "files_in_cycles": int, "note": str}, the
141
+ largest cycle first; only imports the graph resolved to a file of the project count.
142
+ Raises: ValueError when the code graph is empty.
143
+ """
144
+ data = code_graph.build_current(root, view_id, shared=True)
145
+ if not data.get("symbols") and not data.get("dependencies"):
146
+ raise ValueError(f"The code graph of {root} is empty: index the project first (project_manage action=index).")
147
+ edges = {}
148
+ for dependency in data.get("dependencies") or []:
149
+ if dependency.get("kind") == "import" and dependency.get("resolution") == "resolved" and dependency.get("target"):
150
+ edges.setdefault(dependency["source"], set()).add(dependency["target"])
151
+ edges.setdefault(dependency["target"], set())
152
+ cycles = sorted(_components(edges), key=lambda files: (-len(files), files))
153
+ note = code_graph.left_out_sentence(data) if data.get("truncated") else ""
154
+ return {"cycles": [{"files": files, "size": len(files)} for files in cycles[:limit]], "total": len(cycles),
155
+ "files_in_cycles": sum(len(files) for files in cycles), "note": note}
156
+
157
+
158
+ def comments(root, view_id=None, limit=DEFAULT_LIMIT):
159
+ """Comments in the wrong place across the code files of the project: commented-out code, history tags, loose
160
+ documentation and long inline blocks (`comment_check`), for files written before the edit hook existed.
161
+
162
+ Parameters: root (str) project folder; view_id (str or None) index view; limit (int) findings returned.
163
+ Returns: dict {"findings": [{"path", "line", "issue", "name", "text"}], "total": int, "by_issue": {issue: count},
164
+ "files_checked": int}.
165
+ Raises: ValueError when the code graph is empty.
166
+ """
167
+ model = _model(root, view_id)
168
+ findings, checked = [], 0
169
+ for path in model.files():
170
+ if model.kind_of(path) != "code" or not doc_check.supported(path):
171
+ continue
172
+ text = model.read(path)
173
+ if not text:
174
+ continue
175
+ checked += 1
176
+ findings += [{"path": path, **item} for item in comment_check.review(path, None, text)]
177
+ by_issue = {}
178
+ for item in findings:
179
+ by_issue[item["issue"]] = by_issue.get(item["issue"], 0) + 1
180
+ return {"findings": findings[:limit], "total": len(findings), "by_issue": by_issue, "files_checked": checked}
package/code_impact.py CHANGED
@@ -1,6 +1,7 @@
1
1
  """What changing a function touches, from the indexed code graph: where it is defined, who calls it, what it calls,
2
2
  which tests reach it through static calls and which files import its module, each with the first line of its
3
3
  docstring. Answers the question an agent asks before an edit without a chain of searches and file reads."""
4
+ import difflib
4
5
  import os
5
6
  import re
6
7
  from collections import defaultdict
@@ -23,6 +24,15 @@ def _matches(symbols, name):
23
24
  return exact or [s for s in pool if s["name"].split(".")[-1] == wanted]
24
25
 
25
26
 
27
+ def _closest_names(symbols, name, limit=3):
28
+ """Up to `limit` indexed function or class names that resemble `name` (case ignored), best first."""
29
+ wanted = name.strip().rpartition("::")[2].casefold()
30
+ by_lower = {}
31
+ for symbol in symbols:
32
+ by_lower.setdefault(symbol["name"].split(".")[-1].casefold(), symbol["name"].split(".")[-1])
33
+ return [by_lower[key] for key in difflib.get_close_matches(wanted, list(by_lower), n=limit, cutoff=0.6)]
34
+
35
+
26
36
  def _site(by_id, symbol_id, line, of=None):
27
37
  symbol = by_id.get(symbol_id) or {}
28
38
  site = {"id": symbol_id, "function": symbol.get("name", symbol_id), "path": symbol.get("path"), "line": line}
@@ -85,7 +95,9 @@ def impact(root, symbol, view_id=None, depth=3, limit=30):
85
95
  diagnostics = [d.get("reason") for d in data.get("diagnostics") or [] if d.get("reason")]
86
96
  if not found:
87
97
  cause = f" Analysis problems: {'; '.join(diagnostics)}" if diagnostics else ""
88
- raise ValueError(f"No function or class named {symbol!r} in the indexed view; check the name or reindex.{cause}")
98
+ close = _closest_names(data.get("symbols") or [], symbol)
99
+ hint = f" Closest names: {', '.join(close)}." if close else ""
100
+ raise ValueError(f"No function or class named {symbol!r} in the indexed view; check the name or reindex.{hint}{cause}")
89
101
  profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile"))
90
102
  by_id = {s["id"]: s for s in data["symbols"]}
91
103
  callers, callees = defaultdict(list), defaultdict(list)