@allansantos-dev/smart-tool 0.9.2 → 0.9.4

package/code_graph.py

@@ -2,6 +2,7 @@
 import ast
 import collections
 import copy
+import gzip
 import contextvars
 import hashlib
 import json
@@ -14,12 +15,15 @@ from pathlib import Path
 
 import indexer
 import index_inventory
+import index_scope
 import project_identity
 import web_search_adapters
 import web_document_graph
 import document_text
 
 VERSION = 2
+SOURCE_EXTENSIONS = ('.py','.java','.js','.jsx','.ts','.tsx','.mjs','.cjs','.mts','.cts','.json','.html','.htm','.css','.scss','.sass','.less','.md','.markdown')
+MAX_OVERLAY_BYTES = 1024 * 1024
 MAX_FILES = 3000
 MAX_TEXT = 24 * 1024 * 1024
 MAX_SYMBOLS = 8000
@@ -72,7 +76,7 @@ def _snapshot(path):
                       'chunks':chunks,'lines':line_count or 0,'group':posixpath.dirname(file_path) or '(root)',
                       'location_kind':document_text.location_kind(file_path),'format':posixpath.splitext(file_path)[1].lower().lstrip('.') or 'text'}
             files.append(record)
-            if not file_path.lower().endswith(('.py','.java','.js','.jsx','.ts','.tsx','.mjs','.cjs','.mts','.cts','.json','.html','.htm','.css','.scss','.sass','.less','.md','.markdown')):
+            if not file_path.lower().endswith(SOURCE_EXTENSIONS):
                 continue
             rows = conn.execute('SELECT start_line,end_line,text FROM chunks WHERE path=? ORDER BY start_line,id', (original,)).fetchall()
             text, error = reconstruct(rows)
@@ -228,19 +232,34 @@ def _python_graph(sources):
             'diagnostics':diagnostics,'parsed':list(trees),'truncated':len(symbols)>=MAX_SYMBOLS or len(dependencies)>MAX_EDGES}
 
 
+NODE_HEAP_MB = (1024, 4096)
+
+
+def _run_analyzer(script, payload, failure):
+    """Runs a Node analyzer, retrying once with a larger heap when it runs out of memory (634 TypeScript files, 2.9 MB,
+    needed more than the former fixed 512 MB)."""
+    for heap in NODE_HEAP_MB:
+        process=subprocess.run([web_search_adapters.NODE_EXECUTABLE,f'--max-old-space-size={heap}',str(Path(__file__).with_name(script))],
+            input=payload,capture_output=True,text=True,encoding='utf-8',timeout=120,
+            creationflags=getattr(subprocess,'CREATE_NO_WINDOW',0))
+        if process.returncode==0:
+            return json.loads(process.stdout)
+        if 'heap out of memory' not in (process.stderr or '') or heap==NODE_HEAP_MB[-1]:
+            break
+    detail=' (out of memory)' if 'heap out of memory' in (process.stderr or '') else ''
+    raise RuntimeError(failure+detail)
+
+
 def _javascript_graph(sources, all_paths=None):
     extensions=('.js','.jsx','.ts','.tsx','.mjs','.cjs','.mts','.cts')
     relevant={path:text for path,text in sources.items() if path.endswith(extensions+('.json','.html','.htm'))}
     if not any(path.endswith(extensions) for path in relevant):
         return {}
     try:
-        process=subprocess.run([web_search_adapters.NODE_EXECUTABLE,'--max-old-space-size=512',str(Path(__file__).with_name('code_graph_js.cjs'))],
-            input=json.dumps({'files':[{'path':path,'text':text} for path,text in relevant.items()],'paths':list(all_paths or sources)},ensure_ascii=False),
-            capture_output=True,text=True,encoding='utf-8',timeout=40,
-            creationflags=getattr(subprocess,'CREATE_NO_WINDOW',0))
-        if process.returncode:
-            raise RuntimeError('The TypeScript analyzer did not finish. Check the local code-analysis runtime.')
-        return json.loads(process.stdout)
+        return _run_analyzer('code_graph_js.cjs',
+                             json.dumps({'files':[{'path':path,'text':text} for path,text in relevant.items()],
+                                         'paths':list(all_paths or sources)},ensure_ascii=False),
+                             'The TypeScript analyzer did not finish. Check the local code-analysis runtime.')
     except (OSError,subprocess.TimeoutExpired,ValueError,RuntimeError) as exc:
         return {'diagnostics':[{'path':'JavaScript/TypeScript','reason':str(exc)[:250]}],'parsed':[],'retryable':True}
 
@@ -249,17 +268,17 @@ def _java_graph(sources):
     files=[{'path':path,'text':text} for path,text in sources.items() if path.lower().endswith('.java')]
     if not files:return {}
     try:
-        result=subprocess.run([web_search_adapters.NODE_EXECUTABLE,'--max-old-space-size=512',str(Path(__file__).with_name('code_graph_java.mjs'))],
-            input=json.dumps({'files':files},ensure_ascii=False),capture_output=True,text=True,encoding='utf-8',timeout=40,
-            creationflags=getattr(subprocess,'CREATE_NO_WINDOW',0))
-        if result.returncode:raise RuntimeError('The Java analyzer did not finish. Check the local runtime.')
-        return json.loads(result.stdout)
+        return _run_analyzer('code_graph_java.mjs',json.dumps({'files':files},ensure_ascii=False),
+                             'The Java analyzer did not finish. Check the local runtime.')
     except (OSError,ValueError,RuntimeError,subprocess.TimeoutExpired) as exc:
         return {'diagnostics':[{'path':'Java','reason':str(exc)[:250]}],'parsed':[],'retryable':True}
 
 
 def _analyze(path):
-    files,sources,diagnostics,truncated=_snapshot(path)
+    return _analyze_sources(*_snapshot(path))
+
+
+def _analyze_sources(files,sources,diagnostics,truncated):
     merged={'symbols':[],'dependencies':[],'calls':[],'unresolved':[],'diagnostics':diagnostics,'parsed':[]}
     retryable=False
     for output in (_python_graph(sources),_javascript_graph(sources,[f['path'] for f in files]),_java_graph(sources),web_document_graph.analyze(sources,[f['path'] for f in files])):
@@ -322,6 +341,41 @@ def _by_file(data):
     return {'symbols':by_file,'parsed':parsed,'note':note}
 
 
+def _disk_path(view_path):
+    path=indexer.graph_cache_path(view_path)
+    return os.path.dirname(path),path
+
+
+def _disk_load(key):
+    """Analysis saved for exactly this index state and analyzer version, or None. A damaged file is a miss: the
+    caller analyzes again and overwrites it."""
+    _folder,path=_disk_path(key[0])
+    try:
+        with gzip.open(path,'rt',encoding='utf-8') as stream:
+            saved=json.load(stream)
+    except (OSError,EOFError,ValueError):
+        return None
+    return saved.get('graph') if saved.get('key')==[key[1],key[2],key[3]] else None
+
+
+def _disk_save(key,data):
+    """Writes the analysis next to the index (atomic replace) and removes caches of views that no longer exist.
+    Returns the error text when it could not be written, so the caller can report it."""
+    folder,path=_disk_path(key[0])
+    try:
+        os.makedirs(folder,exist_ok=True)
+        temporary=f'{path}.{os.getpid()}.{threading.get_ident()}.tmp'
+        with gzip.open(temporary,'wt',encoding='utf-8',compresslevel=5) as stream:
+            json.dump({'key':[key[1],key[2],key[3]],'graph':data},stream,ensure_ascii=False)
+        os.replace(temporary,path)
+        for name in os.listdir(folder):
+            if name.endswith('.json.gz') and not os.path.isfile(os.path.join(os.path.dirname(folder),name[:-8]+'.sqlite3')):
+                os.remove(os.path.join(folder,name))
+    except OSError as exc:
+        return f'Graph cache not saved ({type(exc).__name__}: {exc}); the next restart analyzes again.'[:300]
+    return None
+
+
 def cached_symbols(root):
     path=indexer.existing_db_path(root)
     if not path:
@@ -331,6 +385,13 @@ def cached_symbols(root):
         data=_CACHE.get(key)
         if data is not None:
             _CACHE.move_to_end(key)
+    if data is None:
+        data=_disk_load(key)
+        if data is not None:
+            with _LOCK:
+                _CACHE[key]=data
+                while len(_CACHE)>3:_CACHE.popitem(last=False)
+    with _LOCK:
         state=_WARM_STATE.get(root)
         if data is None and state and state['key']==key and (state['result'] or time.time()-state['at']<WARM_RETRY_S):
             return state['result'],state['note']
@@ -344,6 +405,12 @@ def cached_symbols(root):
     return None,None
 
 
+def warm(root):
+    """Starts the analysis of the project's current index in the background unless memory or disk already has it, so
+    the next edit hook or search finds the graph ready (called when an indexing job ends)."""
+    cached_symbols(root)
+
+
 def _warm(root,key):
     result,note=None,None
     try:
@@ -371,6 +438,13 @@ def build(root,view_id=None,storage_id=None,file_path=None,background=False):
         cached=_CACHE.get(key)
         if cached:_CACHE.move_to_end(key)
     was_cached=cached is not None
+    save_note=None
+    if cached is None:
+        cached=_disk_load(key)
+        if cached is not None:
+            with _LOCK:
+                _CACHE[key]=cached
+                while len(_CACHE)>3:_CACHE.popitem(last=False)
     if cached is None:
         slots=_WARM_SLOT if background else _ANALYSIS_SLOTS
         if not slots.acquire(timeout=None if background else 3):
@@ -384,7 +458,9 @@ def build(root,view_id=None,storage_id=None,file_path=None,background=False):
             with _LOCK:
                 _CACHE[key]=cached
                 while len(_CACHE)>3:_CACHE.popitem(last=False)
+            save_note=_disk_save(key,cached)
     data=copy.deepcopy(cached)
+    if save_note:data['diagnostics']=[*data.get('diagnostics',[]),{'path':'','reason':save_note}]
     # Só compara metadados do diretório de trabalho quando a visão é a atual.
     for file in data['files']:
         file['status']='stored'
@@ -401,3 +477,113 @@ def build(root,view_id=None,storage_id=None,file_path=None,background=False):
                 limits={'files':MAX_FILES,'symbols':MAX_SYMBOLS,'edges':MAX_EDGES,'display_nodes_default':120},
                 languages=['Java','Angular','Python','JavaScript','TypeScript','JSX','TSX','HTML','CSS','Markdown'],cache_hit=was_cached)
     return _focus(data,file_path) if file_path else data
+
+
+def working_tree_changes(root):
+    """Project-relative paths changed in the git working tree (staged, unstaged, untracked) -> 'deleted' or
+    'changed'; empty when the folder is not in a git repository."""
+    def git(*args):
+        return subprocess.run(['git',*args],cwd=root,capture_output=True,timeout=30,
+                              creationflags=getattr(subprocess,'CREATE_NO_WINDOW',0))
+    prefix=git('rev-parse','--show-prefix')
+    if prefix.returncode:
+        return {}
+    prefix=prefix.stdout.decode('utf-8','replace').strip()
+    status=git('status','--porcelain=v1','-z','--untracked-files=all','--','.')
+    if status.returncode:
+        raise RuntimeError('git status failed: '+status.stderr.decode('utf-8','replace').strip()[:200])
+    entries=status.stdout.decode('utf-8','replace').split('\0');changes={};i=0
+    while i<len(entries):
+        entry=entries[i];i+=1
+        if len(entry)<4:continue
+        code,path=entry[:2],entry[3:]
+        if 'R' in code or 'C' in code:i+=1
+        if path.startswith(prefix):changes[path[len(prefix):]]='deleted' if 'D' in code else 'changed'
+    return changes
+
+
+def pending_changes(root,view_path):
+    """Files the indexed view does not reflect yet: working-tree changes, indexed files whose size or modification time
+    differs on disk, and files tracked by git inside the index scope that were never indexed (commits made after the
+    last indexing). Path -> 'deleted' or 'changed'."""
+    changes=working_tree_changes(root)
+    conn=indexer._readonly(view_path)
+    try:
+        columns={row[1] for row in conn.execute('PRAGMA table_info(manifest)')}
+        if not {'size','mtime_ns'} <= columns:
+            raise RuntimeError('Index without file sizes and times; reindex the project.')
+        rows=conn.execute('SELECT path,size,mtime_ns FROM manifest').fetchall()
+    finally:
+        conn.close()
+    indexed=set()
+    for original,size,stamp in rows:
+        rel=original.replace('\\','/');indexed.add(rel)
+        if rel in changes:continue
+        try:
+            stat=os.stat(os.path.join(root,rel))
+        except OSError:
+            changes[rel]='deleted';continue
+        if (stat.st_size,stat.st_mtime_ns)!=(size,stamp):changes[rel]='changed'
+    scope=index_scope.load_scope(root)
+    listed=subprocess.run(['git','ls-files','-z'],cwd=root,capture_output=True,timeout=30,
+                          creationflags=getattr(subprocess,'CREATE_NO_WINDOW',0))
+    if scope and listed.returncode==0:
+        for rel in listed.stdout.decode('utf-8','replace').split('\0'):
+            if rel and rel not in indexed and rel not in changes and rel.lower().endswith(SOURCE_EXTENSIONS) \
+                    and index_scope.in_scope(scope,rel) and os.path.isfile(os.path.join(root,rel)):
+                changes[rel]='changed'
+    return changes
+
+
+def build_current(root,view_id=None):
+    """The graph an agent should see while editing: the indexed view plus every file it does not reflect yet (see
+    pending_changes and build_overlay) when that view is the current one; a pinned or older view is returned as
+    indexed."""
+    inventory=index_inventory.inspect(root,view_id)
+    selected=inventory.get('selected') or {}
+    changes=pending_changes(root,selected['path']) if selected.get('current') else {}
+    return build_overlay(root,changes,view_id) if changes else build(root,view_id)
+
+
+def build_overlay(root,changes,view_id=None):
+    """Graph of the indexed view with the given changed files read from the working tree instead of the snapshot
+    (changes: project-relative path -> 'deleted' or any other status), so a caller right after an edit sees new files,
+    new imports and current line numbers without reindexing or embeddings. A deleted file keeps its indexed copy so
+    the files that imported it stay linked to it. Cached per snapshot and file contents."""
+    inventory=index_inventory.inspect(root,view_id)
+    if not inventory['selected']:
+        return {**inventory,'symbols':[],'dependencies':[],'calls':[],'diagnostics':[],'counts':{},'files':[]}
+    path=inventory['selected']['path'];stat=os.stat(path)
+    files,sources,diagnostics,truncated=_snapshot(path)
+    by_path={f['path']:f for f in files};overlaid=[]
+    for rel,status in sorted(changes.items()):
+        full=os.path.join(root,rel)
+        if status=='deleted' or not project_identity.within_root(root,full):
+            continue
+        try:
+            if os.path.getsize(full)>MAX_OVERLAY_BYTES:continue
+            with open(full,encoding='utf-8') as stream:text=stream.read()
+        except (OSError,UnicodeDecodeError):continue
+        by_path.setdefault(rel,{'id':rel,'path':rel,'hash':None,'size':len(text),'mtime_ns':None,'chunks':0,
+                                'lines':text.count('\n')+1,'group':posixpath.dirname(rel) or '(root)',
+                                'location_kind':document_text.location_kind(rel),
+                                'format':posixpath.splitext(rel)[1].lower().lstrip('.') or 'text'})
+        if rel.lower().endswith(SOURCE_EXTENSIONS):
+            sources[rel]=text;overlaid.append((rel,hashlib.sha1(text.encode('utf-8')).hexdigest()))
+    key=(path,stat.st_mtime_ns,stat.st_size,VERSION,'overlay',tuple(overlaid))
+    with _LOCK:
+        cached=_CACHE.get(key)
+    if cached is None:
+        if not _ANALYSIS_SLOTS.acquire(timeout=3):
+            raise RuntimeError('Two map analyses are in progress. Wait for them to finish and retry.')
+        try:
+            cached=_analyze_sources(list(by_path.values()),sources,diagnostics,truncated)
+        finally:
+            _ANALYSIS_SLOTS.release()
+        if not cached['retryable']:
+            with _LOCK:
+                _CACHE[key]=cached
+                while len(_CACHE)>3:_CACHE.popitem(last=False)
+    data=copy.deepcopy(cached)
+    data.update(selected=inventory['selected'],source='indexed_snapshot_with_working_tree',overlaid=[r for r,_h in overlaid])
+    return data

package/code_graph_java.mjs

@@ -33,9 +33,12 @@ for(const unit of units){
  if(cls&&n.name==='primary'){
    const prefix=n.children.primaryPrefix?.[0],prefixText=text(unit,prefix).trim(),suffixes=n.children.primarySuffix||[];let chain=prefixText,fluent=false;
    const newMatch=/^new\s+([\w.$]+)/.exec(prefixText);let constructed=newMatch?resolveType(unit,newMatch[1],cls):null;
+   const link=(type,line)=>{if(type&&type.unit.path!==unit.path&&dependencies.length<MAX_EDGES)dependencies.push({source:unit.path,target:type.unit.path,specifier:type.fqn,line,kind:'java_type',resolution:'resolved'})};
    if(constructed&&calls.length<MAX_EDGES)calls.push({source:(owner||cls.symbol).id,target:constructed.symbol.id,line:n.location.startLine,kind:'construct',resolution:'static'});
+   link(constructed,n.location.startLine);
+   const staticHead=/^([A-Z][\w$]*)\./.exec(prefixText);if(staticHead&&!vars.has(staticHead[1]))link(resolveType(unit,staticHead[1],cls),n.location.startLine);
    for(const suffix of suffixes){const invoke=suffix.children.methodInvocationSuffix?.[0];if(!invoke){chain+=text(unit,suffix);continue}const args=invoke.children.argumentList?.[0],arity=args?(args.children.expression||[]).length:0;const match=/^(?:([\w.$]+)\.)?([\w$]+)$/.exec(chain);let target=null;
-     if(match&&!fluent){const receiver=match[1],name=match[2];let type=null;if(!receiver||receiver==='this')type=cls;else if(receiver==='super')type=resolveType(unit,cls.extends,cls);else if(receiver.startsWith('this.'))type=resolveType(unit,cls.fields.get(receiver.slice(5))||'',cls);else if(vars.has(receiver))type=resolveType(unit,vars.get(receiver)||'',cls);else type=resolveType(unit,receiver,cls);target=lookupMethod(type,name,arity);if(!target&&!receiver){const candidates=unit.imports.filter(i=>i.static&&(i.spec.endsWith('.'+name)||i.spec.endsWith('.*'))).map(i=>lookupMethod(classes.get(i.spec.split('.').slice(0,-1).join('.')),name,arity)).filter(Boolean);if(candidates.length===1)target=candidates[0]}}
+     if(match&&!fluent){const receiver=match[1],name=match[2];let type=null;if(!receiver||receiver==='this')type=cls;else if(receiver==='super')type=resolveType(unit,cls.extends,cls);else if(receiver.startsWith('this.'))type=resolveType(unit,cls.fields.get(receiver.slice(5))||'',cls);else if(vars.has(receiver))type=resolveType(unit,vars.get(receiver)||'',cls);else{type=resolveType(unit,receiver,cls);link(type,invoke.location.startLine)}target=lookupMethod(type,name,arity);if(!target&&!receiver){const candidates=unit.imports.filter(i=>i.static&&(i.spec.endsWith('.'+name)||i.spec.endsWith('.*'))).map(i=>lookupMethod(classes.get(i.spec.split('.').slice(0,-1).join('.')),name,arity)).filter(Boolean);if(candidates.length===1)target=candidates[0]}}
      if(constructed&&!fluent){const methodName=/\.([\w$]+)$/.exec(chain)?.[1];if(methodName)target=lookupMethod(constructed,methodName,arity)}
      if(target&&calls.length<MAX_EDGES)calls.push({source:(owner||cls.symbol).id,target:target.id,line:invoke.location.startLine,kind:'call',resolution:'static'});
      else if(unresolved.length<1000)unresolved.push({path:unit.path,line:invoke.location.startLine,expression:chain.slice(0,140),reason:'External/dynamic type, interface without implementation, or ambiguous overload in the Java snapshot.'});

package/code_graph_js.cjs

@@ -25,7 +25,19 @@ function candidate(base) {
   const variants=[base,base.replace(/\.[cm]?jsx?$/,'.ts'),base.replace(/\.jsx?$/,'.tsx'),
     ...['.ts','.tsx','.js','.jsx','.mts','.cts','.mjs','.cjs'].map(e=>base+e),
     ...['.ts','.tsx','.js','.jsx'].map(e=>base+'/index'+e)];
-  return variants.find(name=>knownFiles.has(clean(name)));
+  const found=variants.find(name=>knownFiles.has(clean(name)));
+  return found&&clean(found);
+}
+const workspaces=new Map();
+for(const [name,file] of docs)if(name.endsWith('/package.json')&&!name.includes('/node_modules/')){try{const pkg=JSON.parse(file.text);if(typeof pkg.name==='string'&&pkg.name)workspaces.set(pkg.name,{dir:path.dirname(name),entries:[pkg.source,pkg.main,pkg.module].filter(e=>typeof e==='string')})}catch{}}
+function workspace(spec){
+  for(const [name,pkg] of workspaces){
+    if(spec!==name&&!spec.startsWith(name+'/'))continue;
+    const sub=spec.slice(name.length+1);
+    if(sub)return candidate(path.join(pkg.dir,'src',sub))||candidate(path.join(pkg.dir,sub));
+    return candidate(path.join(pkg.dir,'src/index'))||candidate(path.join(pkg.dir,'index'))||pkg.entries.map(e=>candidate(path.join(pkg.dir,e))).find(Boolean);
+  }
+  return undefined;
 }
 function resolve(spec, from) {
   if (spec.startsWith('.')) return candidate(clean(path.join(path.dirname(from),spec)));
@@ -39,6 +51,8 @@ function resolve(spec, from) {
       }
     }
   }
+  const local=workspace(spec);
+  if(local)return local;
   if(config.baseUrl)return candidate(clean(path.join(baseUrl,spec)));
   return undefined;
 }

package/code_impact.py

@@ -0,0 +1,132 @@
+"""What changing a function touches, from the indexed code graph: where it is defined, who calls it, what it calls,
+which tests reach it through static calls and which files import its module, each with the first line of its
+docstring. Answers the question an agent asks before an edit without a chain of searches and file reads."""
+import os
+from collections import defaultdict
+
+import code_graph
+import doc_check
+import index_profile
+import index_scope
+
+MAX_DEPTH = 4
+NOTE = ("Static analysis of the indexed snapshot plus the files changed in the working tree: calls made through callbacks, dynamic dispatch or names built at "
+        "runtime are not seen, so treat an empty list as 'none found', not as 'none exist'.")
+
+
+def _matches(symbols, name):
+    path, _sep, wanted = name.strip().rpartition("::")
+    path = path.replace("\\", "/").removeprefix("./")
+    pool = [s for s in symbols if s["path"] == path] if path else symbols
+    exact = [s for s in pool if s["id"] == wanted or s["name"] == wanted]
+    return exact or [s for s in pool if s["name"].split(".")[-1] == wanted]
+
+
+def _site(by_id, symbol_id, line, of=None):
+    symbol = by_id.get(symbol_id) or {}
+    site = {"id": symbol_id, "function": symbol.get("name", symbol_id), "path": symbol.get("path"), "line": line}
+    if of:
+        site["of"] = of
+    return site
+
+
+def summaries(root, symbols, wanted_ids):
+    """First docstring line of the wanted symbols, read from the working tree once per file."""
+    by_path = defaultdict(list)
+    for symbol in symbols:
+        by_path[symbol["path"]].append(symbol)
+    docs = {}
+    for path in {s["path"] for s in symbols if s["id"] in wanted_ids}:
+        try:
+            with open(os.path.join(root, path), encoding="utf-8") as stream:
+                source = stream.read()
+        except (OSError, UnicodeDecodeError):
+            continue
+        for function in doc_check.functions(path, source, by_path[path]):
+            if function["doc"]:
+                docs[(path, function["start"])] = function["doc"]
+    return {s["id"]: docs[(s["path"], s["start_line"])] for s in symbols
+            if s["id"] in wanted_ids and (s["path"], s["start_line"]) in docs}
+
+
+def impact(root, symbol, view_id=None, depth=3, limit=30):
+    if not isinstance(symbol, str) or not symbol.strip():
+        raise ValueError("Pass symbol: a function, method (Class.method) or class name.")
+    if type(depth) is not int or not 1 <= depth <= MAX_DEPTH:
+        raise ValueError(f"depth must be an integer from 1 to {MAX_DEPTH}.")
+    data = code_graph.build_current(root, view_id)
+    found = _matches(data.get("symbols") or [], symbol)
+    diagnostics = [d.get("reason") for d in data.get("diagnostics") or [] if d.get("reason")]
+    if not found:
+        cause = f" Analysis problems: {'; '.join(diagnostics)}" if diagnostics else ""
+        raise ValueError(f"No function or class named {symbol!r} in the indexed view; check the name or reindex.{cause}")
+    profile = index_profile.current((index_scope.load_scope(root) or {}).get("profile"))
+    by_id = {s["id"]: s for s in data["symbols"]}
+    callers, callees = defaultdict(list), defaultdict(list)
+    for call in data["calls"]:
+        callers[call["target"]].append(call)
+        callees[call["source"]].append(call)
+    targets = {s["id"] for s in found}
+    label = {s["id"]: f"{s['path']}::{s['name']}" for s in found} if len(found) > 1 else {}
+    tests = {}
+    for origin in targets:
+        seen, frontier = set(targets), {origin}
+        for hops in range(1, depth + 1):
+            reached = set()
+            for target in frontier:
+                for call in callers[target]:
+                    source = call["source"]
+                    if source in seen:
+                        continue
+                    seen.add(source)
+                    reached.add(source)
+                    caller = by_id.get(source)
+                    if caller and index_profile.kind(caller["path"], profile) == "test" and source not in tests:
+                        tests[source] = {**_site(by_id, source, caller["start_line"], label.get(origin)), "hops": hops}
+            frontier = reached
+    direct = [_site(by_id, c["source"], c["line"], label.get(t)) for t in targets for c in callers[t]
+              if c["source"] not in targets]
+    outgoing = [_site(by_id, c["target"], c["line"], label.get(t)) for t in targets for c in callees[t]
+                if c["target"] not in targets]
+    files = {s["path"] for s in found}
+    importers = sorted({d["source"] for d in data["dependencies"] if d.get("target") in files and d["source"] not in files})
+    ordered_tests = sorted(tests.values(), key=lambda t: (t["hops"], t["path"], t["line"]))
+    shown = direct[:limit] + outgoing[:limit] + ordered_tests[:limit]
+    docs = summaries(root, data["symbols"], targets | {site["id"] for site in shown})
+    for site in shown:
+        doc = docs.get(site.pop("id"))
+        if doc:
+            site["doc"] = doc
+    definitions = []
+    for s in found:
+        entry = {"name": s["name"], "kind": s.get("kind"), "path": s["path"], "lines": f"{s['start_line']}-{s['end_line']}"}
+        if docs.get(s["id"]):
+            entry["doc"] = docs[s["id"]]
+        definitions.append(entry)
+    return {
+        "symbol": symbol.strip(),
+        "definitions": definitions,
+        "callers": direct[:limit],
+        "calls": outgoing[:limit],
+        "tests": ordered_tests[:limit],
+        "imported_by": importers[:limit],
+        "counts": {"callers": len(direct), "calls": len(outgoing), "tests": len(ordered_tests),
+                   "imported_by": len(importers)},
+        "test_depth": depth,
+        "diagnostics": diagnostics,
+        "view": (data.get("selected") or {}).get("label"),
+        "note": NOTE + (f" {len(found)} definitions share this name; each entry says which one ('of'); pass "
+                        "path::name to keep one." if label else ""),
+    }
+
+
+def for_agent(data, limit):
+    """The file-focused graph without what an agent never reads (view list, display limits) and with lists capped."""
+    for key in ("symbols", "dependencies", "calls", "unresolved", "diagnostics"):
+        items = data.get(key) or []
+        if len(items) > limit:
+            data[key] = items[:limit]
+            data.setdefault("omitted", {})[key] = len(items) - limit
+    for key in ("views", "limits", "languages", "current_view", "generated_at", "cache_hit", "read_only", "source"):
+        data.pop(key, None)
+    return data

package/config.py

@@ -31,6 +31,8 @@ DEFAULT_CONFIG = {
     "site_memory_similarity_threshold": 0.35,
     "local_models": "fallback",
     "hook_mode": "redirect",
+    "doc_mode": "remind",
+    "duplicate_mode": "warn",
     "contact": "",
     "model_adapter": "",
     "model_adapter_options": {},
@@ -42,6 +44,26 @@ LOCAL_MODEL_MODES = ("fallback", "off", "prefer")
 # PreToolUse hook: redirect = deny the native tool and point to Smart Tool; advise = let it run and add the tip to the
 # agent's context; off = no routing at all.
 HOOK_MODES = ("redirect", "advise", "off")
+# Edit hook on functions without a docstring: require = deny the edit until it adds one; remind = let it run and tell
+# the agent; off = say nothing. Independent of hook_mode, which only routes searches and reads.
+DOC_MODES = ("require", "remind", "off")
+# Edit hook on functions that copy one already indexed (exact or near-identical body): warn = let the edit run and
+# point to the existing function; off = say nothing. Never blocks: near matches are leads, not defects.
+DUPLICATE_MODES = ("warn", "off")
+
+
+def doc_mode(cfg=None):
+    value = (cfg if cfg is not None else load_config()).get("doc_mode") or DEFAULT_CONFIG["doc_mode"]
+    if value not in DOC_MODES:
+        raise ValueError(f"Invalid doc_mode ({value!r}) in {CONFIG_PATH}: use require, remind or off.")
+    return value
+
+
+def duplicate_mode(cfg=None):
+    value = (cfg if cfg is not None else load_config()).get("duplicate_mode") or DEFAULT_CONFIG["duplicate_mode"]
+    if value not in DUPLICATE_MODES:
+        raise ValueError(f"Invalid duplicate_mode ({value!r}) in {CONFIG_PATH}: use warn or off.")
+    return value
 
 
 def hook_mode(cfg=None):