srcly 0.1.24__tar.gz → 0.1.27__tar.gz

{srcly-0.1.24 → srcly-0.1.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: srcly
-Version: 0.1.24
+Version: 0.1.27
 Summary: Interactive codebase treemap and metrics viewer.
 Requires-Python: >=3.13
 Requires-Dist: fastapi>=0.121.3

{srcly-0.1.24 → srcly-0.1.27}/app/models.py

@@ -90,6 +90,11 @@ class OverlayToken(BaseModel):
     category: str
     symbolId: str
     tooltip: str
+    definitionSnippet: str | None = None
+    definitionLine: int | None = None
+    scopeSnippet: str | None = None
+    scopeLine: int | None = None
+    scopeEndLine: int | None = None
 
 
 class FocusOverlayResponse(BaseModel):

{srcly-0.1.24 → srcly-0.1.27}/app/services/focus_overlay.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
@@ -14,6 +15,8 @@ from app.models import FocusOverlayResponse, OverlayToken
 TYPESCRIPT_LANGUAGE = Language(tstypescript.language_typescript())
 TSX_LANGUAGE = Language(tstypescript.language_tsx())
 
+logger = logging.getLogger(__name__)
+
 _SUPPORTED_TYPESCRIPT_SUFFIXES: set[str] = {
     ".ts",
     ".tsx",
@@ -53,10 +56,11 @@ class _Def:
 @dataclass
 class _Scope:
     id: str
-    type: str  # "global" | "function" | "block"
+    type: str  # "global" | "function" | "block" | "catch"
     parent_id: str | None
     start_line: int
     end_line: int
+    def_line: int  # Line of the node that created the scope
     vars: Dict[str, _Def]
 
 
@@ -67,10 +71,11 @@ class _Usage:
     start_col: int  # 0-based
     end_col: int  # exclusive
     resolved: _Def | None
+    containing_fn_scope_id: str  # Added to track where this usage occurs
 
 
 _BUILTINS: set[str] = {
-    # JS/TS builtins (small Phase 1 heuristic set)
+    # JS/TS builtins
     "console",
     "Math",
     "JSON",
@@ -93,17 +98,96 @@ _BUILTINS: set[str] = {
     "URIError",
     "Symbol",
     "BigInt",
+    "Intl",
+    "Proxy",
+    "Reflect",
+    "Atomics",
+    "DataView",
+    "ArrayBuffer",
+    "SharedArrayBuffer",
+    "AggregateError",
+    "FinalizationRegistry",
+    "WeakRef",
+    # Typed Arrays
+    "Int8Array",
+    "Uint8Array",
+    "Uint8ClampedArray",
+    "Int16Array",
+    "Uint16Array",
+    "Int32Array",
+    "Uint32Array",
+    "Float32Array",
+    "Float64Array",
+    "BigInt64Array",
+    "BigUint64Array",
+    # Fetch / Streams
     "fetch",
     "Request",
     "Response",
     "Headers",
     "URL",
     "URLSearchParams",
+    "ReadableStream",
+    "WritableStream",
+    "TransformStream",
+    "TextEncoder",
+    "TextDecoder",
+    # Environment / Global
     "window",
     "document",
     "globalThis",
     "process",
     "Buffer",
+    "navigator",
+    "location",
+    "history",
+    "screen",
+    "frames",
+    "performance",
+    "structuredClone",
+    "queueMicrotask",
+    "requestIdleCallback",
+    "cancelIdleCallback",
+    # Common DOM / Web APIs
+    "Object",
+    "requestAnimationFrame",
+    "cancelAnimationFrame",
+    "localStorage",
+    "sessionStorage",
+    "confirm",
+    "alert",
+    "prompt",
+    "Node",
+    "NodeFilter",
+    "HTMLElement",
+    "Element",
+    "Event",
+    "CustomEvent",
+    "CSS",
+    "IntersectionObserver",
+    "ResizeObserver",
+    "MutationObserver",
+    "AbortController",
+    "AbortSignal",
+    "Crypto",
+    "crypto",
+    "indexedDB",
+    "ShadowRoot",
+    "DocumentFragment",
+    "setTimeout",
+    "clearTimeout",
+    "setInterval",
+    "clearInterval",
+    # Node.js legacy/common
+    "require",
+    "module",
+    "exports",
+    "__dirname",
+    "__filename",
+    # Constants
+    "undefined",
+    "NaN",
+    "Infinity",
 }
 
 
@@ -305,6 +389,8 @@ def _resolve_to_existing_ts_module(candidate: Path) -> Optional[Path]:
         ".webp",
         ".bmp",
         ".avif",
+        ".md",
+        ".txt",
     }
     if resolved.suffix and resolved.suffix in asset_exts:
         return None
@@ -364,6 +450,7 @@ def compute_focus_overlay(
     focus_end_line = max(focus_start_line, int(focus_end_line))
 
     content = path.read_bytes()
+    source_lines = content.decode("utf-8", errors="replace").splitlines()
     is_tsx = path.suffix.lower() == ".tsx" or path.name.endswith(".tsx")
     parser = Parser(TSX_LANGUAGE if is_tsx else TYPESCRIPT_LANGUAGE)
     tree = parser.parse(content)
@@ -375,8 +462,7 @@ def compute_focus_overlay(
     slice_end_line = min(slice_end_line, file_total_lines)
 
     scopes: Dict[str, _Scope] = {}
-    scope_stack: List[_Scope] = []
-
+    
     # Deterministic scope IDs based on start/end lines + a monotonic counter for collisions.
     scope_counter = 0
 
@@ -396,13 +482,13 @@ def compute_focus_overlay(
             parent_id=parent.id if parent else None,
             start_line=start_line,
             end_line=end_line,
+            def_line=start_line,
             vars={},
         )
         scopes[scope.id] = scope
         return scope
 
     global_scope = new_scope("global", tree.root_node, None)
-    scope_stack.append(global_scope)
 
     # --- Helpers ---
     def _is_function_node(n: Node) -> bool:
@@ -414,21 +500,29 @@ def compute_focus_overlay(
             "generator_function",
             "generator_function_declaration",
         }
+    
+    def _is_catch_clause(n: Node) -> bool:
+        return n.type == "catch_clause"
 
     def _is_scope_boundary(n: Node) -> bool:
         # Mirror the data-flow analyzer behavior: don't create a redundant block
         # scope for function bodies.
         if n.type in {"block", "statement_block"}:
             parent = n.parent
-            if parent and _is_function_node(parent):
+            if parent and (_is_function_node(parent) or _is_catch_clause(parent)):
                 return False
             return True
+        
+        if _is_catch_clause(n):
+            return True
 
         return _is_function_node(n)
 
     def _scope_type(n: Node) -> str:
         if _is_function_node(n):
             return "function"
+        if _is_catch_clause(n):
+            return "catch"
         if n.type in {"block", "statement_block"}:
             return "block"
         return "block"
@@ -506,10 +600,15 @@ def compute_focus_overlay(
         )
         scope.vars[name] = d
 
-    def _resolve(name: str) -> _Def | None:
-        for s in reversed(scope_stack):
-            if name in s.vars:
-                return s.vars[name]
+    def _resolve(name: str, start_scope: _Scope) -> _Def | None:
+        curr = start_scope
+        while curr:
+            if name in curr.vars:
+                return curr.vars[name]
+            if curr.parent_id:
+                curr = scopes[curr.parent_id]
+            else:
+                break
         return None
 
     def _ancestor_chain(scope_id: str) -> List[str]:
@@ -522,16 +621,20 @@ def compute_focus_overlay(
             curr = scopes.get(curr.parent_id)
         return chain
 
-    # --- Traverse: create scopes + record defs/usages ---
-    usages: List[_Usage] = []
-
-    def traverse(n: Node) -> None:
-        scope_created = False
+    # --- Phase 1: Create scopes and record definitions ---
+    
+    # We maintain a mapping of node_id -> created_scope so we can look them up in Phase 2
+    # `scope_boundary_map[id(node)] = scope`
+    scope_boundary_map: Dict[int, _Scope] = {}
+    
+    def phase1_traverse(n: Node, current_scope: _Scope) -> None:
+        next_scope = current_scope
         if _is_scope_boundary(n):
-            parent = scope_stack[-1] if scope_stack else None
-            scope = new_scope(_scope_type(n), n, parent)
-            scope_stack.append(scope)
-            scope_created = True
+            # If we are effectively creating a new scope
+            # Ensure we don't recreate global scope if n is root
+            if n != tree.root_node:
+                next_scope = new_scope(_scope_type(n), n, current_scope)
+                scope_boundary_map[n.id] = next_scope
 
         # Definitions
         if n.type == "import_statement":
@@ -617,62 +720,86 @@ def compute_focus_overlay(
                                     import_is_internal=is_internal,
                                 )
 
-        if n.type == "variable_declarator":
+        elif n.type == "variable_declarator":
             name_node = n.child_by_field_name("name")
             if name_node is not None:
                 if name_node.type == "identifier":
                     _add_def(
                         name_node=name_node,
                         kind="local",
-                        scope=scope_stack[-1],
-                        scope_type=scope_stack[-1].type,
+                        scope=next_scope,
+                        scope_type=next_scope.type,
                     )
                 else:
                     for ident in _collect_pattern_identifiers(name_node):
                         _add_def(
                             name_node=ident,
                             kind="local",
-                            scope=scope_stack[-1],
-                            scope_type=scope_stack[-1].type,
+                            scope=next_scope,
+                            scope_type=next_scope.type,
                         )
 
-        if n.type in {"required_parameter", "optional_parameter", "rest_parameter"}:
+        elif n.type in {"required_parameter", "optional_parameter", "rest_parameter"}:
             for ident in _collect_pattern_identifiers(n):
                 _add_def(
                     name_node=ident,
                     kind="param",
-                    scope=scope_stack[-1],
-                    scope_type=scope_stack[-1].type,
+                    scope=next_scope,
+                    scope_type=next_scope.type,
                 )
+        
+        elif n.type == "identifier" and n.parent and n.parent.type == "arrow_function":
+            # In arrow functions like `tile => { ... }`, the parameter `tile`
+            # is a direct identifier child of the arrow_function node.
+            _add_def(
+                name_node=n,
+                kind="param",
+                scope=next_scope,
+                scope_type=next_scope.type,
+            )
+        
+        elif n.type == "catch_clause":
+             # catch (err) ...
+             param = n.child_by_field_name("parameter")
+             if param:
+                # The parameter node might be an identifier or a pattern (destructuring)
+                # But it is physically outside the 'body' block.
+                # Since we created a 'catch' scope for this catch_clause node, we can add it there.
+                
+                # In tree-sitter-typescript, the parameter field of catch_clause serves as the binding.
+                if param.type == "identifier":
+                    _add_def(name_node=param, kind="param", scope=next_scope, scope_type="catch")
+                else:
+                    for ident in _collect_pattern_identifiers(param):
+                         _add_def(name_node=ident, kind="param", scope=next_scope, scope_type="catch")
 
-        if n.type == "function_declaration":
+
+        elif n.type == "function_declaration":
             name_node = n.child_by_field_name("name")
             if name_node is not None:
                 # Define function name in parent scope (if any).
-                parent_scope = scope_stack[-2] if len(scope_stack) >= 2 else scope_stack[-1]
+                # `next_scope` IS the function scope.
+                # So we want the scope enclosing `n`, which is `current_scope`.
+                
                 _add_def(
                     name_node=name_node,
-                    kind="local" if parent_scope.type != "global" else "module",
-                    scope=parent_scope,
-                    scope_type=parent_scope.type,
+                    kind="local" if current_scope.type != "global" else "module",
+                    scope=current_scope,
+                    scope_type=current_scope.type,
                 )
 
-        if n.type == "class_declaration":
+        elif n.type == "class_declaration":
             name_node = n.child_by_field_name("name")
             if name_node is not None:
-                parent_scope = scope_stack[-2] if len(scope_stack) >= 2 else scope_stack[-1]
                 _add_def(
                     name_node=name_node,
-                    kind="local" if parent_scope.type != "global" else "module",
-                    scope=parent_scope,
-                    scope_type=parent_scope.type,
+                    kind="local" if current_scope.type != "global" else "module",
+                    scope=current_scope,
+                    scope_type=current_scope.type,
                 )
 
         # Loop introductions:
-        # In our tree-sitter-typescript version, `for (const x of xs) { ... }`
-        # parses as `for_in_statement` with children including `const`, `of`,
-        # and `left` as a bare identifier (not a variable_declarator).
-        if n.type == "for_in_statement":
+        elif n.type == "for_in_statement":
             # Only treat as an introduction when it's a declaration (const/let/var).
             is_decl = any(c.type in {"const", "let", "var"} for c in n.children)
             if is_decl:
@@ -682,20 +809,35 @@ def compute_focus_overlay(
                         _add_def(
                             name_node=left,
                             kind="local",
-                            scope=scope_stack[-1],
-                            scope_type=scope_stack[-1].type,
+                            scope=next_scope,
+                            scope_type=next_scope.type,
                         )
                     else:
                         for ident in _collect_pattern_identifiers(left):
                             _add_def(
                                 name_node=ident,
                                 kind="local",
-                                scope=scope_stack[-1],
-                                scope_type=scope_stack[-1].type,
+                                scope=next_scope,
+                                scope_type=next_scope.type,
                             )
 
-        # Usages: resolve identifiers while we still have the right scope stack.
-        if n.type == "identifier":
+        for c in n.children:
+            phase1_traverse(c, next_scope)
+
+    phase1_traverse(tree.root_node, global_scope)
+
+    # --- Phase 2: Record usages ---
+    usages: List[_Usage] = []
+    
+    unresolved_counts: Dict[str, int] = {}
+    
+    def phase2_traverse(n: Node, current_scope: _Scope) -> None:
+        next_scope = current_scope
+        if n.id in scope_boundary_map:
+            next_scope = scope_boundary_map[n.id]
+
+        # Usages: resolve identifiers
+        if n.type in {"identifier", "jsx_identifier"}:
             parent = n.parent
             if parent is not None:
                 # Skip identifier occurrences that are themselves definitions.
@@ -707,36 +849,77 @@ def compute_focus_overlay(
                     pass
                 elif parent.type in {"required_parameter", "optional_parameter", "rest_parameter"}:
                     pass
+                elif parent.type == "catch_clause" and parent.child_by_field_name("parameter") == n:
+                    pass
                 elif (
                     parent.type == "for_in_statement"
                     and parent.child_by_field_name("left") == n
                     and any(c.type in {"const", "let", "var"} for c in parent.children)
                 ):
-                    # `for (const x of xs)` introduces `x` as a binding.
                     pass
                 elif parent.type == "property_identifier":
                     pass
+                
+                # SPECIAL HANDLING FOR JSX
+                # 1. Skip if it is an attribute name
+                elif (n.type in {"identifier", "jsx_identifier"}) and parent.type == "jsx_attribute" and parent.child_by_field_name("name") == n:
+                    pass
+                # 2. Skip intrinsic elements (lowercase tag names)
+                # If text is uppercase, the condition below fails, so we fall through to 'else'
+                # and process it as a component usage.
+                elif (
+                    n.type in {"identifier", "jsx_identifier"} 
+                    and parent.type in {"jsx_opening_element", "jsx_closing_element", "jsx_self_closing_element"}
+                    and parent.child_by_field_name("name") == n
+                    and n.text.decode("utf-8", errors="ignore")[0].islower()
+                ):
+                    pass
+
                 else:
                     # Skip identifiers inside binding patterns (destructuring LHS / params)
+                    # Skip identifiers inside binding patterns (destructuring LHS / params)
+                    # We need to be careful not to skip usages on the RHS.
+                    # e.g. `const { x: y } = z` -> x is prop (skipped), y is def (skipped), z is usage.
                     curr = n
+                    is_definition_part = False
+                    
                     while curr is not None:
                         p = curr.parent
                         if p is None:
                             break
+                        
+                        # Variable declarator: `name` field is the pattern/identifier being defined.
                         if p.type == "variable_declarator":
                             name_node = p.child_by_field_name("name")
                             if name_node is not None:
                                 check = n
+                                # Walk up from n to p. If we hit name_node, we are inside the definition side.
                                 while check is not None and check is not p:
-                                    if check is name_node:
+                                    if check == name_node:
+                                        is_definition_part = True
                                         break
                                     check = check.parent
-                                if check is name_node:
-                                    curr = None
+                                if is_definition_part:
                                     break
+                            
                         if p.type in {"required_parameter", "optional_parameter", "rest_parameter"}:
-                            curr = None
+                            is_definition_part = True
                             break
+                        
+                        if p.type == "catch_clause":
+                            param = p.child_by_field_name("parameter")
+                             # If we are inside the parameter node
+                            if param:
+                                check = n
+                                while check is not None and check is not p:
+                                    if check is param:
+                                        is_definition_part = True
+                                        break
+                                    check = check.parent
+                            if is_definition_part:
+                                break
+
+                        # Boundaries where definition context definitely ends
                         if p.type in {
                             "program",
                             "statement_block",
@@ -747,11 +930,24 @@ def compute_focus_overlay(
                             "class_declaration",
                         }:
                             break
+                        
                         curr = p
-                    if curr is not None:
+                        if is_definition_part:
+                            break
+                            
+                    if not is_definition_part:
                         name = n.text.decode("utf-8", errors="ignore")
                         if name:
-                            resolved = _resolve(name)
+                            resolved = _resolve(name, next_scope)
+                            if resolved is None and name not in _BUILTINS:
+                                unresolved_counts[name] = unresolved_counts.get(name, 0) + 1
+                                
+                            # Find the immediate containing function scope for this usage.
+                            # This is crucial for per-token "capture" vs "local" classification.
+                            usage_fn_scope = next_scope
+                            while usage_fn_scope and usage_fn_scope.type != "function" and usage_fn_scope.parent_id:
+                                usage_fn_scope = scopes[usage_fn_scope.parent_id]
+                            
                             usages.append(
                                 _Usage(
                                     name=name,
@@ -759,31 +955,19 @@ def compute_focus_overlay(
                                     start_col=n.start_point.column,
                                     end_col=n.end_point.column,
                                     resolved=resolved,
+                                    containing_fn_scope_id=usage_fn_scope.id if usage_fn_scope else global_scope.id,
                                 )
                             )
 
         for c in n.children:
-            traverse(c)
-
-        if scope_created:
-            scope_stack.pop()
+            phase2_traverse(c, next_scope)
 
-    traverse(tree.root_node)
+    phase2_traverse(tree.root_node, global_scope)
 
-    # --- Find focus function scope (preferred boundary for param/local/capture semantics) ---
-    def smallest_containing_function_scope() -> _Scope:
-        candidates: List[_Scope] = []
-        for s in scopes.values():
-            if s.type != "function":
-                continue
-            if s.start_line <= focus_start_line and s.end_line >= focus_end_line:
-                candidates.append(s)
-        if not candidates:
-            return global_scope
-        return min(candidates, key=lambda s: (s.end_line - s.start_line, s.start_line))
-
-    focus_fn_scope = smallest_containing_function_scope()
-    focus_fn_chain = set(_ancestor_chain(focus_fn_scope.id))  # includes global
+    if unresolved_counts:
+        # Log top unresolved identifiers to help identify missing builtins/globals
+        sorted_unresolved = sorted(unresolved_counts.items(), key=lambda x: x[1], reverse=True)
+        logger.info(f"Focus overlay unresolved symbols for {path.name}: {sorted_unresolved[:20]}")
 
     # --- Build tokens ---
     tokens: List[OverlayToken] = []
@@ -846,17 +1030,48 @@ def compute_focus_overlay(
                             category = "module"
                             tooltip = f"Module scope (line {d.def_line})"
                         else:
+                            # Classify relative to the token's immediate containing function scope
+                            usage_fn_scope_id = u.containing_fn_scope_id
+                            usage_fn_chain = set(_ancestor_chain(usage_fn_scope_id))
+                            
+                            
                             def_chain = set(_ancestor_chain(def_scope.id))
-                            if focus_fn_scope.id in def_chain:
+                            
+                            # START FIX: If the definition is within the current focus range, treat as local.
+                            definition_in_focus = (focus_start_line <= d.def_line <= focus_end_line)
+                            
+                            if definition_in_focus:
                                 category = "local"
                                 tooltip = f"Local declaration (line {d.def_line})"
-                            elif def_scope.id in focus_fn_chain and def_scope.id != global_scope.id:
+                            elif usage_fn_scope_id in def_chain:
+                                category = "local"
+                                tooltip = f"Local declaration (line {d.def_line})"
+                            elif def_scope.id in usage_fn_chain and def_scope.id != global_scope.id:
                                 category = "capture"
                                 tooltip = f"Captured from outer scope (line {d.def_line})"
                             else:
                                 category = "local"
                                 tooltip = f"Local declaration (line {d.def_line})"
 
+        definition_snippet: str | None = None
+        definition_line: int | None = None
+        if d:
+            definition_line = d.def_line
+            if 0 <= d.def_line - 1 < len(source_lines):
+                 definition_snippet = source_lines[d.def_line - 1].strip()
+
+        scope_snippet: str | None = None
+        scope_line: int | None = None
+        scope_end_line: int | None = None
+
+        if category == "capture" and d:
+            def_scope = scopes.get(d.scope_id)
+            if def_scope:
+                scope_line = def_scope.def_line
+                scope_end_line = def_scope.end_line
+                if 0 <= scope_line - 1 < len(source_lines):
+                    scope_snippet = source_lines[scope_line - 1].strip()
+
         tokens.append(
             OverlayToken(
                 fileLine=u_line,
@@ -865,9 +1080,12 @@ def compute_focus_overlay(
                 category=category,
                 symbolId=symbol_id,
                 tooltip=tooltip,
+                definitionSnippet=definition_snippet,
+                definitionLine=definition_line,
+                scopeSnippet=scope_snippet,
+                scopeLine=scope_line,
+                scopeEndLine=scope_end_line,
             )
         )
 
     return FocusOverlayResponse(tokens=tokens)
-
-