@allansantos-dev/smart-tool 0.9.81 → 0.9.83

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.
Files changed (59) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/NOTICE +1 -1
  3. package/README.md +73 -14
  4. package/affected_tests.py +9 -8
  5. package/agent_redirect.py +32 -0
  6. package/autostart.py +32 -25
  7. package/browser_bridge.py +320 -0
  8. package/browser_control.py +76 -39
  9. package/browser_service_client.py +1 -7
  10. package/client_hooks.py +41 -42
  11. package/code_graph.py +66 -21
  12. package/code_graph_java.mjs +21 -12
  13. package/code_health.py +14 -9
  14. package/codex_config.py +3 -0
  15. package/commit_check.py +184 -0
  16. package/daemon_launcher.py +37 -5
  17. package/doc_candidates.py +63 -0
  18. package/doc_check.py +9 -3
  19. package/doc_extras.py +2 -3
  20. package/doc_insights.py +26 -2
  21. package/doc_prose.py +59 -11
  22. package/doc_registry.py +241 -0
  23. package/doc_scope.py +205 -39
  24. package/doc_turn.py +205 -0
  25. package/doc_validate.py +52 -9
  26. package/document_converter.py +4 -4
  27. package/document_read.py +19 -11
  28. package/document_url.py +107 -0
  29. package/edit_shape.py +119 -0
  30. package/endpoint_sync.py +3 -21
  31. package/engine_home.py +95 -0
  32. package/hook_call.py +133 -0
  33. package/hook_decision.py +142 -7
  34. package/hooks/pre_commit.py +45 -0
  35. package/hooks/pretool_router.py +36 -30
  36. package/hooks/turn_end.py +40 -0
  37. package/index_views.py +5 -0
  38. package/install.py +24 -9
  39. package/lazy_mcp_proxy.py +10 -9
  40. package/local_embedder.py +8 -1
  41. package/locales/pt-BR.json +1 -2
  42. package/model_breaker.py +6 -5
  43. package/package.json +2 -2
  44. package/process_limits.py +17 -3
  45. package/project_identity.py +19 -1
  46. package/project_scan.py +98 -0
  47. package/release_notes.py +125 -0
  48. package/rename_preview.py +95 -0
  49. package/requester.py +1 -1
  50. package/scout_access.py +48 -0
  51. package/shell_reads.py +67 -0
  52. package/smart_tool_daemon.py +245 -50
  53. package/tray.py +31 -0
  54. package/venv_launch.py +67 -0
  55. package/version.py +1 -1
  56. package/web_adapters/node/engine-home.mjs +42 -0
  57. package/web_adapters/node/package-lock.json +13 -0
  58. package/web_adapters/node/package.json +1 -0
  59. package/web_fetch_many.py +61 -0
package/doc_validate.py CHANGED
@@ -122,7 +122,7 @@ def _function_line(model, function, number):
122
122
  """True when the project file's line holds the function's own name (its definition line)."""
123
123
  text = model.read(function["path"])
124
124
  lines = text.split("\n") if text else []
125
- name = function["name"].split(".")[-1].split("@")[0]
125
+ name = function["name"].split("(", 1)[0].split(".")[-1].split("@")[0]
126
126
  return 0 < number <= len(lines) and re.search(rf"\b{re.escape(name)}\b", lines[number - 1]) is not None
127
127
 
128
128
 
@@ -198,15 +198,55 @@ class _Validation:
198
198
  by_path = defaultdict(list)
199
199
  for symbol in self.model.graph.get("symbols") or []:
200
200
  by_path[symbol["path"]].append(symbol)
201
- current, stamps = doc_scope._current_code(self.root, {m["id"].rpartition("::")[0] for m in markers}, by_path)
201
+ current = doc_scope._current_code(self.root, {m["id"].rpartition("::")[0] for m in markers}, by_path)
202
202
  for marker in markers:
203
203
  now = current.get(marker["id"])
204
- check.verify(now == marker["signature"], f"{marker['file']}:{marker['line']}",
205
- f"`{marker['id']}` ({marker['file']}:{marker['line']}) has the signature of the code",
206
- f"`{marker['id']}` " + ("no longer exists in the code" if now is None else "changed its signature"))
207
- for item in doc_scope.stale_prose(self.pages, stamps):
204
+ parts = doc_scope.changed_parts(marker, now) if now else []
205
+ check.verify(now is not None and not parts, f"{marker['file']}:{marker['line']}",
206
+ f"`{marker['id']}` ({marker['file']}:{marker['line']}) has the signature, body and docstring of "
207
+ "the code", f"`{marker['id']}` " + ("no longer exists in the code" if now is None
208
+ else f"changed its {' and '.join(parts)} since generation"))
209
+ for item in doc_scope.stale_prose(self.pages, doc_scope.prose_stamps(self.model)):
208
210
  check.fail(f"{item['file']}:{item['line']}", f"the paragraph of `{item['id']}` was written for other code of "
209
- "the function: its body changed since")
211
+ "the feature: its entry point or a function its flow reaches changed since")
212
+
213
+ def chain(self):
214
+ check = self.check("chain", "Every feature a technical entry names lists that entry in its section of the "
215
+ "functional overview, and the other way round")
216
+ technical, functional = {"": set(), "possible ": set()}, {"": set(), "possible ": set()}
217
+ for rel, found in self.sections.items():
218
+ if not rel.startswith("technical/"):
219
+ continue
220
+ for anchor, section in found.items():
221
+ if anchor not in self.model.function_of:
222
+ continue
223
+ if not any(l.startswith("- Feature: ") for _n, l in section["body"]):
224
+ check.fail(f"{rel}:{section['line']}", f"`{anchor}` has no Feature line")
225
+ for number, line in section["body"]:
226
+ kind = "" if line.startswith("- Feature: ") else "possible " if line.startswith(
227
+ "- Possible feature: ") else None
228
+ for _label, target in _ANY_LINK.findall(line) if kind is not None else ():
229
+ path, _sep, feature = target.strip("<>").partition("#")
230
+ if _resolve(rel, path) == "functional.md":
231
+ technical[kind].add((html.unescape(feature), anchor, f"{rel}:{number}"))
232
+ for feature, section in self.sections.get("functional.md", {}).items():
233
+ if section["heading"] is None or feature.startswith("cli:"):
234
+ continue
235
+ for number, line in section["body"]:
236
+ kind = "possible " if line.startswith("- possible: ") else ""
237
+ for _label, target in _ANY_LINK.findall(line):
238
+ path, _sep, anchor = target.strip("<>").partition("#")
239
+ if _resolve("functional.md", path).startswith("technical/"):
240
+ functional[kind].add((feature, html.unescape(anchor), f"functional.md:{number}"))
241
+ for kind in technical:
242
+ written = {(f, a) for f, a, _w in functional[kind]}
243
+ named = {(f, a) for f, a, _w in technical[kind]}
244
+ for feature, anchor, where in sorted(technical[kind]):
245
+ check.verify((feature, anchor) in written, where, f"`{anchor}` and feature `{feature}` link each other",
246
+ f"`{anchor}` names {kind}feature `{feature}`, whose section does not list it")
247
+ for feature, anchor, where in sorted(functional[kind]):
248
+ check.verify((feature, anchor) in named, where, f"`{anchor}` and feature `{feature}` link each other",
249
+ f"{kind}feature `{feature}` lists `{anchor}`, whose technical entry does not name it")
210
250
 
211
251
  def links(self):
212
252
  check = self.check("links", "Every link resolves to an existing page, file and anchor")
@@ -274,7 +314,7 @@ class _Validation:
274
314
  for path, at in _PATH_LINE.findall(line):
275
315
  source = self.model.read(path)
276
316
  rows = source.split("\n") if source else []
277
- word = name.group(1).split(".")[-1]
317
+ word = name.group(1).split("(", 1)[0].split(".")[-1]
278
318
  held = 0 < int(at) <= len(rows) and word in rows[int(at) - 1]
279
319
  check.verify(held, f"{rel}:{number}", f"`{name.group(1)}` is at {path}:{at}",
280
320
  f"line {at} of `{path}` does not hold `{name.group(1)}`")
@@ -500,6 +540,9 @@ class _Validation:
500
540
  tests = self.model.tests_of(anchor) if anchor in self.model.function_of else []
501
541
  check.verify(count == len(tests), f"extras/features-tests.md:{number}", f"`{anchor}`: {count} test(s)",
502
542
  f"`{anchor}` shows {count} test(s), the graph reaches {len(tests)}")
543
+ if not rows and not self.entries and "No entry point found" in text:
544
+ check.ok("extras/features-tests.md says no entry point was found")
545
+ return
503
546
  bare = sum(1 for a in self.entries[:rows] if not self.model.tests_of(a))
504
547
  found = re.search(r"^(\d+) of (\d+) entry point", text, re.M)
505
548
  check.verify(found and [int(found.group(1)), int(found.group(2))] == [bare, rows], "extras/features-tests.md",
@@ -636,7 +679,7 @@ class _Validation:
636
679
  check.fail(f"extras/dependencies.md ({path})", f"`{key[0]}` is not declared in {path}")
637
680
 
638
681
  def run(self):
639
- for step in (self.markers, self.links, self.lines, self.relations, self.coverage, self.entry_points,
682
+ for step in (self.markers, self.chain, self.links, self.lines, self.relations, self.coverage, self.entry_points,
640
683
  self.features, self.command_lines, self.prose, self.entry_tests, self.labels, self.counts,
641
684
  self.glossary, self.navigation, self.versions):
642
685
  step()
@@ -114,16 +114,16 @@ def _checked(engine, pages, expected_pages):
114
114
  return pages
115
115
 
116
116
 
117
- def cache_folder():
118
- """The one folder of this version's converted pages: `%LOCALAPPDATA%\\SmartTool\\cache\\<version>\\convert`, created
119
- here; the folders of other versions are deleted the first time it is asked for in a process.
117
+ def cache_folder(name="convert"):
118
+ """The folder `name` of this version's cache: `%LOCALAPPDATA%\\SmartTool\\cache\\<version>\\<name>` (the converted
119
+ pages by default), created here; the folders of other versions are deleted the first time it is asked for in a process.
120
120
 
121
121
  Raises: RuntimeError when LOCALAPPDATA is not set."""
122
122
  local = os.environ.get("LOCALAPPDATA")
123
123
  if not local:
124
124
  raise RuntimeError("LOCALAPPDATA is not set: there is no per-user folder for the converter's cache.")
125
125
  root = os.path.join(local, "SmartTool", "cache")
126
- folder = os.path.join(root, version.VERSION, "convert")
126
+ folder = os.path.join(root, version.VERSION, name)
127
127
  os.makedirs(folder, exist_ok=True)
128
128
  if root not in _swept:
129
129
  _swept.add(root)
package/document_read.py CHANGED
@@ -35,7 +35,8 @@ class NoTextLayer(document_text.DocumentError):
35
35
  """A PDF whose pages carry no text: `pages` is its page count."""
36
36
 
37
37
  def __init__(self, pages):
38
- super().__init__(f'PDF of {pages} pages has no text layer (scanned pages are not read; there is no OCR).')
38
+ super().__init__(f'PDF of {pages} pages has no text layer (scanned pages are not read; set `document_converter` '
39
+ f'to auto, kreuzberg or docling in config.json, with the engine installed, to read them).')
39
40
  self.pages = pages
40
41
 
41
42
 
@@ -214,7 +215,8 @@ def load(path):
214
215
  converted = extension not in KINDS and extension in document_converter.EXTENSIONS and document_converter.enabled()
215
216
  if extension not in KINDS and not converted:
216
217
  raise ValueError(f"read_document reads {', '.join(KINDS)} files; {extension or 'this file'} is not supported "
217
- '(use the normal Read for plain text; legacy .doc, .xls, .xlsb and .ppt and macro files other than .xlsm are not read)')
218
+ '(use the normal Read for plain text; images, legacy .doc, .xls and .ppt, OpenDocument and .rtf are read '
219
+ 'when `document_converter` is set to auto, kreuzberg or docling in config.json with the engine installed; .xlsb and macro files other than .xlsm are never read)')
218
220
  try:
219
221
  info = os.stat(path)
220
222
  except OSError as exc:
@@ -284,12 +286,13 @@ def _spans(numbers):
284
286
  return ', '.join(spans)
285
287
 
286
288
 
287
- def header(document):
289
+ def header(document, shown_as=None):
288
290
  """The metadata block that opens every answer: path, type, size, units and the estimated tokens of the whole text.
289
291
 
290
- Parameters: document. Returns: the block as text."""
292
+ Parameters: document; shown_as (what the first line names instead of the document's path, for a file downloaded
293
+ from a URL). Returns: the block as text."""
291
294
  total = sum(estimate_tokens(unit.text) for unit in document.units)
292
- lines = [f'document: {document.path}',
295
+ lines = [f'document: {shown_as or document.path}',
293
296
  f'type: {document.kind} | size: {document.size / 1048576:.2f} MiB | '
294
297
  f'{UNIT_NAMES[document.kind]}s: {len(document.units)} | est. tokens (all text): {total:,}']
295
298
  lines += [f'{key}: {value}' for key, value in document.facts.items()
@@ -297,18 +300,23 @@ def header(document):
297
300
  return '\n'.join(lines)
298
301
 
299
302
 
300
- def read(path, range_spec=None, max_chars=DEFAULT_MAX_CHARS, info_only=False):
303
+ def check_max_chars(max_chars):
304
+ """Raises ValueError unless max_chars is an integer from 1000 to MAX_CHARS_LIMIT."""
305
+ if isinstance(max_chars, bool) or not isinstance(max_chars, int) or not 1000 <= max_chars <= MAX_CHARS_LIMIT:
306
+ raise ValueError(f'max_chars must be an integer from 1000 to {MAX_CHARS_LIMIT}')
307
+
308
+
309
+ def read(path, range_spec=None, max_chars=DEFAULT_MAX_CHARS, info_only=False, shown_as=None):
301
310
  """The answer of read_document: the metadata block, then the chosen units as markdown, a note naming the next range
302
311
  when the text was cut.
303
312
 
304
313
  Parameters: path (see load), range_spec (see parse_range; None reads from the first unit up to max_chars),
305
314
  max_chars (cap of the text returned, 1000-MAX_CHARS_LIMIT; a single unit over the cap is cut at a line with a
306
- notice), info_only (only the metadata block). Returns: the text. Raises: as load and parse_range, ValueError for a
307
- max_chars out of bounds."""
308
- if isinstance(max_chars, bool) or not isinstance(max_chars, int) or not 1000 <= max_chars <= MAX_CHARS_LIMIT:
309
- raise ValueError(f'max_chars must be an integer from 1000 to {MAX_CHARS_LIMIT}')
315
+ notice), info_only (only the metadata block), shown_as (see header). Returns: the text. Raises: as load and
316
+ parse_range, ValueError for a max_chars out of bounds."""
317
+ check_max_chars(max_chars)
310
318
  document = load(path)
311
- head = header(document)
319
+ head = header(document, shown_as)
312
320
  if info_only:
313
321
  return head
314
322
  numbers = parse_range(range_spec, document) if range_spec else list(range(1, len(document.units) + 1))
@@ -0,0 +1,107 @@
1
+ """read_document by URL: the file is downloaded with the web_fetch download (public addresses only, every redirect hop
2
+ checked, 5 MB cap) into the per-user cache folder and then read by document_read like a local file, so ranges and the
3
+ token estimate work the same. A web page is refused with the pointer to web_fetch. The query string and the
4
+ credentials of a URL are never part of the answer or of a file name."""
5
+ import hashlib
6
+ import os
7
+ import time
8
+ import urllib.parse
9
+
10
+ import atomic_io
11
+ import document_converter
12
+ import document_read
13
+ import web_fetch
14
+
15
+ FOLDER = "download"
16
+ URL_EXTENSIONS = (".pdf", ".docx", ".pptx", ".xlsx", ".xlsm", ".csv", ".epub")
17
+ CONTENT_TYPES = {"application/pdf": ".pdf", "text/csv": ".csv", "application/epub+zip": ".epub",
18
+ "application/vnd.ms-excel.sheet.macroenabled.12": ".xlsm",
19
+ **{kind: "." + extension for kind, extension in web_fetch.OFFICE_TYPES.items()}}
20
+ EXTENSION_FALLBACK_TYPES = web_fetch.GENERIC_BINARY_TYPES + web_fetch.TEXT_TYPES
21
+
22
+
23
+ def is_url(value):
24
+ """Whether `value` is read as a URL: a string that starts with `http://` or `https://`, nothing else."""
25
+ return isinstance(value, str) and value.startswith(("http://", "https://"))
26
+
27
+
28
+ def shown(url):
29
+ """The URL as an answer names it: scheme, host, port and path, without credentials, query or fragment.
30
+
31
+ Raises: ValueError when the URL cannot be parsed."""
32
+ try:
33
+ parts = urllib.parse.urlsplit(url)
34
+ host, port = parts.hostname, parts.port
35
+ except ValueError:
36
+ raise ValueError("read_document could not parse the URL") from None
37
+ if not host:
38
+ raise ValueError("read_document needs a host in the URL")
39
+ host = f"[{host}]" if ":" in host else host
40
+ return f"{parts.scheme}://{host}{f':{port}' if port else ''}{parts.path}"
41
+
42
+
43
+ def extension(url):
44
+ """Lowercase extension of the URL path (`.pdf`), empty when there is none or the URL cannot be parsed; this is what
45
+ the metric records, so the query string never reaches it."""
46
+ try:
47
+ return os.path.splitext(urllib.parse.urlsplit(url).path)[1].lower()
48
+ except ValueError:
49
+ return ""
50
+
51
+
52
+ def _document_extension(kind, final_url):
53
+ """File extension for the downloaded bytes: by content type, or by the extension of the final URL path when the
54
+ server sends a generic or text type. Raises ValueError, naming web_fetch, for a web page, and naming the readable
55
+ types for anything else."""
56
+ name = shown(final_url)
57
+ if "html" in kind:
58
+ raise ValueError(f"{name} is a web page ({kind}), not a document: use web_fetch with this URL and a prompt "
59
+ "to read it.")
60
+ found = CONTENT_TYPES.get(kind)
61
+ if not found and kind in EXTENSION_FALLBACK_TYPES and extension(final_url) in URL_EXTENSIONS:
62
+ found = extension(final_url)
63
+ if not found:
64
+ raise ValueError(f"{name} is {kind}, which is not a document read_document reads "
65
+ f"({', '.join(URL_EXTENSIONS)}); for a web page use web_fetch.")
66
+ return found
67
+
68
+
69
+ def _stale_sweep(folder):
70
+ """Deletes the downloads older than the 24 h web_fetch keeps a page."""
71
+ cutoff = time.time() - web_fetch.PAGE_TTL_S
72
+ for entry in os.scandir(folder):
73
+ if entry.is_file() and entry.stat().st_mtime < cutoff:
74
+ try:
75
+ os.remove(entry.path)
76
+ except OSError:
77
+ continue
78
+
79
+
80
+ def download(url, deadline):
81
+ """The local path of the file at `url`: the copy downloaded in the last 24 h, else a fresh download kept in
82
+ `<cache>/download` under a name made of a SHA-256 of the URL (never the URL, the query or the file name).
83
+
84
+ Parameters: url (http or https), deadline (time.monotonic() value). Returns: the path. Raises: FetchError for a
85
+ refused address, a failed or oversized download; ValueError for a web page or a type that is not a document;
86
+ TimeoutError past the deadline."""
87
+ folder = document_converter.cache_folder(FOLDER)
88
+ _stale_sweep(folder)
89
+ stem = hashlib.sha256(web_fetch.normalize(url).encode()).hexdigest()[:40]
90
+ for name in os.listdir(folder):
91
+ if name.startswith(stem + "."):
92
+ return os.path.join(folder, name)
93
+ final_url, kind, _charset, body = web_fetch.fetch_http(web_fetch.normalize(url), deadline)
94
+ path = os.path.join(folder, stem + _document_extension(kind, final_url))
95
+ atomic_io.write_secret_bytes(path, body)
96
+ return path
97
+
98
+
99
+ def read(url, range_spec, max_chars, info_only, deadline):
100
+ """The answer of read_document for an http(s) URL: the file downloaded (or kept from a recent read) and read by
101
+ document_read, with the URL, without its query and credentials, on the first line.
102
+
103
+ Parameters: as document_read.read, with the URL for the path and the deadline of the download. Returns: the text.
104
+ Raises: as download and document_read.read."""
105
+ label = shown(url)
106
+ document_read.check_max_chars(max_chars)
107
+ return document_read.read(download(url, deadline), range_spec, max_chars, info_only, label)
package/edit_shape.py ADDED
@@ -0,0 +1,119 @@
1
+ """Facts about the shape of the project that an edit touches, for the edit hook: the import cycle an added import closes, and
2
+ the hotspot or the usual change partner an edited file has.
3
+
4
+ Both read only what is already cached, so the hook never waits for them: the analysis of the code graph (`code_graph.cached_graph`)
5
+ and the history `doc_insights.history` keeps in memory (`doc_insights.cached_history`). Nothing cached means nothing said:
6
+ no analysis starts and no `git` process runs. Only Python imports are mapped to project files.
7
+ """
8
+ import ast
9
+ import collections
10
+
11
+ import code_graph
12
+ import code_health
13
+ import doc_insights
14
+ import index_profile
15
+ import index_scope
16
+
17
+ HOTSPOT_TOP = 10
18
+ HOTSPOT_MIN_COMMITS = 10
19
+ MAX_FINDINGS = 3
20
+
21
+
22
+ def _module_imports(rel, text, known):
23
+ """The project files a Python text imports at module level, with the line of the first import of each.
24
+
25
+ Parameters: rel (str) project-relative path of the file; text (str) its text; known (set of str) the project's files.
26
+ Returns: dict {file: line}; empty when the text does not parse. An import inside a function or a class is left out: it is
27
+ the usual way to break a cycle.
28
+ """
29
+ try:
30
+ tree = ast.parse(text)
31
+ except (SyntaxError, ValueError, RecursionError):
32
+ return {}
33
+ found = {}
34
+ for node in tree.body:
35
+ if isinstance(node, (ast.Import, ast.ImportFrom)):
36
+ for _alias, target, _base in code_graph.python_import_targets(rel, node, known):
37
+ if target and target != rel:
38
+ found.setdefault(target, node.lineno)
39
+ return found
40
+
41
+
42
+ def _chain(edges, start, goal):
43
+ """The shortest chain of files from `start` to `goal` over the import edges, or [] when `goal` cannot be reached."""
44
+ previous, queue = {start: None}, collections.deque([start])
45
+ while queue:
46
+ node = queue.popleft()
47
+ if node == goal:
48
+ chain = []
49
+ while node is not None:
50
+ chain.append(node)
51
+ node = previous[node]
52
+ return chain[::-1]
53
+ for following in sorted(edges.get(node, ())):
54
+ if following not in previous:
55
+ previous[following] = node
56
+ queue.append(following)
57
+ return []
58
+
59
+
60
+ def added_cycles(root, rel, before, after):
61
+ """The imports an edit adds to a Python file that close an import cycle in the cached code graph.
62
+
63
+ Parameters: root (str) project folder; rel (str) project-relative path of the edited file; before (str or None) text
64
+ before the edit; after (str) text after it.
65
+ Returns: list of {"line", "imports", "chain"} (at most MAX_FINDINGS): the added import, the project file it names and the
66
+ chain of files from that one back to `rel`. Empty when the graph is not cached, the file is not Python or no added
67
+ import has a way back.
68
+ """
69
+ if not rel.endswith(".py"):
70
+ return []
71
+ data = code_graph.cached_graph(root)
72
+ if data is None:
73
+ return []
74
+ known = {item["path"] for item in data.get("files") or []}
75
+ edges = code_graph.import_edges(data)
76
+ old = _module_imports(rel, before, known) if before else {}
77
+ found = []
78
+ for target, line in sorted(_module_imports(rel, after, known).items(), key=lambda item: item[1]):
79
+ chain = [] if target in old else _chain(edges, target, rel)
80
+ if chain:
81
+ found.append({"line": line, "imports": target, "chain": chain})
82
+ return found[:MAX_FINDINGS]
83
+
84
+
85
+ class _Indexed:
86
+ """The part of a documentation model that `doc_insights.coupling` reads, over a cached analysis."""
87
+
88
+ def __init__(self, data):
89
+ self.graph = data
90
+ self._files = [item["path"] for item in data.get("files") or []]
91
+
92
+ def files(self):
93
+ """Project-relative paths of the indexed files."""
94
+ return self._files
95
+
96
+
97
+ def history_findings(root, rels):
98
+ """The hotspots and the usual change partners among the files of an edit, from the cached history and graph.
99
+
100
+ Parameters: root (str) project folder; rels (list of str) project-relative paths of every file in the edit.
101
+ Returns: dict {"hotspots": [{"path", "commits", "rank"}], "coupled": [{"path", "with", "shared", "degree"}]}; a hotspot
102
+ is a code file in the first HOTSPOT_TOP of the commits-times-lines ranking with at least HOTSPOT_MIN_COMMITS commits;
103
+ a partner is a file outside the edit that `doc_insights.coupling` pairs with an edited one and that the edited one does
104
+ not import. Both lists are empty when the history or the graph is not cached.
105
+ """
106
+ nothing = {"hotspots": [], "coupled": []}
107
+ commits = doc_insights.cached_history(root)
108
+ data = code_graph.cached_graph(root) if commits else None
109
+ if data is None:
110
+ return nothing
111
+ lines = {item["path"]: item.get("lines") or 0 for item in data.get("files") or []}
112
+ profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile"))
113
+ ranking = doc_insights.ranked_hotspots(commits, lambda path: path in lines and index_profile.kind(path, profile) == "code",
114
+ lines.get)
115
+ edited = set(rels)
116
+ hot = [{"path": path, "commits": count, "rank": rank} for rank, (path, count, _lines, _last)
117
+ in enumerate(ranking[:HOTSPOT_TOP], 1) if path in edited and count >= HOTSPOT_MIN_COMMITS]
118
+ coupled = code_health.partners(doc_insights.coupling(_Indexed(data), commits), edited)
119
+ return {"hotspots": hot, "coupled": coupled[:MAX_FINDINGS]}
package/endpoint_sync.py CHANGED
@@ -1,8 +1,8 @@
1
1
  """Aponta os clientes para a porta em que o daemon subiu, só quando ela muda.
2
2
 
3
3
  O daemon é dono da porta: depois do bind, reescreve apenas as URLs do smart-tool que os clientes guardam (MCP do
4
- Claude Code em ~/.claude.json, hook HTTP em ~/.claude/settings.json, MCP do Codex em ~/.codex/config.toml). Nada roda
5
- por prompt ou por sessão; o Claude Code relê hooks editados pelo file watcher, o MCP já conectado precisa de /mcp.
4
+ Claude Code em ~/.claude.json, MCP do Codex em ~/.codex/config.toml). Os hooks não guardam porta: leem o arquivo de
5
+ execução do daemon a cada chamada. Nada roda por prompt ou por sessão; o MCP já conectado precisa de /mcp.
6
6
  Cada arquivo é relido logo antes da gravação atômica: o Claude Code reescreve o ~/.claude.json com frequência.
7
7
  """
8
8
  import json
@@ -16,8 +16,6 @@ import codex_config
16
16
  import node_locator
17
17
 
18
18
  SERVER = "smart-tool"
19
- HOOK_PATH = "/hooks/pretool"
20
- POST_HOOK_PATH = "/hooks/posttool"
21
19
  _CODEX_URL_RE = re.compile(r'(\[mcp_servers\.smart-tool\][^\[]*?\burl\s*=\s*")http://127\.0\.0\.1:\d+(/mcp")')
22
20
 
23
21
 
@@ -60,21 +58,6 @@ def _claude_mcp(text, base):
60
58
  return json.dumps(data, indent=2, ensure_ascii=False)
61
59
 
62
60
 
63
- def _claude_hook(text, base):
64
- """settings.json text with our PreToolUse and PostToolUse hook URLs moved to base, or None when none changed."""
65
- data = json.loads(text)
66
- changed = False
67
- hooks = (data.get("hooks") or {}) if isinstance(data, dict) else {}
68
- for event, path in (("PreToolUse", HOOK_PATH), ("PostToolUse", POST_HOOK_PATH)):
69
- groups = (hooks.get(event) or []) if isinstance(hooks, dict) else []
70
- for group in groups if isinstance(groups, list) else []:
71
- for hook in (group.get("hooks") or []) if isinstance(group, dict) else []:
72
- if isinstance(hook, dict) and path in str(hook.get("url", "")):
73
- new = _rebase(hook["url"], base)
74
- changed, hook["url"] = changed or new != hook["url"], new
75
- return json.dumps(data, indent=2, ensure_ascii=False) if changed else None
76
-
77
-
78
61
  def _codex_mcp(text, base):
79
62
  port = urllib.parse.urlsplit(base).port
80
63
  new = _CODEX_URL_RE.sub(lambda m: f"{m.group(1)}http://127.0.0.1:{port}{m.group(2)}", text, count=1)
@@ -82,8 +65,7 @@ def _codex_mcp(text, base):
82
65
 
83
66
 
84
67
  def targets():
85
- return ((claude_json(), _claude_mcp), (os.path.join(claude_dir(), "settings.json"), _claude_hook),
86
- (os.path.join(codex_dir(), "config.toml"), _codex_mcp))
68
+ return ((claude_json(), _claude_mcp), (os.path.join(codex_dir(), "config.toml"), _codex_mcp))
87
69
 
88
70
 
89
71
  _CODEX_ANY_URL_RE = re.compile(r'\[mcp_servers\.smart-tool\][^\[]*?\burl\s*=\s*"([^"]+)"')
package/engine_home.py ADDED
@@ -0,0 +1,95 @@
1
+ """Brings the shared engines Smart Tool consumes (the embeddings home and the graph engine) up through the engine
2
+ registry: installs one that is missing, updates one that is outdated with the signed asset checked by the registry kit,
3
+ and reports why it could not when it cannot. Nothing here raises for a machine without Node, without network or without
4
+ the engine: that is a status the searches and the setup screen show.
5
+ """
6
+ import json
7
+ import os
8
+ import subprocess
9
+ import threading
10
+ import time
11
+
12
+ import node_locator
13
+
14
+ ENGINES = ("casa-de-embeddings", "motor-de-grafo")
15
+ SCRIPT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "web_adapters", "node", "engine-home.mjs")
16
+ TIMEOUT_S = 900
17
+ CHECK_EVERY_S = 24 * 3600
18
+ RETRY_AFTER_S = 600
19
+
20
+ _lock = threading.Lock()
21
+ _last = {}
22
+
23
+
24
+ def forget():
25
+ """Drops what was learned about every engine (tests)."""
26
+ with _lock:
27
+ _last.clear()
28
+
29
+
30
+ def remember(name, status):
31
+ """Keeps `status` as the last answer for `name`, with the time it was kept."""
32
+ with _lock:
33
+ _last[name] = {**status, "at": time.time()}
34
+
35
+
36
+ def status(name):
37
+ """The last status of `name` (`ok`, `url`, `version`, `reason`, `at`), or None when none was asked yet."""
38
+ with _lock:
39
+ return dict(_last[name]) if name in _last else None
40
+
41
+
42
+ def ensure(name):
43
+ """Installs or updates `name`, starts it and waits for it to announce itself.
44
+
45
+ Parameters: name (one of ENGINES). Returns: `{"ok": True, "url", "version", ...}` or `{"ok": False, "reason"}`;
46
+ the result is also kept for `status`. Raises: ValueError for a name that is not an engine of this module."""
47
+ if name not in ENGINES:
48
+ raise ValueError(f"unknown engine {name!r}; Smart Tool consumes {' and '.join(reversed(ENGINES))}")
49
+ result = _run(name)
50
+ remember(name, result)
51
+ return result
52
+
53
+
54
+ def _run(name):
55
+ """One run of the Node script for `name`, as a status."""
56
+ node = node_locator.node()
57
+ if not node:
58
+ return {"ok": False, "reason": f"Node.js was not found, and {name} is installed and updated through it: "
59
+ "install Node.js or let Smart Tool download its own."}
60
+ try:
61
+ done = subprocess.run([node, SCRIPT, name], capture_output=True, text=True, timeout=TIMEOUT_S,
62
+ cwd=os.path.dirname(SCRIPT), env=node_locator.environment(prefer=node),
63
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
64
+ except subprocess.TimeoutExpired:
65
+ return {"ok": False, "reason": f"{name} did not finish installing or starting in {TIMEOUT_S}s."}
66
+ except OSError as exc:
67
+ return {"ok": False, "reason": f"{name} could not be started through Node ({exc})."}
68
+ if done.returncode:
69
+ tail = (done.stderr.strip().splitlines() or ["no error text"])[-1]
70
+ return {"ok": False, "reason": f"{name}: the install step failed (exit {done.returncode}): {tail[:300]}"}
71
+ try:
72
+ answer = json.loads(done.stdout)
73
+ if not isinstance(answer, dict) or type(answer.get("ok")) is not bool:
74
+ raise ValueError("not a status")
75
+ except ValueError:
76
+ return {"ok": False, "reason": f"{name}: the install step gave an answer that is not a status."}
77
+ return answer
78
+
79
+
80
+ def ensure_when_due(name):
81
+ """`ensure(name)` unless it ran recently: a working engine is looked at again after CHECK_EVERY_S, a failed one after
82
+ RETRY_AFTER_S, so a search never waits on an install that just failed. Returns: the status in force."""
83
+ last = status(name)
84
+ wait = CHECK_EVERY_S if last and last["ok"] else RETRY_AFTER_S
85
+ if last and time.time() - last["at"] < wait:
86
+ return last
87
+ return ensure(name)
88
+
89
+
90
+ def explain(name):
91
+ """A sentence for a warning: why `name` is not answering."""
92
+ last = status(name)
93
+ if last is None:
94
+ return f"{name} is being installed or started; it has not answered yet."
95
+ return f"{name} could not be brought up: {last.get('reason') or 'it did not answer'}."