@allansantos-dev/smart-tool 0.9.2 → 0.9.4

package/hook_decision.py

@@ -10,11 +10,22 @@ no Claude Code, e nenhuma decisão aqui é sobre periculosidade, só sobre custo
 import json
 import os
 
+import code_graph
+import code_impact
 import config
+import doc_check
+import duplicates
+import edit_preview
+import index_profile
+import index_scope
 import endpoint_sync
+import project_store
 import router
 
 WEB_TOOLS = ("WebSearch", "WebFetch")
+EDIT_TOOLS = ("Edit", "MultiEdit", "Write", "apply_patch")
+MAX_DOC_FINDINGS = 5
+MAX_DUPLICATE_FINDINGS = 3
 SMART_TOOL_SERVER = "smart-tool"
 REASON_MAX_CHARS = 200
 
@@ -55,9 +66,96 @@ def advise(reason):
                                    "additionalContext": f"Smart Tool tip (the call was not blocked): {reason}"}}
 
 
+def _project_of(path):
+    target = os.path.normcase(os.path.abspath(path))
+    roots = [p["root"] for p in project_store.all_projects()
+             if target.startswith(os.path.normcase(os.path.abspath(p["root"])) + os.sep)]
+    return max(roots, key=len) if roots else None
+
+
+def _impact_line(root, rel, name):
+    """Callers and tests from the code graph, only when its analysis is already cached: the hook never waits for one."""
+    if not root or code_graph.cached_symbols(root)[0] is None:
+        return ""
+    try:
+        found = code_impact.impact(root, f"{rel}::{name}", limit=3)
+    except ValueError:
+        return ""
+    counts = found["counts"]
+    tests = ", ".join(f"{t['function']} ({t['path']})" for t in found["tests"])
+    calls = f"; tests calling it: {tests}" if tests else ""
+    return f" {counts['callers']} caller(s){calls}; project_manage affected_tests lists every test to run after the edit."
+
+
+def _doc_lines(findings):
+    lines = []
+    for root, rel, item in findings[:MAX_DOC_FINDINGS]:
+        if item["issue"] == "missing":
+            text = f"{item['name']} ({rel}:{item['start']}) has no docstring: write one (purpose, parameters, return)."
+        else:
+            text = (f"{item['name']} ({rel}:{item['start']}) changed its signature: update its docstring if the "
+                    f"contract changed.")
+        lines.append(text + _impact_line(root, rel, item["name"]))
+    if len(findings) > MAX_DOC_FINDINGS:
+        lines.append(f"{len(findings) - MAX_DOC_FINDINGS} more function(s) in the same situation.")
+    return "Smart Tool docs: " + " ".join(lines)
+
+
+def _duplicate_lines(findings):
+    lines = []
+    for rel, item in findings[:MAX_DUPLICATE_FINDINGS]:
+        existing = item["existing"]
+        where = f"{existing['name']} in {existing['path']}:{existing['lines']}"
+        if item["type"] == "exact":
+            lines.append(f"{item['name']} ({rel}:{item['lines']}) has the same body as {where}: reuse it instead of a copy.")
+        else:
+            lines.append(f"{item['name']} ({rel}:{item['lines']}) is near-identical to {where} (score {item['score']}, "
+                         f"local names ignored): check whether it can be reused.")
+    if len(findings) > MAX_DUPLICATE_FINDINGS:
+        lines.append(f"{len(findings) - MAX_DUPLICATE_FINDINGS} more copied function(s).")
+    return ("Smart Tool duplicates: " + " ".join(lines)
+            + " If the copy is intentional (moving the function, a deliberate fork), go ahead.")
+
+
+def _edit_review(payload, doc_mode, duplicate_mode):
+    """Checks of an edit before it runs. Docstrings follow doc_mode, in code files of registered projects only (tests,
+    docs and files outside a project are left out, as in the docs coverage): missing ones deny the edit in require mode and become a reminder in remind mode; a
+    documented function whose signature changed always gets a reminder. Copies of indexed functions follow
+    duplicate_mode and only add context, never deny."""
+    doc_findings, duplicate_findings, failures = [], [], []
+    for path, before, after in edit_preview.preview(payload.get("tool_name"), payload.get("tool_input"), payload.get("cwd")):
+        if not doc_check.supported(path):
+            continue
+        root = _project_of(path)
+        rel = os.path.relpath(path, root).replace(os.sep, "/") if root else os.path.basename(path)
+        edited = doc_check.written(path, before, after)
+        profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile")) if root else None
+        if doc_mode != "off" and root and index_profile.kind(rel, profile) == "code":
+            doc_findings += [(root, rel, item) for item in doc_check.review(path, before, after, edited)]
+        if duplicate_mode != "off" and root and edited["touched"]:
+            try:
+                duplicate_findings += [(rel, item) for item in duplicates.on_write(root, path, before, after, edited)]
+            except (ValueError, RuntimeError) as exc:
+                failures.append(f"Smart Tool duplicates check skipped: {exc}")
+    parts = ([_doc_lines(doc_findings)] if doc_findings else []) + \
+        ([_duplicate_lines(duplicate_findings)] if duplicate_findings else []) + failures
+    if not parts:
+        return {}
+    message = " ".join(parts)
+    if doc_mode == "require" and any(item["issue"] == "missing" for _root, _rel, item in doc_findings):
+        return deny(message + " Redo the edit with the docstring.")
+    return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": message}}
+
+
 def decide(payload, client, web_route):
-    """Hook output for one PreToolUse payload, following config hook_mode (redirect | advise | off)."""
+    """Hook output for one PreToolUse payload: edits follow doc_mode (require | remind | off) and duplicate_mode
+    (warn | off), the other tools follow hook_mode (redirect | advise | off)."""
     cfg = config.load_config()
+    if isinstance(payload, dict) and payload.get("tool_name") in EDIT_TOOLS:
+        doc_mode, duplicate_mode = config.doc_mode(cfg), config.duplicate_mode(cfg)
+        if doc_mode == "off" and duplicate_mode == "off":
+            return {}
+        return _edit_review(payload, doc_mode, duplicate_mode)
     mode = config.hook_mode(cfg)
     if mode == "off" or not isinstance(payload, dict):
         return {}
@@ -82,7 +180,7 @@ def _route(payload, client, web_route, cfg):
             return {}
         decision = web_route(tool_name, str(tool_input.get("url") or ""))
         return deny(clean_reason(decision.get("reason"))) if decision.get("redirect") else {}
-    router.CLIENT = client
+    router.CLIENT.set(client)
     try:
         decision, reason = router.decide(tool_name, tool_input, router_model, cwd=cwd)
     except Exception as exc:

package/index_profile.py

@@ -17,7 +17,7 @@ DOC_DATA = {"html", "htm", "json", "csv", "xml", "yaml", "yml", "svg"}
 _NAME_DOC = re.compile(r"(^|/)(readme|changelog|license|licence|contributing|install|history|authors)(\.[^/]*)?$", re.I)
 _DIR_DOC = re.compile(r"(^|/)(docs?|adrs?|documentation)/", re.I)
 _TEST = re.compile(r"(^|/)(tests?|__tests__|spec|specs|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)test_[^/]+\.py$|"
-                   r"(^|/)conftest\.py$|_test\.(py|go)$|\.(test|spec)\.[cm]?[jt]sx?$|(^|/)[^/]*[a-z0-9](?-i:Tests?)\.java$|"
+                   r"(^|/)conftest\.py$|_test\.(py|go)$|\.(test|spec)(-d)?\.[cm]?[jt]sx?$|(^|/)[^/]*[a-z0-9](?-i:Tests?)\.java$|"
                    r"(^|/)src/test/|(^|/)test[-_][^/]*\.[cm]?[jt]sx?$|[-_]test\.[cm]?[jt]sx?$", re.I)
 _TEST_PROSE = re.compile(r"(^|/)(tests?|__tests__|e2e|fixtures?|testdata|test-utils?)(/|$)|(^|/)src/test/", re.I)
 _TEXT_LINE = re.compile(r"[A-Za-zÀ-ú]{3,}\s+[A-Za-zÀ-ú]{3,}")

package/index_scope.py

@@ -415,6 +415,22 @@ def _exclude_matcher(exclude):
     return matches
 
 
+def in_scope(scope, rel_path):
+    """Whether resolve_included_files would list rel_path: under an include base, outside the exclusions and outside
+    hidden folders."""
+    rel_path = rel_path.replace("\\", "/")
+    include = scope.get("include") or [""]
+    matcher = _exclude_matcher(set(scope.get("exclude") or []) | set(scope.get("user_exclude") or []) |
+                               _ALWAYS_EXCLUDE | _ALWAYS_EXCLUDE_FILES)
+    parts = rel_path.split("/")
+    if matcher(rel_path) or any(part.startswith(".") for part in parts[:-1]):
+        return False
+    if any(base in ("", ".") for base in include):
+        return True
+    return len(parts) == 1 or any(rel_path == base.strip("/") or rel_path.startswith(base.strip("/") + "/")
+                                  for base in include)
+
+
 def resolve_included_files(root, scope, cancel_check=None):
     if not valid_scope(scope):
         raise ValueError("Invalid scope; request a new project analysis.")

package/indexer.py

@@ -841,6 +841,12 @@ def search(root, query_vector=None, top_k=20, query=None, model_id=None, include
     return [(scores[chunk_id], *by_id[chunk_id][1:5]) for chunk_id in ids[:top_k]]
 
 
+def graph_cache_path(view_path):
+    """Where code_graph keeps the saved analysis of one index view (graph-cache/<view>.json.gz next to it)."""
+    return os.path.join(os.path.dirname(view_path), "graph-cache",
+                        os.path.basename(view_path).removesuffix(".sqlite3") + ".json.gz")
+
+
 def remove_index(root):
     """Remove somente arquivos de índice da raiz conhecida, nunca arquivos do projeto."""
     import glob
@@ -855,6 +861,10 @@ def remove_index(root):
                 except PermissionError as exc:
                     raise RuntimeError("The index is open in another process. Close the external reader and try removing it again.") from exc
                 removed.append(safe)
+                try:
+                    os.remove(graph_cache_path(safe))
+                except FileNotFoundError:
+                    pass
     invalidate_cache(root)
     return removed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
   "license": "Apache-2.0",
   "author": "Allan Santos",

package/router.py

@@ -5,6 +5,7 @@ modelo pequeno se deve deixar passar ou redirecionar pra `smart_search`. Cada de
 logada em `router-metrics.jsonl` pra orientar um classificador mais fino depois, com
 base em uso real — não numa suposição a priori.
 """
+import contextvars
 import json
 import os
 import paths
@@ -17,7 +18,8 @@ import index_scope
 import indexer
 import web_search_adapters
 
-CLIENT = None
+# Per request: the daemon serves each hook call on its own thread, so a module global mixed up clients.
+CLIENT = contextvars.ContextVar("router_client", default=None)
 METRICS_PATH = os.path.join(paths.DATA_DIR, "router-metrics.jsonl")
 
 _SYSTEM_PROMPT = (
@@ -266,7 +268,7 @@ def _log_decision(tool_name, tool_input, decision, reason, extra=None):
         "tool_input": _redacted_input(tool_input),
         "decision": decision,
         "reason": reason,
-        **({"client": CLIENT} if CLIENT else {}),
+        **({"client": CLIENT.get()} if CLIENT.get() else {}),
     }
     record.update(extra or {})
     try:
@@ -290,18 +292,21 @@ def log_unavailable(tool_name, tool_input, exc):
     )
 
 
-# Verbo ancorado no início do comando ou de um segmento (`|`, `;`, `&&`, `$(`): casar por
-# substring solta faria qualquer palavra inglesa dentro de um heredoc Python contar como
-# busca. A ausência de verbo é prova mecânica de que o `command` não busca código.
+# Search/read verbs count only where they start a command: at the beginning, after `;`, `&&`, `||`, `$(`, a backtick,
+# a loop/if keyword or a shell invoker (`bash -c`, `powershell -Command`, `cmd /c`). After a single `|` they filter the
+# output of the command before them (`python x.py | tail -5`), which reads no source code.
 _SEARCH_VERB_RE = re.compile(
-    # Início, separador de segmento, ou logo depois de um invocador de shell
-    # (`powershell -Command`, `bash -c`, `cmd /c`), que é como o verbo real costuma
-    # aparecer no meio de um comando em máquina Windows.
-    r"(?:^|[|;&]|\$\(|`|-c\s|-Command\s|/c\s|/k\s)\s*(?:sudo\s+|command\s+)?"
+    r"(?:^|[;&]|\|\||\$\(|`|-c\s|-Command\s|/c\s|/k\s)\s*[\"']?\s*(?:(?:do|then|else)\s+)?(?:sudo\s+|command\s+)?"
     r"(grep|egrep|fgrep|rg|ripgrep|find|findstr|fd|cat|type|head|tail|less|more|"
     r"ls|dir|awk|sed|ack|ag|select-string|sls|get-content|gc|get-childitem|gci)\b",
     re.IGNORECASE,
 )
+# Commands that read code or pages without a search verb at their start: their pipe filters still search content.
+_READ_PRODUCER_RE = re.compile(
+    r"\bgit\s+(grep|ls-files|show|log\s+-p|diff)\b|\b(curl|wget|iwr|invoke-webrequest)\b|\bgh\s+api\b|"
+    r"readFileSync|read_text\(|open\(",
+    re.IGNORECASE,
+)
 _READ_TOOLS = frozenset({"Read", "NotebookRead"})
 
 BREAKER_PATH = os.path.join(os.path.dirname(METRICS_PATH), "router-breaker.json")
@@ -316,14 +321,17 @@ def _mechanical_decision(tool_name, tool_input):
     Medido em 1973 decisões reais: 97,8% eram `allow`, e 1512 delas (77%) caíam nestes
     casos — cada uma custando uma ida ao gateway antes de toda tool call do agente. Os
     dois únicos `Read` redirecionados nesse histórico eram decisões erradas (um deles com
-    `offset`/`limit` explícitos, onde só as linhas pedidas servem)."""
+    `offset`/`limit` explícitos, onde só as linhas pedidas servem). Remedido em 2026-10-08
+    sobre 2488 Bash que foram ao modelo (mediana 1,5 s, 7,8% redirecionados): ignorar os
+    filtros depois de `|` (salvo quando o produtor lê código ou páginas) decide 439 deles
+    sem modelo (13,3 min em 58 h) e perde 1 dos 155 redirecionamentos."""
     if tool_name in _READ_TOOLS:
         return "allow", "Reading a specific file is never replaced by semantic search."
     if tool_name == "Bash":
         command = tool_input.get("command")
         if not isinstance(command, str) or not command.strip():
             return "allow", "Bash without a readable command."
-        if not _SEARCH_VERB_RE.search(command):
+        if not _SEARCH_VERB_RE.search(command) and not _READ_PRODUCER_RE.search(command):
             return "allow", "The command neither searches nor reads source code."
     return None
 

package/setup_ui.py

@@ -177,18 +177,31 @@ def handle_integration_get():
         mode, mode_error = config.hook_mode(), ""
     except ValueError as exc:
         mode, mode_error = "", str(exc)
+    try:
+        doc_mode, doc_error = config.doc_mode(), ""
+    except ValueError as exc:
+        doc_mode, doc_error = "", str(exc)
+    try:
+        duplicate_mode, duplicate_error = config.duplicate_mode(), ""
+    except ValueError as exc:
+        duplicate_mode, duplicate_error = "", str(exc)
     return {"daemon_url": setup_origin(), "clients": clients, "hook_mode": mode, "hook_mode_error": mode_error,
-            "hook_modes": list(config.HOOK_MODES)}
+            "hook_modes": list(config.HOOK_MODES), "doc_mode": doc_mode, "doc_mode_error": doc_error,
+            "doc_modes": list(config.DOC_MODES), "duplicate_mode": duplicate_mode,
+            "duplicate_mode_error": duplicate_error, "duplicate_modes": list(config.DUPLICATE_MODES)}
 
 
 def handle_integration_save(body):
     """`hook_mode` sets redirect/advise/off for every client; `register_mcp` runs the client's CLI; hook in two steps:
     `preview` shows the exact change, `install` writes it (with backup)."""
-    if isinstance(body, dict) and body.get("action") == "hook_mode":
-        if body.get("mode") not in config.HOOK_MODES:
-            raise SetupError("Invalid mode: use redirect, advise or off.")
+    if isinstance(body, dict) and body.get("action") in ("hook_mode", "doc_mode", "duplicate_mode"):
+        action = body["action"]
+        allowed = {"hook_mode": config.HOOK_MODES, "doc_mode": config.DOC_MODES,
+                   "duplicate_mode": config.DUPLICATE_MODES}[action]
+        if body.get("mode") not in allowed:
+            raise SetupError(f"Invalid mode: use {', '.join(allowed)}.")
         try:
-            config.update_config(lambda cfg: cfg.update(hook_mode=body["mode"]))
+            config.update_config(lambda cfg: cfg.update({action: body["mode"]}))
         except (OSError, config.ConfigCorruptedError) as exc:
             raise SetupError(str(exc))
         return handle_integration_get()
@@ -565,6 +578,21 @@ _PAGE_TEMPLATE = """<!doctype html>
           </select>
           <span class="hint" id="hook-mode-hint">Applies to every client on the next tool call; nothing is reinstalled.</span></div>
         <div class="actions"><button type="button" id="btn-save-hook-mode">Save behavior</button></div>
+        <div class="field" style="margin-top:16px"><label for="sel-doc-mode">Documentation on edit</label>
+          <select id="sel-doc-mode">
+            <option value="remind">Remind: the edit runs; the agent is told which touched functions lack a docstring (default)</option>
+            <option value="require">Require: an edit that leaves a touched function without a docstring is blocked until it adds one</option>
+            <option value="off">Off: no documentation checks</option>
+          </select>
+          <span class="hint">Only public functions the edit touches (private, nested and override functions are exempt, as in pydocstyle, eslint-plugin-jsdoc and Checkstyle). A documented function is mentioned again only when its signature changes; body-only edits stay silent.</span></div>
+        <div class="actions"><button type="button" id="btn-save-doc-mode">Save documentation</button></div>
+        <div class="field" style="margin-top:16px"><label for="sel-duplicate-mode">Duplicate functions on edit</label>
+          <select id="sel-duplicate-mode">
+            <option value="warn">Warn: the edit runs; the agent is told when a written function copies one already in the project (default)</option>
+            <option value="off">Off: no duplicate checks on edit</option>
+          </select>
+          <span class="hint">Compares functions the edit writes with the indexed code: identical bodies, and near-identical ones with only local names changed. Never blocks.</span></div>
+        <div class="actions"><button type="button" id="btn-save-duplicate-mode">Save duplicates</button></div>
         <div class="msg" id="agents-msg" role="status"></div>
         <div id="agents-list"></div>
       </section>
@@ -849,7 +877,11 @@ async function loadAgents() {
     const data = await resp.json();
     if (!resp.ok || data.error) throw new Error(data.error);
     if (document.activeElement !== $("sel-hook-mode")) $("sel-hook-mode").value = data.hook_mode;
+    if (document.activeElement !== $("sel-doc-mode")) $("sel-doc-mode").value = data.doc_mode;
+    if (document.activeElement !== $("sel-duplicate-mode")) $("sel-duplicate-mode").value = data.duplicate_mode;
     if (data.hook_mode_error) setMsg("agents-msg", "error", data.hook_mode_error);
+    if (data.doc_mode_error) setMsg("agents-msg", "error", data.doc_mode_error);
+    if (data.duplicate_mode_error) setMsg("agents-msg", "error", data.duplicate_mode_error);
     const list = $("agents-list");
     list.textContent = "";
     for (const item of data.clients) {
@@ -913,6 +945,22 @@ async function loadAgents() {
   }
 }
 loadAgents();
+$("btn-save-doc-mode").addEventListener("click", async () => {
+  try {
+    await post("/setup/integration", { action: "doc_mode", mode: $("sel-doc-mode").value });
+    setMsg("agents-msg", "ok", "Documentation setting saved; it applies on the next edit.");
+  } catch (error) {
+    setMsg("agents-msg", "error", error.message);
+  }
+});
+$("btn-save-duplicate-mode").addEventListener("click", async () => {
+  try {
+    await post("/setup/integration", { action: "duplicate_mode", mode: $("sel-duplicate-mode").value });
+    setMsg("agents-msg", "ok", "Duplicate setting saved; it applies on the next edit.");
+  } catch (error) {
+    setMsg("agents-msg", "error", error.message);
+  }
+});
 $("btn-save-hook-mode").addEventListener("click", async () => {
   try {
     await post("/setup/integration", { action: "hook_mode", mode: $("sel-hook-mode").value });