@allansantos-dev/smart-tool 0.9.57 → 0.9.65

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/duplicates.py CHANGED
@@ -45,17 +45,20 @@ _KEYWORDS = {
45
45
  "extends final finally float for if implements import instanceof int interface long native new null "
46
46
  "package private protected public return short static super switch synchronized this throw throws "
47
47
  "transient try void volatile while true false var",
48
+ "go": "break case chan const continue default defer else fallthrough for func go goto if import interface map "
49
+ "package range return select struct switch type var true false nil iota",
48
50
  }
49
51
  _KEYWORDS["ts"] = _KEYWORDS["js"] + " as interface type enum implements private public protected readonly keyof never unknown any"
50
52
  _KEYWORDS = {lang: frozenset(words.split()) for lang, words in _KEYWORDS.items()}
51
53
  _LANG = {"py": "py", "js": "js", "jsx": "js", "mjs": "js", "cjs": "js", "ts": "ts", "tsx": "ts", "mts": "ts",
52
- "cts": "ts", "java": "java"}
54
+ "cts": "ts", "java": "java", "go": "go"}
53
55
  _CONTRACT = re.compile(r"^(__\w+__|equals|hashCode|toString|compareTo|clone|close|run|call|apply|get|set|render|"
54
56
  r"constructor|ng[A-Z]\w*|componentDid\w+|main)$")
55
57
  _DOCSTRING = re.compile(r"\A\s*[rRuUbB]{0,2}(\"\"\"|''')[\s\S]*?\1")
56
58
  _GENERATED = re.compile(r"@generated|DO NOT EDIT|Code generated by|auto-generated", re.I)
57
59
  _WRITE_POOLS = {}
58
- _CONTAINER_KINDS = {"module", "template", "class", "interface"}
60
+ _CONTAINER_KINDS = {"module", "template", "class", "interface", "type"}
61
+ _DECLARATION_KINDS = _CONTAINER_KINDS | {"const", "var"}
59
62
  _GENERIC_NAMES = {"callback", "anonymous", "constructor"}
60
63
  _WARMING = set()
61
64
  _WARM_ERRORS = {}
@@ -208,7 +211,7 @@ def _working_tree_functions(root, changes, profile, include_tests=False):
208
211
  include_tests), with the same identity as indexed ones, so a copy written earlier in the session is caught and
209
212
  a function removed since the last indexing is not reported. The functions of a file are remembered per
210
213
  (modification time, size), so only files written since the last call are read and parsed again."""
211
- found = []
214
+ found, pending = [], []
212
215
  kinds = ("code", "test") if include_tests else ("code",)
213
216
  for rel, status in changes.items():
214
217
  ext = rel.rsplit(".", 1)[-1].lower() if "." in rel else ""
@@ -227,14 +230,17 @@ def _working_tree_functions(root, changes, profile, include_tests=False):
227
230
  source = stream.read()
228
231
  except (OSError, UnicodeDecodeError):
229
232
  continue
230
- if _GENERATED.search(source[:4000]):
231
- continue
233
+ if not _GENERATED.search(source[:4000]):
234
+ pending.append((rel, ext, kind, key, source))
235
+ braced = [(rel, source) for rel, _ext, _kind, _key, source in pending if not rel.lower().endswith(doc_check.PYTHON)]
236
+ symbols = dict(zip((rel for rel, _source in braced), doc_check.analyze_files(braced)))
237
+ for rel, ext, kind, key, source in pending:
232
238
  before = len(found)
233
239
  lines = source.splitlines()
234
- functions = doc_check.functions(rel, source)
240
+ functions = doc_check.functions(rel, source, symbols.get(rel))
235
241
  occurrences = {}
236
242
  for function in functions:
237
- if function["end"] - function["start"] + 1 < MIN_LINES or any(
243
+ if function.get("kind") in _DECLARATION_KINDS or function["end"] - function["start"] + 1 < MIN_LINES or any(
238
244
  other is not function and other["start"] <= function["start"] and function["end"] <= other["end"]
239
245
  and (other["start"], other["end"]) != (function["start"], function["end"]) for other in functions):
240
246
  continue
@@ -486,6 +492,8 @@ def on_write(root, path, before, after, written):
486
492
  remaining = {f["name"].split("(")[0].split(".")[-1] for f in written["all"]}
487
493
  matches = []
488
494
  for function in written["touched"]:
495
+ if function.get("kind") in _DECLARATION_KINDS:
496
+ continue
489
497
  name = function["name"].split("(")[0].split(".")[-1]
490
498
  text = "\n".join(lines[function["start"] - 1:function["end"]])
491
499
  body = _strip_comments(_body(text, ext), ext)
package/hook_decision.py CHANGED
@@ -15,9 +15,11 @@ import os
15
15
  import affected_tests
16
16
  import code_graph
17
17
  import code_impact
18
+ import comment_check
18
19
  import config
19
20
  import dependency_notice
20
21
  import doc_check
22
+ import doc_scope
21
23
  import duplicates
22
24
  import edit_preview
23
25
  import index_profile
@@ -210,7 +212,12 @@ def _run_command(root, tests):
210
212
  def _doc_lines(findings):
211
213
  lines = []
212
214
  for root, rel, item in findings[:MAX_DOC_FINDINGS]:
213
- if item["issue"] == "missing":
215
+ short = item["name"].split(".")[-1]
216
+ if item["issue"] == "missing" and item.get("malformed"):
217
+ text = f"{item['name']} ({rel}:{item['start']}) has a doc comment that does not start with '{short} ': fix it."
218
+ elif item["issue"] == "missing" and item.get("convention") == "go":
219
+ text = f"{item['name']} ({rel}:{item['start']}) has no doc comment: write one starting with '{short} '."
220
+ elif item["issue"] == "missing":
214
221
  text = f"{item['name']} ({rel}:{item['start']}) has no docstring: write one (purpose, parameters, return)."
215
222
  else:
216
223
  text = (f"{item['name']} ({rel}:{item['start']}) changed its signature: update its docstring if the "
@@ -221,6 +228,32 @@ def _doc_lines(findings):
221
228
  return "Smart Tool docs: " + " ".join(lines)
222
229
 
223
230
 
231
+ _COMMENT_FIX = {
232
+ "commented_code": "is commented-out code: delete it, version control keeps it",
233
+ "history_tag": "carries a ticket, version or history tag: drop it, that belongs in the commit message",
234
+ "loose_docs": "documents the function below as a loose comment: move it into the docstring in the language's "
235
+ "standard format",
236
+ "inline_long": "is a long comment inside a function: keep one short line that says why, or move the contract "
237
+ "into the docstring",
238
+ }
239
+
240
+
241
+ def _comment_lines(findings):
242
+ lines = [f"{rel}:{item['line']} {_COMMENT_FIX[item['issue']]}" for rel, item in findings[:MAX_DOC_FINDINGS]]
243
+ if len(findings) > MAX_DOC_FINDINGS:
244
+ lines.append(f"{len(findings) - MAX_DOC_FINDINGS} more comment(s) in the same situation.")
245
+ return "Smart Tool comments: " + "; ".join(lines) + "."
246
+
247
+
248
+ def _scope_lines(findings):
249
+ shown = [f"{item['id']} ({'signature changed' if item['issue'] == 'signature_changed' else 'removed'}, "
250
+ f"{item['file']})" for item in findings[:MAX_DOC_FINDINGS]]
251
+ more = f" and {len(findings) - MAX_DOC_FINDINGS} more" if len(findings) > MAX_DOC_FINDINGS else ""
252
+ return ("Smart Tool docs scope: this edit leaves documented entries out of date: " + "; ".join(shown) + more
253
+ + ". After the edit, regenerate with project_manage action=docs generate=true and review the prose of "
254
+ "those entries.")
255
+
256
+
224
257
  def _duplicate_lines(findings):
225
258
  lines = []
226
259
  for rel, item in findings[:MAX_DUPLICATE_FINDINGS]:
@@ -237,14 +270,15 @@ def _duplicate_lines(findings):
237
270
  + " If the copy is intentional (moving the function, a deliberate fork), go ahead.")
238
271
 
239
272
 
240
- def _edit_review(payload, doc_mode, duplicate_mode, dependency_mode):
273
+ def _edit_review(payload, doc_mode, duplicate_mode, dependency_mode, comment_mode="off"):
241
274
  """Checks of an edit before it runs. Docstrings follow doc_mode, in code files of registered projects only (tests,
242
275
  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
243
- documented function whose signature changed always gets a reminder. Copies of indexed functions follow
244
- duplicate_mode and only add context, never deny. An edit of a package.json, requirements*.txt or go.mod follows dependency_mode: advisories
276
+ documented function whose signature changed always gets a reminder. Comments the edit adds in the wrong place
277
+ (see comment_check) follow comment_mode in the same files: require denies, remind adds context. Copies of indexed
278
+ functions follow duplicate_mode and only add context, never deny. An edit of a package.json, requirements*.txt or go.mod follows dependency_mode: advisories
245
279
  of the added or changed dependencies are added as context, never a denial."""
246
280
  with code_graph.pending_scope():
247
- return _edit_review_scoped(payload, doc_mode, duplicate_mode, dependency_mode)
281
+ return _edit_review_scoped(payload, doc_mode, duplicate_mode, dependency_mode, comment_mode)
248
282
 
249
283
 
250
284
  def _dependency_part(before, after, ecosystem):
@@ -260,9 +294,10 @@ def _dependency_part(before, after, ecosystem):
260
294
  return f"{dependency_notice.PREFIX}dependency check skipped: {exc}"
261
295
 
262
296
 
263
- def _edit_review_scoped(payload, doc_mode, duplicate_mode, dependency_mode):
297
+ def _edit_review_scoped(payload, doc_mode, duplicate_mode, dependency_mode, comment_mode="off"):
264
298
  """`_edit_review` inside one `code_graph.pending_scope`, so the pending-changes scan runs once per review."""
265
- doc_findings, duplicate_findings, failures, dependency_parts = [], [], [], []
299
+ doc_findings, scope_findings, duplicate_findings, failures, dependency_parts = [], [], [], [], []
300
+ comment_findings = []
266
301
  for path, before, after in edit_preview.preview(payload.get("tool_name"), payload.get("tool_input"), payload.get("cwd")):
267
302
  ecosystem = dependency_notice.ecosystem_of(path)
268
303
  if dependency_mode != "off" and ecosystem:
@@ -271,23 +306,36 @@ def _edit_review_scoped(payload, doc_mode, duplicate_mode, dependency_mode):
271
306
  if not doc_check.supported(path):
272
307
  continue
273
308
  root = _project_of(path)
274
- rel = os.path.relpath(path, root).replace(os.sep, "/") if root else os.path.basename(path)
309
+ rel = os.path.relpath(os.path.realpath(path), os.path.realpath(root)).replace(os.sep, "/") if root else os.path.basename(path)
275
310
  edited = doc_check.written(path, before, after)
276
311
  profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile")) if root else None
277
312
  if doc_mode != "off" and root and index_profile.kind(rel, profile) == "code":
278
313
  doc_findings += [(root, rel, item) for item in doc_check.review(path, before, after, edited)]
314
+ if comment_mode != "off" and root and index_profile.kind(rel, profile) == "code":
315
+ comment_findings += [(rel, item) for item in comment_check.review(path, before, after, edited)]
316
+ if doc_mode != "off" and root:
317
+ try:
318
+ scope_findings += doc_scope.on_edit(root, rel, before, edited["all"])
319
+ except (OSError, UnicodeDecodeError) as exc:
320
+ failures.append(f"Smart Tool docs scope check skipped: {exc}")
279
321
  if duplicate_mode != "off" and root and edited["touched"]:
280
322
  try:
281
323
  duplicate_findings += [(rel, item) for item in duplicates.on_write(root, path, before, after, edited)]
282
324
  except (ValueError, RuntimeError) as exc:
283
325
  failures.append(f"Smart Tool duplicates check skipped: {exc}")
284
326
  parts = ([_doc_lines(doc_findings)] if doc_findings else []) + \
327
+ ([_comment_lines(comment_findings)] if comment_findings else []) + \
328
+ ([_scope_lines(scope_findings)] if scope_findings else []) + \
285
329
  ([_duplicate_lines(duplicate_findings)] if duplicate_findings else []) + failures + dependency_parts
286
330
  if not parts:
287
331
  return {}
288
332
  message = " ".join(parts)
289
- if doc_mode == "require" and any(item["issue"] == "missing" for _root, _rel, item in doc_findings):
290
- return deny(message + " Redo the edit with the docstring.")
333
+ missing_docs = doc_mode == "require" and any(item["issue"] == "missing" for _root, _rel, item in doc_findings)
334
+ wrong_comments = comment_mode == "require" and bool(comment_findings)
335
+ if missing_docs or wrong_comments:
336
+ fixes = " and ".join(text for text, needed in (("the docstring", missing_docs),
337
+ ("the comments fixed", wrong_comments)) if needed)
338
+ return deny(message + f" Redo the edit with {fixes}.")
291
339
  return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": message}}
292
340
 
293
341
 
@@ -299,11 +347,11 @@ def decide(payload, client, web_route, jobs):
299
347
  subagent whose tool list has no Smart Tool MCP tool: it has nothing to switch to."""
300
348
  cfg = config.load_config()
301
349
  if isinstance(payload, dict) and payload.get("tool_name") in EDIT_TOOLS:
302
- doc_mode, duplicate_mode, dependency_mode = (config.doc_mode(cfg), config.duplicate_mode(cfg),
303
- config.dependency_mode(cfg))
304
- if doc_mode == "off" and duplicate_mode == "off" and dependency_mode == "off":
350
+ doc_mode, duplicate_mode, dependency_mode, comment_mode = (
351
+ config.doc_mode(cfg), config.duplicate_mode(cfg), config.dependency_mode(cfg), config.comment_mode(cfg))
352
+ if "off" == doc_mode == duplicate_mode == dependency_mode == comment_mode:
305
353
  return {}
306
- return _edit_review(payload, doc_mode, duplicate_mode, dependency_mode)
354
+ return _edit_review(payload, doc_mode, duplicate_mode, dependency_mode, comment_mode)
307
355
  if isinstance(payload, dict) and str(payload.get("tool_name")).startswith(f"mcp__{SMART_TOOL_SERVER}__"):
308
356
  if payload["tool_name"] == SMART_SEARCH_TOOL:
309
357
  router.CLIENT.set(client)
package/install.py CHANGED
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env python3
2
2
  import argparse
3
3
  import filecmp
4
+ import hashlib
4
5
  import json
5
6
  import os
6
7
  import re
@@ -24,6 +25,10 @@ HOOK_SCRIPTS = ("pretool_router.py", "session_audit.py")
24
25
  STARTUP_SCRIPT = Path(os.environ.get("APPDATA", str(Path.home() / "AppData" / "Roaming"))) / "Microsoft" / "Windows" / \
25
26
  "Start Menu" / "Programs" / "Startup" / "SmartTool-Tray.vbs"
26
27
  MANIFEST = ".install-manifest.json"
28
+ DEPENDENCY_INPUTS = ("requirements.txt", "install_runtime.py", "node_locator.py", "web_adapters/node/package.json",
29
+ "web_adapters/node/package-lock.json", "web_adapters/browser/requirements.txt",
30
+ "web_adapters/browser/fetch_camoufox.py", "web_adapters/browser/ranged_download.py")
31
+ DEPENDENCY_STAMP = ".dependencies.sha256"
27
32
  REGISTRY = Path(paths.DATA_DIR) / "daemon.json"
28
33
  BLOCKED = {"__pycache__", ".token-guard", ".git", ".pytest_cache", ".data", ".artifacts", ".claude", ".vscode",
29
34
  ".impeccable", "tests", "sessions", "results", "dist", "node_modules", ".node-runtime", ".venv",
@@ -280,6 +285,50 @@ def restore_packages(python, frozen, backup):
280
285
  str(backup / "requirements.frozen.txt")], check=True)
281
286
 
282
287
 
288
+ def dependency_digest(root):
289
+ """SHA-256 over the DEPENDENCY_INPUTS under root: the files that decide what pip and install_runtime.py install."""
290
+ digest = hashlib.sha256()
291
+ for rel in DEPENDENCY_INPUTS:
292
+ digest.update(rel.encode("utf-8") + b"\0" + (root / rel).read_bytes() + b"\0")
293
+ return digest.hexdigest()
294
+
295
+
296
+ def runtime_complete(target, python):
297
+ """`install_runtime.py --check` of target: Node, parsers, browser packages and browsers all present. It only
298
+ reads, so it runs while the daemon is still up."""
299
+ return subprocess.run([str(python), str(target / "install_runtime.py"), "--check"], cwd=target,
300
+ capture_output=True, text=True, timeout=120).returncode == 0
301
+
302
+
303
+ def dependencies_current(target, python):
304
+ """True when the last update that completed in target ran the dependency step with the inputs this package
305
+ ships and the web runtime is still complete, so pip and install_runtime.py would change nothing. Running them
306
+ anyway keeps the daemon down for about 48 s, longer than an MCP client keeps reconnecting (Claude Code gives up
307
+ after 5 attempts, about 15 s)."""
308
+ stamp = target / DEPENDENCY_STAMP
309
+ return (python.is_file() and stamp.is_file()
310
+ and stamp.read_text(encoding="utf-8").strip() == dependency_digest(SOURCE)
311
+ and runtime_complete(target, python))
312
+
313
+
314
+ def refresh_camoufox(target):
315
+ """Runs target's `fetch_camoufox.py` while the daemon is still up, so a newer browser build for the same library
316
+ version arrives on every update. Camoufox installs each build in its own folder and switches the active one only
317
+ after the download checks out, so the running browser keeps its files; with no newer build it only looks up the
318
+ releases."""
319
+ browser = target / "web_adapters" / "browser"
320
+ subprocess.run([str(browser / ".venv" / "Scripts" / "python.exe"), str(browser / "fetch_camoufox.py")], check=True)
321
+
322
+
323
+ def prune_camoufox(target):
324
+ """Runs target's `prune_camoufox.py` after a verified update, so the Camoufox builds older than the active one leave
325
+ the user's cache. The update is already complete, so a failure is reported, not rolled back."""
326
+ browser = target / "web_adapters" / "browser"
327
+ result = subprocess.run([str(browser / ".venv" / "Scripts" / "python.exe"), str(browser / "prune_camoufox.py")])
328
+ if result.returncode:
329
+ print(f"Old Camoufox builds not pruned: prune_camoufox.py exited {result.returncode}.", file=sys.stderr)
330
+
331
+
283
332
  def install_dependencies(target, python):
284
333
  if not python.exists():
285
334
  venv.create(python.parent.parent, with_pip=True)
@@ -411,6 +460,9 @@ def prune_backups(target):
411
460
 
412
461
  def _update(args, target, files, existed, python, pythonw):
413
462
  """Replaces the installed files, dependencies and daemon, restoring the previous version on any failure."""
463
+ run_deps = not args.skip_deps and not dependencies_current(target, python)
464
+ if not args.skip_deps and not run_deps:
465
+ refresh_camoufox(target)
414
466
  stop_processes(target)
415
467
  if not args.no_start:
416
468
  wait_port_free(target)
@@ -421,10 +473,12 @@ def _update(args, target, files, existed, python, pythonw):
421
473
  copy_files(target, files, backup, changed, removed)
422
474
  clear_bytecode(target)
423
475
  print(f"Files changed: {len(changed)}; removed as obsolete: {len(removed)}")
424
- if not args.skip_deps:
476
+ if run_deps:
425
477
  frozen = freeze(python)
426
478
  deps_touched = True
427
479
  install_dependencies(target, python)
480
+ elif not args.skip_deps:
481
+ print("Dependencies unchanged since the last update; pip and install_runtime.py skipped.")
428
482
  if not args.no_start:
429
483
  mark_updating(False)
430
484
  start(target, python, pythonw)
@@ -448,7 +502,11 @@ def _update(args, target, files, existed, python, pythonw):
448
502
  raise SystemExit(1)
449
503
  shutil.rmtree(backup, ignore_errors=True)
450
504
  raise SystemExit(1)
505
+ if run_deps:
506
+ (target / DEPENDENCY_STAMP).write_text(dependency_digest(SOURCE), encoding="utf-8")
451
507
  shutil.rmtree(backup)
508
+ if not args.skip_deps and not args.no_start:
509
+ prune_camoufox(target)
452
510
 
453
511
 
454
512
  if __name__ == "__main__":
@@ -239,10 +239,39 @@ def _run_once(args, cwd, env, flags, label, idle_s, stream):
239
239
  raise RuntimeError(f"{label} failed (exit {process.returncode}): {tail[-1] if tail else 'no output'}")
240
240
 
241
241
 
242
+ def _lock_digest():
243
+ return hashlib.sha256((NODE_DIR / "package-lock.json").read_bytes()).hexdigest()
244
+
245
+
246
+ def _lock_stamp():
247
+ """Written after `npm ci` succeeds; `npm ci` deletes node_modules first, so a failed run leaves no stamp."""
248
+ return NODE_DIR / "node_modules" / ".smart-tool-lock.sha256"
249
+
250
+
251
+ def _node_packages_current():
252
+ """node_modules was installed from the package-lock.json shipped now and still holds every entry point. npm's own
253
+ hidden lockfile is not compared because npm ignores it whenever another tool touched the tree."""
254
+ try:
255
+ stamped = _lock_stamp().read_text(encoding="utf-8").strip()
256
+ except OSError:
257
+ return False
258
+ return stamped == _lock_digest() and all(path.is_file() for path in (
259
+ OPEN_WEBSEARCH_CLI, TYPESCRIPT_PARSER, JAVA_PARSER, ANGULAR_PARSER, PLAYWRIGHT_MCP_CLI))
260
+
261
+
262
+ def _install_node_packages(npm):
263
+ if _node_packages_current():
264
+ return
265
+ _run([npm, "ci", "--omit=dev", "--no-audit", "--no-fund"], cwd=NODE_DIR,
266
+ label="Web adapters and code parser via npm", idle_s=300)
267
+ _lock_stamp().write_text(_lock_digest(), encoding="utf-8")
268
+
269
+
242
270
  def _check():
243
271
  node, _npm = _node_commands()
244
272
  status = {
245
273
  "node": bool(node),
274
+ "node_packages": bool(node and _node_packages_current()),
246
275
  "open_websearch": bool(node and OPEN_WEBSEARCH_CLI.is_file()),
247
276
  "typescript_parser": bool(node and TYPESCRIPT_PARSER.is_file()),
248
277
  "java_parser":bool(node and JAVA_PARSER.is_file()),
@@ -318,10 +347,7 @@ def install(reuse_browser_runtime=None):
318
347
  if not node or not npm:
319
348
  _install_node()
320
349
  node, npm = _node_commands()
321
- if not all(path.is_file() for path in (OPEN_WEBSEARCH_CLI, TYPESCRIPT_PARSER, JAVA_PARSER, ANGULAR_PARSER,
322
- PLAYWRIGHT_MCP_CLI)):
323
- _run([npm, "ci", "--omit=dev", "--no-audit", "--no-fund"], cwd=NODE_DIR,
324
- label="Web adapters and code parser via npm", idle_s=300)
350
+ _install_node_packages(npm)
325
351
  if reuse_browser_runtime:
326
352
  existing = Path(reuse_browser_runtime).expanduser().resolve()
327
353
  if not (existing / "Scripts" / "python.exe").is_file():
package/layers.py ADDED
@@ -0,0 +1,237 @@
1
+ """Declared layers of a project: an ordered list from the highest layer (entry points) to the lowest (data access), each
2
+ defined by path globs and annotations, saved in the project at .smart-tool/layers.json once the agent confirms it.
3
+
4
+ The model follows the layer rules of validated tools: import-linter's layers contract (an ordered list, higher layers
5
+ may depend on lower ones), ArchUnit's layeredArchitecture (a layer is defined by a package pattern) and
6
+ dependency-cruiser (paths relative to the project root, forward slashes). A file belongs to the first layer, in the
7
+ declared order, whose path glob matches it or whose annotation starts one of its lines. The suggestion reads folder
8
+ names and annotations only; nothing is decided without the agent confirming it."""
9
+ import fnmatch
10
+ import json
11
+ import os
12
+ import posixpath
13
+ import re
14
+ from collections import Counter
15
+
16
+ import atomic_io
17
+ import code_graph
18
+ import index_profile
19
+ import index_scope
20
+
21
+ RULE_PATH = os.path.join(".smart-tool", "layers.json")
22
+ MAX_LAYERS = 12
23
+ MAX_PATTERNS = 200
24
+ MAX_UNASSIGNED = 30
25
+ _NAME = re.compile(r"[A-Za-z][\w-]{0,39}")
26
+ CONVENTIONS = (
27
+ ("entry", {"api", "apis", "cmd", "cli", "commands", "controller", "controllers", "endpoint", "endpoints",
28
+ "graphql", "handler", "handlers", "http", "resolvers", "rest", "route", "router", "routers", "routes",
29
+ "views", "web"},
30
+ ("@RestController", "@Controller", "@RequestMapping", "@GetMapping", "@PostMapping", "@PutMapping",
31
+ "@DeleteMapping", "@PatchMapping", "@Path", "@app.route", "@bp.route", "@blueprint.route", "@app.get",
32
+ "@app.post", "@app.put", "@app.delete", "@app.patch", "@router.get", "@router.post", "@router.put",
33
+ "@router.delete", "@router.patch")),
34
+ ("service", {"application", "business", "interactors", "service", "services", "usecase", "usecases",
35
+ "use_cases"},
36
+ ("@Service", "@Injectable")),
37
+ ("domain", {"core", "domain", "entities", "entity", "model", "models"},
38
+ ("@Entity", "@Embeddable")),
39
+ ("data", {"dao", "daos", "database", "db", "migrations", "persistence", "repo", "repos", "repositories",
40
+ "repository", "sql", "storage", "store"},
41
+ ("@Repository", "@Mapper", "@Dao")),
42
+ )
43
+
44
+
45
+ class Rule:
46
+ """A validated layer rule: assign() gives the layer of a file from its path and text."""
47
+
48
+ def __init__(self, layers):
49
+ self.layers = layers
50
+ self._paths = [[re.compile(fnmatch.translate(p)) for p in layer["paths"]] for layer in layers]
51
+ self._annotations = [re.compile(r"^[ \t]*(?:" + "|".join(re.escape(a) for a in layer["annotations"])
52
+ + r")(?![\w.])", re.M) if layer["annotations"] else None
53
+ for layer in layers]
54
+
55
+ def assign(self, path, text=None):
56
+ """Name of the first layer whose glob matches path or whose annotation starts a line of text; None if none.
57
+
58
+ Parameters: path (str) project-relative with forward slashes; text (str or None) the file's source.
59
+ Returns: str or None.
60
+ """
61
+ for layer, globs, annotation in zip(self.layers, self._paths, self._annotations):
62
+ if any(g.match(path) for g in globs) or (text and annotation and annotation.search(text)):
63
+ return layer["name"]
64
+ return None
65
+
66
+
67
+ def validate(layers):
68
+ """The layer list as saved, or ValueError naming the first problem.
69
+
70
+ Parameters: layers (list of {'name', 'paths', 'annotations'}) ordered from the highest layer to the lowest.
71
+ Returns: list of {'name': str, 'paths': [str], 'annotations': [str]}.
72
+ """
73
+ if not isinstance(layers, list) or not 1 <= len(layers) <= MAX_LAYERS:
74
+ raise ValueError(f"layers must be a list of 1 to {MAX_LAYERS} layers, highest first.")
75
+ clean, names = [], set()
76
+ for index, layer in enumerate(layers):
77
+ if not isinstance(layer, dict) or set(layer) - {"name", "paths", "annotations"}:
78
+ raise ValueError(f"layers[{index}] must be an object with name, paths and annotations only.")
79
+ name = layer.get("name")
80
+ if not isinstance(name, str) or not _NAME.fullmatch(name) or name.casefold() in names:
81
+ raise ValueError(f"layers[{index}].name must be a unique word (letters, digits, - or _, up to 40).")
82
+ names.add(name.casefold())
83
+ paths, annotations = layer.get("paths", []), layer.get("annotations", [])
84
+ if not isinstance(paths, list) or not all(isinstance(p, str) and p.strip() for p in paths) \
85
+ or len(paths) > MAX_PATTERNS:
86
+ raise ValueError(f"layers[{index}].paths must be a list of up to {MAX_PATTERNS} path globs.")
87
+ for pattern in paths:
88
+ parts = pattern.replace("\\", "/").split("/")
89
+ if pattern.startswith(("/", "\\")) or re.match(r"[A-Za-z]:", pattern) or ".." in parts:
90
+ raise ValueError(f"layers[{index}].paths: '{pattern}' must be relative to the project root.")
91
+ if not isinstance(annotations, list) or not all(isinstance(a, str) and re.fullmatch(r"@[\w.]+", a)
92
+ for a in annotations):
93
+ raise ValueError(f"layers[{index}].annotations must be a list like ['@RestController', '@app.route'].")
94
+ if not paths and not annotations:
95
+ raise ValueError(f"layers[{index}] ('{name}') needs at least one path glob or annotation.")
96
+ clean.append({"name": name, "paths": [p.replace("\\", "/") for p in paths], "annotations": annotations})
97
+ return clean
98
+
99
+
100
+ def load(root):
101
+ """The confirmed rule of the project, or None when it has none; a file that does not validate raises ValueError.
102
+
103
+ Parameters: root (str) project folder.
104
+ Returns: Rule or None.
105
+ """
106
+ path = os.path.join(root, RULE_PATH)
107
+ try:
108
+ with open(path, encoding="utf-8") as stream:
109
+ data = json.load(stream)
110
+ except FileNotFoundError:
111
+ return None
112
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
113
+ raise ValueError(f"{path} could not be read: {exc}") from None
114
+ if not isinstance(data, dict) or set(data) != {"layers"}:
115
+ raise ValueError(f"{path} must be an object with a single 'layers' list.")
116
+ try:
117
+ return Rule(validate(data["layers"]))
118
+ except ValueError as exc:
119
+ raise ValueError(f"{path}: {exc}") from None
120
+
121
+
122
+ def save(root, layers):
123
+ """Validate and write the rule to .smart-tool/layers.json in the project.
124
+
125
+ Parameters: root (str) project folder; layers (list) as validate() takes it.
126
+ Returns: Rule.
127
+ """
128
+ clean = validate(layers)
129
+ path = os.path.join(root, RULE_PATH)
130
+ os.makedirs(os.path.dirname(path), exist_ok=True)
131
+ atomic_io.write_text(path, json.dumps({"layers": clean}, indent=2, ensure_ascii=False) + "\n")
132
+ return Rule(clean)
133
+
134
+
135
+ def suggest(paths, read):
136
+ """Layer rule proposed from folder names and annotations, in the CONVENTIONS order.
137
+
138
+ The deepest folder named after a convention decides a file's layer (internal/service/model/x.go is domain); an
139
+ annotation of a higher layer wins over the folder. Folders become globs (`internal/handler/**`); annotations that
140
+ matched a file are kept on their layer.
141
+
142
+ Parameters: paths (iterable of str) code files, project-relative; read (callable path -> str or None) their text.
143
+ Returns: list of layers as validate() takes them (only layers that matched something).
144
+ """
145
+ globs, annotations = {name: set() for name, _f, _a in CONVENTIONS}, {name: set() for name, _f, _a in CONVENTIONS}
146
+ for path in paths:
147
+ text = read(path) or ""
148
+ hit = next(((name, a) for name, _folders, names in CONVENTIONS for a in names
149
+ if re.search(r"^[ \t]*" + re.escape(a) + r"(?![\w.])", text, re.M)), None)
150
+ if hit:
151
+ annotations[hit[0]].add(hit[1])
152
+ continue
153
+ parts = path.split("/")[:-1]
154
+ for depth in range(len(parts), 0, -1):
155
+ layer = next((name for name, folders, _a in CONVENTIONS if parts[depth - 1].lower() in folders), None)
156
+ if layer:
157
+ globs[layer].add("/".join(parts[:depth]) + "/**")
158
+ break
159
+ return [{"name": name, "paths": sorted(globs[name]), "annotations": sorted(annotations[name])}
160
+ for name, _f, _a in CONVENTIONS if globs[name] or annotations[name]]
161
+
162
+
163
+ def summary(rule, graph, read):
164
+ """How a rule splits the code graph: files and symbols per layer, calls between layers (direction 'down' follows
165
+ the declared order, 'up' goes against it) and the folders no layer covers.
166
+
167
+ Parameters: rule (Rule); graph (dict) code graph with 'symbols' and 'calls'; read (callable path -> str or None).
168
+ Returns: dict with 'layers', 'calls_between', 'unassigned' and 'truncated'.
169
+ """
170
+ order = {layer["name"]: index for index, layer in enumerate(rule.layers)}
171
+ paths = sorted({s["path"] for s in graph.get("symbols") or []})
172
+ layer_of = {path: rule.assign(path, read(path) if any(l["annotations"] for l in rule.layers) else None)
173
+ for path in paths}
174
+ symbol_layer = {s["id"]: layer_of[s["path"]] for s in graph.get("symbols") or []}
175
+ files, symbols = Counter(layer_of.values()), Counter(symbol_layer.values())
176
+ between = Counter()
177
+ for call in graph.get("calls") or []:
178
+ source, target = symbol_layer.get(call["source"]), symbol_layer.get(call["target"])
179
+ if source and target and source != target:
180
+ between[(source, target)] += call.get("count", 1)
181
+ unassigned = Counter(posixpath.dirname(p) or "." for p, layer in layer_of.items() if layer is None)
182
+ return {"layers": [{**layer, "files": files[layer["name"]], "symbols": symbols[layer["name"]]}
183
+ for layer in rule.layers],
184
+ "calls_between": [{"from": a, "to": b, "calls": n, "direction": "down" if order[a] < order[b] else "up"}
185
+ for (a, b), n in sorted(between.items(), key=lambda item: (order[item[0][0]],
186
+ order[item[0][1]]))],
187
+ "unassigned": [{"folder": folder, "files": n} for folder, n in unassigned.most_common(MAX_UNASSIGNED)],
188
+ "unassigned_files": files[None], "truncated": bool(graph.get("truncated"))}
189
+
190
+
191
+ def report(root, layers=None, confirm=False, view_id=None):
192
+ """The layers action: the saved rule, a suggestion, a preview of a proposed rule, or the confirmed save, each with
193
+ the summary of how it splits the project's code (tests left out).
194
+
195
+ Parameters: root (str) project folder; layers (list or None) proposed rule; confirm (bool) save the proposed rule;
196
+ view_id (str or None) index view to read.
197
+ Returns: dict with 'saved', 'rule_path', 'layers' (the rule with per-layer counts), 'calls_between', 'unassigned'
198
+ and 'guidance'.
199
+ """
200
+ if type(confirm) is not bool:
201
+ raise ValueError("confirm must be true or false.")
202
+ if confirm and layers is None:
203
+ raise ValueError("confirm=true saves the rule passed in layers; pass layers.")
204
+ graph = code_graph.build_current(root, view_id, shared=True)
205
+ profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile"))
206
+ symbols = [s for s in graph.get("symbols") or [] if index_profile.kind(s["path"], profile) == "code"]
207
+ code = {**graph, "symbols": symbols}
208
+ texts = {}
209
+
210
+ def read(path):
211
+ if path not in texts:
212
+ try:
213
+ with open(os.path.join(root, path), encoding="utf-8") as stream:
214
+ texts[path] = stream.read()
215
+ except (OSError, UnicodeDecodeError):
216
+ texts[path] = None
217
+ return texts[path]
218
+
219
+ path = os.path.join(root, RULE_PATH)
220
+ if layers is not None:
221
+ rule = save(root, layers) if confirm else Rule(validate(layers))
222
+ guidance = ("Saved; documentation and the graph use this rule from now on." if confirm else
223
+ "Preview only: call again with the same layers and confirm=true to save the rule in the project.")
224
+ return {"saved": confirm, "rule_path": path, **summary(rule, code, read), "guidance": guidance}
225
+ rule = load(root)
226
+ if rule:
227
+ return {"saved": True, "rule_path": path, **summary(rule, code, read),
228
+ "guidance": "To change it, pass the new layers (preview), then the same layers with confirm=true."}
229
+ proposed = suggest(sorted({s["path"] for s in symbols}), read)
230
+ if not proposed:
231
+ return {"saved": False, "rule_path": path, "layers": [], "calls_between": [], "unassigned": [],
232
+ "truncated": bool(graph.get("truncated")),
233
+ "guidance": "No folder or annotation follows a known layer convention; declare the layers yourself "
234
+ "(name, paths, annotations, highest first) and confirm them."}
235
+ return {"saved": False, "rule_path": path, **summary(Rule(proposed), code, read),
236
+ "guidance": "Suggested from folder names and annotations, not saved: review the layers (rename, merge, move "
237
+ "folders from 'unassigned'), then pass them with confirm=true."}