@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 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.80 beta. Windows only. What changed in each version: [CHANGELOG.md](CHANGELOG.md).
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.80 install
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; publishing it as a pull-request comment is left to the CI step that calls it.
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.80 uninstall [--target DIR] [--keep-data]
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 in Claude Code."""
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 PreToolUse command of a client without HTTP hooks, signed with HOOK_ORIGIN at the end."""
242
- return f"{_shell_safe(sys.executable)} {_shell_safe(HOOK_SCRIPT)} --client {client} {HOOK_ORIGIN}"
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 PreToolUse route."""
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, and the PostToolUse of Claude Code) out of the client's hooks
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}; each entry
44
- is {"name", "path", "line", "public"}. Candidates only: a call through a framework, a decorator registration,
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["dependencies"] if d.get("target") in files and d["source"] not in files})
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`. The commit
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."""