@allansantos-dev/smart-tool 0.9.80 → 0.9.81
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 +65 -0
- package/README.md +21 -4
- package/client_hooks.py +10 -8
- package/code_health.py +5 -3
- package/code_impact.py +1 -1
- package/config.py +35 -0
- package/dossier.py +40 -5
- package/hook_decision.py +240 -20
- package/hooks/pretool_router.py +5 -4
- package/install.py +66 -27
- package/install_runtime.py +24 -10
- package/link_check.py +69 -0
- package/local_embedder.py +1 -1
- package/locales/pt-BR.json +71 -2
- package/model_client.py +1 -1
- package/model_health.py +24 -6
- package/notice_action.py +9 -0
- package/package.json +1 -1
- package/pr_comment.py +94 -0
- package/pr_impact.py +216 -35
- package/project_admission.py +17 -15
- package/removed_callers.py +146 -0
- package/setup_ui.py +33 -4
- package/smart_tool_daemon.py +8 -3
- package/tray.py +29 -9
- package/update_splash.py +2 -2
- package/version.py +1 -1
- package/web_document_graph.py +12 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,70 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.81 - beta
|
|
4
|
+
|
|
5
|
+
- `pr_impact` lists the functions the diff adds that no function and no test calls (the candidates `dead_code` finds, which
|
|
6
|
+
already leave out framework and registered functions), in the section "New functions nothing calls". The section is
|
|
7
|
+
left out when the diff adds no function or every new one has a caller; a graph the analysis limits cut is said, and so is a
|
|
8
|
+
check that cannot run. `project_manage action=dead_code` also reports the graph cut (`graph_note`). Tests:
|
|
9
|
+
`tests/test_pr_impact.py`, `tests/test_code_health.py`.
|
|
10
|
+
- When an edit changes only the signature of a function (parameters, order, defaults, return annotation), the edit hook and
|
|
11
|
+
`pr_impact` list the callers outside the edited file, as they do for a removed or renamed function; the callers come from
|
|
12
|
+
the graph's resolved calls and its calls left unresolved by name, a graph the analysis limits cut is said instead of
|
|
13
|
+
claiming no caller, a name defined twice in one file (overloads) is not compared, and a failure is a visible note. Tests:
|
|
14
|
+
`tests/test_removed_callers.py`, `tests/test_pr_impact.py`.
|
|
15
|
+
- The edit hook notes a broken local link when an HTML or Markdown file is edited, and so do the review of files a shell
|
|
16
|
+
call wrote and `project_manage action=pr_impact`: a relative `href`, `src` or Markdown link target that the edit adds or
|
|
17
|
+
changes and that points to no file or folder, resolved against the edited file and read with the reader the code graph
|
|
18
|
+
uses. A link that was already broken, http(s), `mailto:`, `tel:`, `data:` and `#anchor` links are left out. What cannot be
|
|
19
|
+
checked is listed with the reason instead of being dropped: a path from the root of a site, a template expression, a page
|
|
20
|
+
with a `<base>` element, a target that cannot be looked up, HTML that did not parse. `link_mode` (`warn` default, or
|
|
21
|
+
`off`) in `config.json` and on the setup screen; it never blocks. Tests: `tests/test_link_check.py`.
|
|
22
|
+
- `project_manage action=pr_impact_comment pr=<number> base=<revision>` posts the `pr_impact` report as a comment on a pull
|
|
23
|
+
request through the `gh` CLI, from the project folder, and returns the comment URL. It writes to GitHub, so it is off
|
|
24
|
+
until the user turns on "Impact report as a pull request comment" in the setup screen (Agent rules; `pr_comment` in
|
|
25
|
+
`config.json`, `off` by default, any other value than `off` or `on` fails loudly); with it off, or with `gh` missing or
|
|
26
|
+
not logged in, it refuses before building anything. The comment ends with a hidden HTML marker: a rerun edits the last
|
|
27
|
+
comment that has it instead of stacking another, and the body shows no path of the user's machine. Tests:
|
|
28
|
+
`tests/test_pr_comment.py`, `tests/test_setup_integration.py`, `tests/test_setup_page_browser.py`.
|
|
29
|
+
- The edit hook names the decisions recorded about the functions an edit touches: for the first three functions in a code
|
|
30
|
+
file, up to two notes of the project (`docs/research`, the backlog, `CLAUDE.md`, `AGENTS.md`) that name the function, as
|
|
31
|
+
`path:line` and the title, so the agent does not undo what a note documents. A single-word function name counts only
|
|
32
|
+
when a note qualifies it as `module.name` or `Class.name`, a compound name as the bare identifier. Measured on 46
|
|
33
|
+
touched functions of this repository, the notes shown were about the function in 22 of 22 cases (the earlier rule: 11 of
|
|
34
|
+
18; the raw search: 9 of 88) and the hook stayed silent on the 27 functions with no recorded decision. It reads files
|
|
35
|
+
only (no network, no model, no git history, 300 ms per function), says when it fails or is cut, and never blocks.
|
|
36
|
+
`decision_mode` (`warn`, default, or `off`) is on the Agent rules page of the setup screen; `pr_impact` uses the same rule
|
|
37
|
+
and also reads the commit messages. Tests: `tests/test_decision_notes.py`, `tests/test_pr_impact.py`. Measurement:
|
|
38
|
+
`docs/research/2026-11-18-decision-notes-keyword-quality.md`.
|
|
39
|
+
- The tray menu has "Open tray log": it opens `tray.log`, and says so when the file does not exist yet. Tests:
|
|
40
|
+
`tests/test_tray_notices.py`.
|
|
41
|
+
- A toast Windows refuses is also shown as a tray balloon with the text and the refusal (cut to the balloon limits) and is
|
|
42
|
+
still logged to `tray.log`; a balloon that fails is logged too, and the next notices are still shown. Tests:
|
|
43
|
+
`tests/test_tray_notices.py`.
|
|
44
|
+
- The toast that says a newer version is available has an "Update now" button (the `update-now` action): it starts the
|
|
45
|
+
update screen for that version, and refuses any version text that is not an npm version number. Tests:
|
|
46
|
+
`tests/test_update_check.py`.
|
|
47
|
+
- The failed-update toast carries the tag `update-failed`, so each tray start replaces it instead of stacking another one.
|
|
48
|
+
Tests: `tests/test_update_check.py`.
|
|
49
|
+
- The edit hook's checks also run after a shell call that wrote files (`sed -i`, a redirection, `npm install`, `cargo add`).
|
|
50
|
+
The PostToolUse entry of Claude Code (Bash and PowerShell) and, new, of Codex (Bash, through the same thin command with
|
|
51
|
+
`--post`) reviews the files git shows changed since `HEAD`, tracked or not, whose modification time is not older than the
|
|
52
|
+
start of that call, which the PreToolUse hook records by `tool_use_id`; files already changed before the call are left
|
|
53
|
+
out. The notes are the ones `pr_impact` already adds to a whole diff (`hook_decision.review_diff`), added to the
|
|
54
|
+
call's context, never a block. A git failure, a start that was not recorded or a review that cannot run comes back as a
|
|
55
|
+
`Smart Tool shell review skipped` note; a folder that is not a git repository is left alone. Codex needs the hook update
|
|
56
|
+
(and its approval) once to get the new entry. Tests: `tests/test_transparent_redirect.py`,
|
|
57
|
+
`tests/test_codex_audit_hook.py`, `tests/test_web_fetch.py`.
|
|
58
|
+
- The installer prints its messages in Portuguese when the user's language is Portuguese: the language picked in the
|
|
59
|
+
settings, else the Windows display language. Unreadable settings are reported on stderr and the Windows language is
|
|
60
|
+
used. `--language en|pt-BR` forces one; the update screen and the release install check pass `--language en`, because
|
|
61
|
+
they read the installer's English lines. The web runtime installer prints in the same language. Tests:
|
|
62
|
+
`tests/test_install_language.py`, `tests/test_update_splash.py`.
|
|
63
|
+
- The refusals a call gets when its folder cannot become a project ("Not indexing ...: it is a personal folder ...") follow
|
|
64
|
+
the language saved in the settings like the rest of the product: Portuguese when it is chosen, with the folders and the
|
|
65
|
+
reason kept in the text, and the same English text as before otherwise. Tests: `tests/test_project_admission.py`,
|
|
66
|
+
`tests/test_i18n.py`.
|
|
67
|
+
|
|
3
68
|
## 0.9.80 - beta
|
|
4
69
|
|
|
5
70
|
- The document converter keeps its results in one folder per version, `%LOCALAPPDATA%\SmartTool\cache\<version>\convert`,
|
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.81 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
|
|
21
21
|
|
|
22
22
|
## How it works
|
|
23
23
|
|
|
@@ -84,7 +84,7 @@ gateway such as Ollama, nothing about your code leaves the machine.
|
|
|
84
84
|
## Install
|
|
85
85
|
|
|
86
86
|
```powershell
|
|
87
|
-
npx @allansantos-dev/smart-tool@0.9.
|
|
87
|
+
npx @allansantos-dev/smart-tool@0.9.81 install
|
|
88
88
|
```
|
|
89
89
|
|
|
90
90
|
Updates install themselves, on by default: the tray checks npm when it starts (at logon) and every 24 h, and when there
|
|
@@ -277,7 +277,12 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
277
277
|
a touched function (a single-word name counts only as a code reference), the files that usually change in the same
|
|
278
278
|
commits and are missing from the diff, the notes the edit hook would have added to the whole diff (comments, copies,
|
|
279
279
|
dependency advisories, credentials) and the tests to run with their commands. It reads
|
|
280
|
-
only
|
|
280
|
+
only. `project_manage action=pr_impact_comment pr=<number> base=<revision>` posts the same report as a comment on that
|
|
281
|
+
pull request through the `gh` CLI, from the project folder, and returns the comment URL. It writes to GitHub with your
|
|
282
|
+
own `gh` login, so it is off until you turn on "Impact report as a pull request comment" in the setup screen (Agent
|
|
283
|
+
rules; `"pr_comment": "on"` in `config.json`); with it off, or with `gh` missing or not logged in, it refuses and
|
|
284
|
+
posts nothing. A rerun edits the last Smart Tool comment (marked by a hidden HTML comment) instead of adding another,
|
|
285
|
+
and the body shows no path of your machine.
|
|
281
286
|
|
|
282
287
|
**Shape of the project**: `project_manage action=hotspots` ranks the code files by commits times lines (the
|
|
283
288
|
riskiest to change), `dead_code` lists the functions no code calls and those only tests call (static call graph,
|
|
@@ -289,6 +294,18 @@ Redirects) and Maintenance (Setup audit, Startup).
|
|
|
289
294
|
a lower layer to a function of a higher one is flagged to the agent; it never blocks. `layer_mode` in
|
|
290
295
|
`config.json`: `warn` (default) or `off`, also on the setup screen.
|
|
291
296
|
|
|
297
|
+
**Broken links on edit**: an edit of an HTML or Markdown file that adds or changes a relative link (`href`, `src`,
|
|
298
|
+
a Markdown link target) to a file that does not exist is flagged to the agent, with the links it could not check
|
|
299
|
+
(a path from the site root, a template expression, a `<base>` element); it never blocks. `link_mode` in
|
|
300
|
+
`config.json`: `warn` (default) or `off`, also on the setup screen.
|
|
301
|
+
**Recorded decisions on edit**: for the first three functions an edit touches in a code file, the hook names up to two
|
|
302
|
+
notes of the project (`docs/research`, the backlog, `CLAUDE.md`, `AGENTS.md`) that name the function, as `path:line` and
|
|
303
|
+
the title, so the agent reads what was decided before undoing it. A single-word function name counts only when a note
|
|
304
|
+
qualifies it as `module.name` or `Class.name`, a compound name as the bare identifier; the search reads files only (no
|
|
305
|
+
network, no model, no git history, 300 ms per function), says when it fails or is cut, and never blocks.
|
|
306
|
+
`decision_mode` in `config.json`: `warn` (default) or `off`, also on the setup screen. The measurement behind the rule is
|
|
307
|
+
in `docs/research/2026-11-18-decision-notes-keyword-quality.md`.
|
|
308
|
+
|
|
292
309
|
**Folder and layer in a search**: `smart_search folder="<path>"` (or a list) and `layer="<name>"` restrict the
|
|
293
310
|
search to a folder of the project or to one of its confirmed layers, by their path globs. The filter runs before
|
|
294
311
|
the ranking, so the results are the best inside the scope, not a cut of the global list.
|
|
@@ -437,7 +454,7 @@ fails to load is listed in the setup screen with its error and does not affect t
|
|
|
437
454
|
## Uninstall
|
|
438
455
|
|
|
439
456
|
```powershell
|
|
440
|
-
npx @allansantos-dev/smart-tool@0.9.
|
|
457
|
+
npx @allansantos-dev/smart-tool@0.9.81 uninstall [--target DIR] [--keep-data]
|
|
441
458
|
```
|
|
442
459
|
|
|
443
460
|
It asks nothing and opens no window. It stops the tray and the daemon, removes the logon task, the hook entries of Smart
|
package/client_hooks.py
CHANGED
|
@@ -40,7 +40,7 @@ CLIENTS = {
|
|
|
40
40
|
"docs": "https://code.claude.com/docs/en/hooks", "event": "PreToolUse", "matcher": "Grep|Glob|Read|Bash|PowerShell|WebSearch|WebFetch|Edit|MultiEdit|Write|mcp__smart-tool__smart_search|mcp__smart-tool__web_search|mcp__smart-tool__web_fetch", "http": True,
|
|
41
41
|
"post_matcher": "Grep|Bash|PowerShell|WebFetch|WebSearch"},
|
|
42
42
|
"codex": {"label": "Codex", "prefix": "codex", "files": [os.path.join(endpoint_sync.codex_dir(), "hooks.json"), os.path.join(endpoint_sync.codex_dir(), "config.toml")],
|
|
43
|
-
"docs": "https://learn.chatgpt.com/docs/hooks", "event": "PreToolUse", "matcher": "Bash|apply_patch",
|
|
43
|
+
"docs": "https://learn.chatgpt.com/docs/hooks", "event": "PreToolUse", "matcher": "Bash|apply_patch", "post_matcher": "Bash",
|
|
44
44
|
"after_install": "Smart Tool recorded the approval of the new definition in Codex's config.toml, as /hooks "
|
|
45
45
|
"would, so Codex runs it from the next session on."},
|
|
46
46
|
"cursor": {"label": "Cursor", "prefix": "cursor", "files": [os.path.join(HOME, ".cursor", "hooks.json")],
|
|
@@ -64,7 +64,7 @@ def _our_hook(hook):
|
|
|
64
64
|
|
|
65
65
|
def _entries(client):
|
|
66
66
|
"""{event: (matcher, handler)} of our hook entries for the client: the PreToolUse, plus the PostToolUse that returns
|
|
67
|
-
the Smart Tool answer of a redirected call
|
|
67
|
+
the Smart Tool answer of a redirected call and the review of the files a shell call wrote."""
|
|
68
68
|
spec = CLIENTS[client]
|
|
69
69
|
entries = {spec["event"]: (spec["matcher"], _handler(client))}
|
|
70
70
|
if spec.get("post_matcher"):
|
|
@@ -237,9 +237,11 @@ def _shell_safe(path):
|
|
|
237
237
|
return path.replace("\\", "/")
|
|
238
238
|
|
|
239
239
|
|
|
240
|
-
def _command(client):
|
|
241
|
-
"""The
|
|
242
|
-
|
|
240
|
+
def _command(client, route=HTTP_PATH):
|
|
241
|
+
"""The command of a client without HTTP hooks for the PreToolUse route (default) or the PostToolUse one, signed with
|
|
242
|
+
HOOK_ORIGIN at the end."""
|
|
243
|
+
after = " --post" if route == POST_PATH else ""
|
|
244
|
+
return f"{_shell_safe(sys.executable)} {_shell_safe(HOOK_SCRIPT)} --client {client}{after} {HOOK_ORIGIN}"
|
|
243
245
|
|
|
244
246
|
|
|
245
247
|
def _port_file():
|
|
@@ -253,14 +255,14 @@ def _port_file():
|
|
|
253
255
|
|
|
254
256
|
def _handler(client, route=HTTP_PATH, timeout=HTTP_TIMEOUT_S):
|
|
255
257
|
"""Claude Code posts the payload straight to the warm daemon (`type: "http"`, no process per tool call); other
|
|
256
|
-
clients run the thin command that forwards to the
|
|
258
|
+
clients run the thin command that forwards to the route."""
|
|
257
259
|
if CLIENTS[client].get("http"):
|
|
258
260
|
registry = daemon_launcher.read_registry()
|
|
259
261
|
if not registry or not registry.get("url"):
|
|
260
262
|
raise ValueError("Smart Tool daemon has no registered URL; start the daemon before installing the hook.")
|
|
261
263
|
query = f"client={client}&hook-origin={OWNER}&port-file={_port_file()}"
|
|
262
264
|
return {"type": "http", "url": f"{registry['url']}{route}?{query}", "timeout": timeout}
|
|
263
|
-
return {"type": "command", "command": _command(client), "timeout": timeout}
|
|
265
|
+
return {"type": "command", "command": _command(client, route), "timeout": timeout}
|
|
264
266
|
|
|
265
267
|
|
|
266
268
|
def _slot(groups, is_ours):
|
|
@@ -340,7 +342,7 @@ def install(client_info, token, confirm):
|
|
|
340
342
|
|
|
341
343
|
|
|
342
344
|
def remove(client):
|
|
343
|
-
"""Takes every redirect hook entry of ours (PreToolUse
|
|
345
|
+
"""Takes every redirect hook entry of ours (PreToolUse and PostToolUse) out of the client's hooks
|
|
344
346
|
file after a backup; other hooks stay, in Codex at the approval of their new index. Returns {client, changed, file,
|
|
345
347
|
backup}."""
|
|
346
348
|
path = os.path.realpath(CLIENTS[client]["files"][0])
|
package/code_health.py
CHANGED
|
@@ -40,8 +40,9 @@ def dead_code(root, view_id=None, limit=DEFAULT_LIMIT):
|
|
|
40
40
|
"""Functions nothing calls and functions only tests call, from the static call graph.
|
|
41
41
|
|
|
42
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
|
|
44
|
-
is {"name", "path", "line", "public"}
|
|
43
|
+
Returns: dict {"no_caller": [...], "only_tests": [...], "counts": {"no_caller", "only_tests"}, "note": str,
|
|
44
|
+
"graph_note": str}; each entry is {"name", "path", "line", "public"}; `graph_note` says what the analysis limits cut from
|
|
45
|
+
the graph, "" when they cut nothing. Candidates only: a call through a framework, a decorator registration,
|
|
45
46
|
reflection or a name built at run time is not seen.
|
|
46
47
|
Raises: ValueError when the code graph is empty.
|
|
47
48
|
"""
|
|
@@ -55,7 +56,8 @@ def dead_code(root, view_id=None, limit=DEFAULT_LIMIT):
|
|
|
55
56
|
|
|
56
57
|
return {"no_caller": [entry(a) for a in alone[:limit]], "only_tests": [entry(a) for a in tested[:limit]],
|
|
57
58
|
"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
|
+
"note": "Candidates from the static call graph (Python and Go only): read each one before deleting it.",
|
|
60
|
+
"graph_note": code_graph.left_out_sentence(model.graph) or ""}
|
|
59
61
|
|
|
60
62
|
|
|
61
63
|
def coupled_with(root, paths, view_id=None, limit=DEFAULT_LIMIT):
|
package/code_impact.py
CHANGED
|
@@ -127,7 +127,7 @@ def impact(root, symbol, view_id=None, depth=3, limit=30):
|
|
|
127
127
|
outgoing = [_site(by_id, c["target"], c["line"], label.get(t)) for t in targets for c in callees[t]
|
|
128
128
|
if c["target"] not in targets]
|
|
129
129
|
files = {s["path"] for s in found}
|
|
130
|
-
importers = sorted({d["source"] for d in data
|
|
130
|
+
importers = sorted({d["source"] for d in data.get("dependencies") or [] if d.get("target") in files and d["source"] not in files})
|
|
131
131
|
ordered_tests = sorted(tests.values(), key=lambda t: (t["hops"], t["path"], t["line"]))
|
|
132
132
|
shown = direct[:limit] + outgoing[:limit] + ordered_tests[:limit]
|
|
133
133
|
_name_test_callbacks(root, by_id, shown)
|
package/config.py
CHANGED
|
@@ -47,6 +47,9 @@ DEFAULT_CONFIG = {
|
|
|
47
47
|
"duplicate_mode": "warn",
|
|
48
48
|
"dependency_mode": "warn",
|
|
49
49
|
"layer_mode": "warn",
|
|
50
|
+
"link_mode": "warn",
|
|
51
|
+
"pr_comment": "off",
|
|
52
|
+
"decision_mode": "warn",
|
|
50
53
|
"document_converter": "off",
|
|
51
54
|
"document_converter_python": "",
|
|
52
55
|
"docs_extras": {key: True for key in DOCS_EXTRAS},
|
|
@@ -84,6 +87,15 @@ DUPLICATE_MODES = ("warn", "off")
|
|
|
84
87
|
# off = say nothing and make no network call.
|
|
85
88
|
DEPENDENCY_MODES = ("warn", "off")
|
|
86
89
|
LAYER_MODES = ("warn", "off")
|
|
90
|
+
# Edit hook on HTML and Markdown files: warn = let the edit run and name the local links it adds or changes that point to a
|
|
91
|
+
# file that does not exist, and the ones that cannot be checked; off = say nothing. Never blocks.
|
|
92
|
+
LINK_MODES = ("warn", "off")
|
|
93
|
+
# Posting the pr_impact report as a comment on a pull request through the gh CLI, a write to GitHub with the user's own
|
|
94
|
+
# login: off = never; on = project_manage action=pr_impact_comment may post. Only the user turns it on, in the setup screen.
|
|
95
|
+
PR_COMMENT_MODES = ("off", "on")
|
|
96
|
+
# Edit hook on the functions an edit touches: warn = let the edit run and name the notes and commit messages of the project
|
|
97
|
+
# that record a decision about them; off = say nothing. Never blocks.
|
|
98
|
+
DECISION_MODES = ("warn", "off")
|
|
87
99
|
# External converter read_document falls back to for a file type or a scanned PDF its native reader refuses: off = never;
|
|
88
100
|
# auto = the first of kreuzberg and docling found installed; or one of them by name. The engine is looked for in the
|
|
89
101
|
# interpreter named by `document_converter_python` (empty = the one Smart Tool runs on).
|
|
@@ -134,6 +146,29 @@ def layer_mode(cfg=None):
|
|
|
134
146
|
return value
|
|
135
147
|
|
|
136
148
|
|
|
149
|
+
def link_mode(cfg=None):
|
|
150
|
+
value = (cfg if cfg is not None else load_config()).get("link_mode") or DEFAULT_CONFIG["link_mode"]
|
|
151
|
+
if value not in LINK_MODES:
|
|
152
|
+
raise ValueError(f"Invalid link_mode ({value!r}) in {CONFIG_PATH}: use warn or off.")
|
|
153
|
+
return value
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def pr_comment(cfg=None):
|
|
157
|
+
"""The user's consent to post the impact report on a pull request: `off` (default) or `on`; any other value fails loudly."""
|
|
158
|
+
value = (cfg if cfg is not None else load_config()).get("pr_comment") or DEFAULT_CONFIG["pr_comment"]
|
|
159
|
+
if value not in PR_COMMENT_MODES:
|
|
160
|
+
raise ValueError(f"Invalid pr_comment ({value!r}) in {CONFIG_PATH}: use off or on.")
|
|
161
|
+
return value
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def decision_mode(cfg=None):
|
|
165
|
+
"""The edit hook's decision-notes mode, `warn` or `off`; raises ValueError for any other value in the config file."""
|
|
166
|
+
value = (cfg if cfg is not None else load_config()).get("decision_mode") or DEFAULT_CONFIG["decision_mode"]
|
|
167
|
+
if value not in DECISION_MODES:
|
|
168
|
+
raise ValueError(f"Invalid decision_mode ({value!r}) in {CONFIG_PATH}: use warn or off.")
|
|
169
|
+
return value
|
|
170
|
+
|
|
171
|
+
|
|
137
172
|
def document_converter(cfg=None):
|
|
138
173
|
"""The external converter setting: `{"mode": one of DOCUMENT_CONVERTERS, "python": interpreter path or ""}`. An
|
|
139
174
|
unknown mode or a python that is not text fails loudly."""
|
package/dossier.py
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
"""Dossier mode of smart_search: a narrow keyword query over the notes a project keeps about its own intent
|
|
2
2
|
(docs/research, the backlog, CLAUDE.md and AGENTS.md; with `history`, also the messages of its commits), answered with
|
|
3
3
|
ids and one short excerpt per hit, inside a time budget. It reads straight from disk, uses no index and no model, and
|
|
4
|
-
never raises on a slow or unreadable file: it stops at the deadline and says so in `degraded`/`reasons`.
|
|
4
|
+
never raises on a slow or unreadable file: it stops at the deadline and says so in `degraded`/`reasons`. `notes_about`
|
|
5
|
+
narrows it to the notes that name one function. The commit
|
|
5
6
|
messages come from `doc_insights.history`, whose first read of a repository runs one `git log` that no deadline can
|
|
6
7
|
cut, so `history` is opt-in and a read that outlasts the budget is reported in `reasons`."""
|
|
7
8
|
import json
|
|
@@ -13,6 +14,7 @@ DEFAULT_TIMEOUT_MS = 800
|
|
|
13
14
|
MAX_TIMEOUT_MS = 5000
|
|
14
15
|
DEFAULT_MAX_HITS = 5
|
|
15
16
|
MAX_HITS = 10
|
|
17
|
+
MAX_FUNCTION_NOTES = 2
|
|
16
18
|
SNIPPET_CHARS = 160
|
|
17
19
|
TITLE_CHARS = 80
|
|
18
20
|
MAX_FILE_BYTES = 512 * 1024
|
|
@@ -100,11 +102,12 @@ def _commit_units(root):
|
|
|
100
102
|
for commit in commits], note
|
|
101
103
|
|
|
102
104
|
|
|
103
|
-
def query(root, text, timeout_ms=DEFAULT_TIMEOUT_MS, max_hits=DEFAULT_MAX_HITS, history=False):
|
|
105
|
+
def query(root, text, timeout_ms=DEFAULT_TIMEOUT_MS, max_hits=DEFAULT_MAX_HITS, history=False, keep=None):
|
|
104
106
|
"""The dossier answer for `text` over the notes of `root`: `{"mode", "degraded", "reasons", "elapsed_ms",
|
|
105
107
|
"scanned", "hits": [{"id", "source", "title", "snippet"}]}`, best hit first. `id` is `path:line` of the unit's
|
|
106
108
|
first line, or `git:<hash>` for a commit message (`history` true; source `git`). `degraded` is true when the
|
|
107
|
-
deadline cut the scan or a file could not be read; `hits` then holds what was found until then.
|
|
109
|
+
deadline cut the scan or a file could not be read; `hits` then holds what was found until then. `keep`, when given,
|
|
110
|
+
is a predicate over the whole text of a unit that a unit must also pass to count."""
|
|
108
111
|
started = time.monotonic()
|
|
109
112
|
deadline = started + timeout_ms / 1000
|
|
110
113
|
terms = focus_terms(text)
|
|
@@ -126,7 +129,7 @@ def query(root, text, timeout_ms=DEFAULT_TIMEOUT_MS, max_hits=DEFAULT_MAX_HITS,
|
|
|
126
129
|
continue
|
|
127
130
|
for number, unit in _units(lines):
|
|
128
131
|
score = _score(unit, terms)
|
|
129
|
-
if score:
|
|
132
|
+
if score and (keep is None or keep("\n".join(unit))):
|
|
130
133
|
scored.append((score, rel, kind, number, unit))
|
|
131
134
|
if unreadable:
|
|
132
135
|
reasons.append("not read: " + "; ".join(unreadable[:5]))
|
|
@@ -139,7 +142,7 @@ def query(root, text, timeout_ms=DEFAULT_TIMEOUT_MS, max_hits=DEFAULT_MAX_HITS,
|
|
|
139
142
|
reasons.append(f"git history read took longer than {timeout_ms} ms")
|
|
140
143
|
for short, _subject, unit in commits:
|
|
141
144
|
score = _score(unit, terms)
|
|
142
|
-
if score:
|
|
145
|
+
if score and (keep is None or keep("\n".join(unit))):
|
|
143
146
|
scored.append((score, f"git:{short}", "git", None, unit))
|
|
144
147
|
elif history:
|
|
145
148
|
reasons.append(f"git history not read: timeout after {timeout_ms} ms")
|
|
@@ -150,6 +153,38 @@ def query(root, text, timeout_ms=DEFAULT_TIMEOUT_MS, max_hits=DEFAULT_MAX_HITS,
|
|
|
150
153
|
"elapsed_ms": round((time.monotonic() - started) * 1000), "scanned": scanned, "hits": hits}
|
|
151
154
|
|
|
152
155
|
|
|
156
|
+
def mention_test(rel, qualified):
|
|
157
|
+
"""A predicate over the text of one note: true when the note names the function `qualified` of the file `rel`.
|
|
158
|
+
|
|
159
|
+
A single word is also ordinary prose, so it counts only qualified, as `module.name` (the file's name without its
|
|
160
|
+
extension) or `Owner.name` (the class or function around it). A compound name (snake_case or camelCase, two words
|
|
161
|
+
or more) is distinctive enough as the bare identifier; it does not count when another name qualifies it
|
|
162
|
+
(`other.name`) or when it is itself a qualifier (`name.attribute`).
|
|
163
|
+
"""
|
|
164
|
+
*owners, name = qualified.split(".")
|
|
165
|
+
stem = rel.rpartition("/")[2].rpartition(".")[0]
|
|
166
|
+
qualifiers = "|".join(re.escape(part) for part in (stem, *owners[-1:]) if part)
|
|
167
|
+
escaped = re.escape(name)
|
|
168
|
+
qualified_form = re.compile(rf"(?<![\w.])(?:{qualifiers})\.{escaped}(?!\w)")
|
|
169
|
+
if len([word for word in re.split(r"_|(?<=[a-z])(?=[A-Z])", name.strip("_")) if word]) < 2:
|
|
170
|
+
return lambda text: bool(qualified_form.search(text))
|
|
171
|
+
bare_form = re.compile(rf"(?<![\w.]){escaped}(?!\w|\.\w)")
|
|
172
|
+
return lambda text: bool(qualified_form.search(text) or bare_form.search(text))
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def notes_about(root, rel, qualified, timeout_ms=DEFAULT_TIMEOUT_MS, history=True):
|
|
176
|
+
"""The notes of `root`, and its commit messages when `history`, that name one function, at most `MAX_FUNCTION_NOTES`.
|
|
177
|
+
|
|
178
|
+
Parameters: root (str) project folder; rel (str) path of the file of the function, relative to root with forward
|
|
179
|
+
slashes; qualified (str) the function's name as `doc_check.functions` gives it (`Class.method` for a method);
|
|
180
|
+
timeout_ms (int) scan budget; history (bool) also read the commit messages, whose first read after a commit runs a
|
|
181
|
+
`git log` no deadline can cut.
|
|
182
|
+
Returns: the `query` answer, keeping only the units `mention_test` accepts.
|
|
183
|
+
"""
|
|
184
|
+
name = qualified.rpartition(".")[2].strip("_")
|
|
185
|
+
return query(root, name, timeout_ms, MAX_FUNCTION_NOTES, history=history, keep=mention_test(rel, qualified))
|
|
186
|
+
|
|
187
|
+
|
|
153
188
|
def answer(arguments):
|
|
154
189
|
"""The text smart_search returns for `mode=dossier`: the compact JSON of `query`. Raises ValueError for a missing
|
|
155
190
|
folder or text, or a `timeout_ms`/`max_hits` out of range, so the caller sees the error instead of an empty dossier."""
|