commiter-cli 0.3.0__py3-none-any.whl

commiter/parser.py

@@ -0,0 +1,1283 @@
+"""Tree-sitter setup, grammar loading, and AST query helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import tree_sitter_python as tspython
+import tree_sitter_javascript as tsjavascript
+import tree_sitter_typescript as tstypescript
+from tree_sitter import Language, Parser, Node
+
+if TYPE_CHECKING:
+    from tree_sitter import Tree
+
+# Language singletons — loaded once and cached
+_LANGUAGES: dict[str, Language] = {}
+
+
+def _get_language(lang: str) -> Language:
+    """Get or create a Tree-sitter Language for the given language name."""
+    if lang not in _LANGUAGES:
+        if lang == "python":
+            _LANGUAGES[lang] = Language(tspython.language())
+        elif lang == "javascript":
+            _LANGUAGES[lang] = Language(tsjavascript.language())
+        elif lang == "typescript":
+            _LANGUAGES[lang] = Language(tstypescript.language_typescript())
+        elif lang == "tsx":
+            _LANGUAGES[lang] = Language(tstypescript.language_tsx())
+        else:
+            raise ValueError(f"Unsupported language: {lang}")
+    return _LANGUAGES[lang]
+
+
+def detect_language(file_path: str) -> str | None:
+    """Detect programming language from file extension."""
+    ext = Path(file_path).suffix.lower()
+    mapping = {
+        ".py": "python",
+        ".js": "javascript",
+        ".mjs": "javascript",
+        ".cjs": "javascript",
+        ".jsx": "javascript",
+        ".ts": "typescript",
+        ".tsx": "tsx",
+    }
+    return mapping.get(ext)
+
+
+def parse_file(file_path: str, language: str | None = None) -> tuple[Tree, str] | None:
+    """Parse a file and return its Tree-sitter tree and detected language.
+
+    Returns None if the file cannot be parsed (unsupported language, read error, etc.).
+    """
+    if language is None:
+        language = detect_language(file_path)
+    if language is None:
+        return None
+
+    try:
+        source = Path(file_path).read_bytes()
+    except (OSError, IOError):
+        return None
+
+    lang = _get_language(language)
+    parser = Parser(lang)
+    tree = parser.parse(source)
+    return tree, language
+
+
+def get_source(file_path: str) -> bytes:
+    """Read file source as bytes."""
+    return Path(file_path).read_bytes()
+
+
+def node_text(node: Node, source: bytes) -> str:
+    """Extract the text content of an AST node."""
+    return source[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+
+
+def find_nodes_by_type(node: Node, type_name: str) -> list[Node]:
+    """Recursively find all descendant nodes of a given type."""
+    results = []
+    if node.type == type_name:
+        results.append(node)
+    for child in node.children:
+        results.extend(find_nodes_by_type(child, type_name))
+    return results
+
+
+def find_decorated_functions(node: Node, source: bytes) -> list[tuple[list[str], Node]]:
+    """Find all decorated function definitions.
+
+    Returns a list of (decorator_names, function_node) tuples.
+    """
+    results = []
+    for child in node.children:
+        if child.type == "decorated_definition":
+            decorators = []
+            func_node = None
+            for sub in child.children:
+                if sub.type == "decorator":
+                    dec_text = node_text(sub, source).lstrip("@").strip()
+                    decorators.append(dec_text)
+                elif sub.type == "function_definition":
+                    func_node = sub
+            if func_node is not None:
+                results.append((decorators, func_node))
+        elif child.type == "function_definition":
+            results.append(([], child))
+        # Recurse into class bodies, modules, etc.
+        if child.type in ("module", "class_definition", "block"):
+            results.extend(find_decorated_functions(child, source))
+    return results
+
+
+def find_function_calls(node: Node, source: bytes, name: str | None = None) -> list[Node]:
+    """Find all function call nodes, optionally filtered by function name."""
+    calls = find_nodes_by_type(node, "call")
+    if name is None:
+        return calls
+    results = []
+    for call in calls:
+        func = call.child_by_field_name("function")
+        if func and node_text(func, source) == name:
+            results.append(call)
+    return results
+
+
+def find_imports(node: Node, source: bytes) -> list[str]:
+    """Extract all import names from a module."""
+    imports = []
+    for child in node.children:
+        if child.type == "import_statement":
+            imports.append(node_text(child, source))
+        elif child.type == "import_from_statement":
+            imports.append(node_text(child, source))
+    return imports
+
+
+def find_string_literals(node: Node, source: bytes) -> list[tuple[str, Node]]:
+    """Find all string literal values and their nodes."""
+    strings = []
+    for str_node in find_nodes_by_type(node, "string"):
+        text = node_text(str_node, source)
+        # Strip quotes
+        if len(text) >= 2:
+            if text.startswith(('"""', "'''")):
+                val = text[3:-3]
+            elif text.startswith(('"', "'")):
+                val = text[1:-1]
+            else:
+                val = text
+            strings.append((val, str_node))
+    return strings
+
+
+# ──────────────────────────────────────────────
+# JS/TS import and export helpers
+# ──────────────────────────────────────────────
+
+@dataclass
+class JSImport:
+    """A parsed JS/TS import statement."""
+    names: list[str]
+    module_path: str
+    is_default: bool
+    line: int
+
+
+@dataclass
+class JSExportedFunction:
+    """An exported function or arrow-function const in JS/TS."""
+    name: str
+    body_node: Node
+    file_path: str
+    line: int
+
+
+def find_js_imports(node: Node, source: bytes) -> list[JSImport]:
+    """Find all import statements in a JS/TS AST.
+
+    Handles:
+      import { getUser, createPost } from "../lib/api";
+      import api from "../lib/api";
+      import * as api from "../lib/api";
+    """
+    imports = []
+    for child in node.children:
+        if child.type != "import_statement":
+            continue
+
+        text = node_text(child, source)
+        line = child.start_point[0] + 1
+
+        # Extract the module path (the string after "from")
+        module_path = None
+        for sub in child.children:
+            if sub.type == "string":
+                module_path = node_text(sub, source).strip("'\"")
+                break
+
+        if not module_path:
+            continue
+
+        # Extract imported names
+        names = []
+        is_default = False
+
+        for sub in child.children:
+            if sub.type == "import_clause":
+                for clause_child in sub.children:
+                    if clause_child.type == "identifier":
+                        # default import: import Foo from "..."
+                        names.append(node_text(clause_child, source))
+                        is_default = True
+                    elif clause_child.type == "named_imports":
+                        # { getUser, createPost } or { getUser as gu }
+                        for spec in clause_child.children:
+                            if spec.type == "import_specifier":
+                                name_node = spec.child_by_field_name("name")
+                                alias_node = spec.child_by_field_name("alias")
+                                # Use alias if present, otherwise the original name
+                                target = alias_node if alias_node else name_node
+                                if target:
+                                    names.append(node_text(target, source))
+                    elif clause_child.type == "namespace_import":
+                        # import * as api from "..."
+                        for ns_child in clause_child.children:
+                            if ns_child.type == "identifier":
+                                names.append(node_text(ns_child, source))
+                                is_default = True
+
+        if names:
+            imports.append(JSImport(
+                names=names,
+                module_path=module_path,
+                is_default=is_default,
+                line=line,
+            ))
+
+    return imports
+
+
+def find_js_exported_functions(node: Node, source: bytes, file_path: str = "") -> list[JSExportedFunction]:
+    """Find all exported function/const declarations in JS/TS.
+
+    Handles:
+      export function getUser(id) { ... }
+      export const getUser = (id) => fetch(...);
+      export const getUser = async (id) => { ... };
+      export default function handler(req, res) { ... }
+    """
+    results = []
+
+    for child in node.children:
+        if child.type != "export_statement":
+            continue
+
+        for sub in child.children:
+            # export function getUser(id) { ... }
+            if sub.type == "function_declaration":
+                name_node = sub.child_by_field_name("name")
+                if name_node:
+                    body = sub.child_by_field_name("body") or sub
+                    results.append(JSExportedFunction(
+                        name=node_text(name_node, source),
+                        body_node=body,
+                        file_path=file_path,
+                        line=sub.start_point[0] + 1,
+                    ))
+
+            # export const getUser = (id) => fetch(...)
+            elif sub.type == "lexical_declaration":
+                for decl in sub.children:
+                    if decl.type == "variable_declarator":
+                        name_node = decl.child_by_field_name("name")
+                        value_node = decl.child_by_field_name("value")
+                        if name_node and value_node:
+                            # value_node could be arrow_function, function_expression, or call_expression
+                            body = value_node
+                            if value_node.type in ("arrow_function", "function_expression"):
+                                body = value_node.child_by_field_name("body") or value_node
+                            results.append(JSExportedFunction(
+                                name=node_text(name_node, source),
+                                body_node=body,
+                                file_path=file_path,
+                                line=decl.start_point[0] + 1,
+                            ))
+
+    return results
+
+
+# ──────────────────────────────────────────────
+# Type extraction helpers (TS interfaces, Python classes)
+# ──────────────────────────────────────────────
+
+@dataclass
+class TypeField:
+    """A single field in a type/interface/class/enum definition."""
+    name: str
+    type_str: str
+    optional: bool = False
+    value: str | None = None  # actual value for enum members and const assertions
+
+
+def extract_type_annotation(node: Node, source: bytes) -> str | None:
+    """Extract type annotation from a TS parameter node.
+
+    Works with required_parameter, optional_parameter, and property_signature nodes
+    that have a type_annotation child.
+    """
+    for child in node.children:
+        if child.type == "type_annotation":
+            text = node_text(child, source).strip()
+            if text.startswith(":"):
+                text = text[1:].strip()
+            return text
+    return None
+
+
+def find_ts_interface_fields(node: Node, source: bytes) -> dict[str, list[TypeField]]:
+    """Find all interface definitions in a TS/TSX file.
+
+    Returns a dict mapping type name to its field list.
+    Handles both exported and non-exported interfaces.
+    """
+    result: dict[str, list[TypeField]] = {}
+
+    for child in node.children:
+        target = child
+        # Handle exported interfaces: export_statement -> interface_declaration
+        if child.type == "export_statement":
+            for sub in child.children:
+                if sub.type == "interface_declaration":
+                    target = sub
+                    break
+
+        if target.type == "interface_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = node_text(name_node, source)
+            fields = _extract_interface_body_fields(target, source)
+            if fields:
+                result[name] = fields
+
+    return result
+
+
+def _extract_interface_body_fields(iface_node: Node, source: bytes) -> list[TypeField]:
+    """Extract property signatures from an interface body."""
+    fields = []
+    body = iface_node.child_by_field_name("body")
+    if not body:
+        for child in iface_node.children:
+            if child.type in ("interface_body", "object_type"):
+                body = child
+                break
+    if not body:
+        return fields
+
+    for child in body.children:
+        if child.type == "property_signature":
+            prop_name = None
+            prop_type = "unknown"
+            optional = False
+
+            name_node = child.child_by_field_name("name")
+            if name_node:
+                prop_name = node_text(name_node, source)
+
+            for sub in child.children:
+                if node_text(sub, source) == "?":
+                    optional = True
+
+            type_ann = extract_type_annotation(child, source)
+            if type_ann:
+                prop_type = type_ann
+
+            if prop_name:
+                fields.append(TypeField(name=prop_name, type_str=prop_type, optional=optional))
+
+    return fields
+
+
+def find_ts_enum_declarations(node: Node, source: bytes) -> dict[str, list[TypeField]]:
+    """Find all enum definitions in a TS/TSX file.
+
+    Returns a dict mapping enum name to its member list.
+    Handles: enum Status { ACTIVE = "active", INACTIVE = "inactive" }
+    """
+    result: dict[str, list[TypeField]] = {}
+
+    for child in node.children:
+        target = child
+        if child.type == "export_statement":
+            for sub in child.children:
+                if sub.type == "enum_declaration":
+                    target = sub
+                    break
+
+        if target.type == "enum_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = node_text(name_node, source)
+            members = _extract_enum_members(target, source)
+            if members:
+                result[name] = members
+
+    return result
+
+
+def _extract_enum_members(enum_node: Node, source: bytes) -> list[TypeField]:
+    """Extract members from an enum body."""
+    members = []
+    body = enum_node.child_by_field_name("body")
+    if not body:
+        # Try finding enum_body child directly
+        for child in enum_node.children:
+            if child.type == "enum_body":
+                body = child
+                break
+    if not body:
+        return members
+
+    for child in body.children:
+        if child.type in ("enum_member", "enum_assignment", "property_identifier"):
+            member_name = None
+            value_str = None
+
+            name_node = child.child_by_field_name("name")
+            if name_node:
+                member_name = node_text(name_node, source)
+            elif child.type == "property_identifier":
+                member_name = node_text(child, source)
+
+            value_node = child.child_by_field_name("value")
+            if value_node:
+                value_str = node_text(value_node, source).strip("'\"")
+
+            if member_name:
+                members.append(TypeField(
+                    name=member_name,
+                    type_str=f'"{value_str}"' if value_str else "auto",
+                    value=value_str,
+                ))
+
+    return members
+
+
+def find_ts_type_aliases(node: Node, source: bytes) -> dict[str, list[TypeField]]:
+    """Find type alias declarations in a TS/TSX file.
+
+    Handles:
+      type User = { id: string; name: string }  (object-like)
+      type Status = "active" | "inactive"        (union literal)
+    """
+    result: dict[str, list[TypeField]] = {}
+
+    for child in node.children:
+        target = child
+        if child.type == "export_statement":
+            for sub in child.children:
+                if sub.type == "type_alias_declaration":
+                    target = sub
+                    break
+
+        if target.type == "type_alias_declaration":
+            name_node = target.child_by_field_name("name")
+            if not name_node:
+                continue
+            name = node_text(name_node, source)
+
+            value_node = target.child_by_field_name("value")
+            if not value_node:
+                continue
+
+            # Object-like type alias: type User = { id: string; name: string }
+            if value_node.type == "object_type":
+                fields = []
+                for prop in value_node.children:
+                    if prop.type == "property_signature":
+                        prop_name = None
+                        prop_type = "unknown"
+                        optional = False
+
+                        pn = prop.child_by_field_name("name")
+                        if pn:
+                            prop_name = node_text(pn, source)
+                        for sub in prop.children:
+                            if node_text(sub, source) == "?":
+                                optional = True
+                        type_ann = extract_type_annotation(prop, source)
+                        if type_ann:
+                            prop_type = type_ann
+                        if prop_name:
+                            fields.append(TypeField(name=prop_name, type_str=prop_type, optional=optional))
+                if fields:
+                    result[name] = fields
+
+            # Union: type Status = "active" | "inactive" OR type Response = Success | Error
+            elif value_node.type == "union_type":
+                members = _flatten_union_type(value_node, source)
+                if members:
+                    result[name] = members
+
+            # Intersection: type FullUser = BaseFields & AuthFields & { role: string }
+            elif value_node.type == "intersection_type":
+                fields = _extract_intersection_parts(value_node, source)
+                if fields:
+                    result[name] = fields
+
+            # Generic type: type UserSummary = Pick<User, "id" | "name">
+            # Store as a marker — resolved lazily by the generic resolver
+            elif value_node.type == "generic_type":
+                generic_text = node_text(value_node, source).strip()
+                result[name] = [TypeField(name=name, type_str="__generic__", value=generic_text)]
+
+    return result
+
+
+def _flatten_union_type(union_node: Node, source: bytes) -> list[TypeField]:
+    """Recursively flatten a union_type node into a list of TypeField members."""
+    members = []
+    for child in union_node.children:
+        if child.type == "union_type":
+            members.extend(_flatten_union_type(child, source))
+        elif child.type == "literal_type":
+            val = node_text(child, source).strip("'\"")
+            if val:
+                members.append(TypeField(name=val, type_str="literal", value=val))
+        elif child.type == "type_identifier":
+            # Type reference in union: SuccessResponse | ErrorResponse
+            type_name = node_text(child, source)
+            members.append(TypeField(name=type_name, type_str="__type_ref__"))
+        elif child.type == "predefined_type":
+            type_name = node_text(child, source)
+            members.append(TypeField(name=type_name, type_str="predefined"))
+    return members
+
+
+def _extract_intersection_parts(node: Node, source: bytes) -> list[TypeField]:
+    """Extract fields from an intersection type: A & B & { inline: string }.
+
+    For type references (A, B): stores as __type_ref__ markers for later resolution.
+    For inline objects ({ inline: string }): extracts fields directly.
+    Handles nested intersections recursively.
+    """
+    fields: list[TypeField] = []
+
+    for child in node.children:
+        if child.type == "intersection_type":
+            # Nested intersection — recurse
+            fields.extend(_extract_intersection_parts(child, source))
+        elif child.type == "type_identifier":
+            # Reference to another type — mark for later resolution
+            type_name = node_text(child, source)
+            fields.append(TypeField(name=type_name, type_str="__type_ref__"))
+        elif child.type == "object_type":
+            # Inline object: { role: string; active: boolean }
+            for prop in child.children:
+                if prop.type == "property_signature":
+                    prop_name = None
+                    prop_type = "unknown"
+                    optional = False
+
+                    pn = prop.child_by_field_name("name")
+                    if pn:
+                        prop_name = node_text(pn, source)
+                    for sub in prop.children:
+                        if node_text(sub, source) == "?":
+                            optional = True
+                    type_ann = extract_type_annotation(prop, source)
+                    if type_ann:
+                        prop_type = type_ann
+                    if prop_name:
+                        fields.append(TypeField(name=prop_name, type_str=prop_type, optional=optional))
+
+    return fields
+
+
+def find_ts_const_objects(node: Node, source: bytes) -> dict[str, list[TypeField]]:
+    """Find const object declarations with 'as const' or UPPER_CASE names.
+
+    Handles: const STATUS = { ACTIVE: "active", INACTIVE: "inactive" } as const;
+    """
+    result: dict[str, list[TypeField]] = {}
+
+    for child in node.children:
+        target = child
+        if child.type == "export_statement":
+            for sub in child.children:
+                if sub.type == "lexical_declaration":
+                    target = sub
+                    break
+
+        if target.type != "lexical_declaration":
+            continue
+
+        for decl in target.children:
+            if decl.type != "variable_declarator":
+                continue
+
+            name_node = decl.child_by_field_name("name")
+            value_node = decl.child_by_field_name("value")
+            if not name_node or not value_node:
+                continue
+
+            var_name = node_text(name_node, source)
+
+            # Check for "as const" assertion or UPPER_CASE convention
+            decl_text = node_text(decl, source)
+            is_const_assertion = "as const" in decl_text
+            is_upper_case = var_name == var_name.upper() and len(var_name) > 1
+
+            if not (is_const_assertion or is_upper_case):
+                continue
+
+            # Extract object properties — value might be wrapped in as_expression
+            obj_node = value_node
+            if value_node.type == "as_expression":
+                # Unwrap: { ... } as const → get the object inside
+                for sub in value_node.children:
+                    if sub.type == "object":
+                        obj_node = sub
+                        break
+
+            if obj_node.type != "object":
+                continue
+
+            fields = []
+            for prop in obj_node.children:
+                if prop.type == "pair":
+                    key_node = prop.child_by_field_name("key")
+                    val_node = prop.child_by_field_name("value")
+                    if key_node and val_node:
+                        key = node_text(key_node, source).strip("'\"")
+                        val = node_text(val_node, source).strip("'\"")
+                        fields.append(TypeField(name=key, type_str=f'"{val}"', value=val))
+
+            if fields:
+                result[var_name] = fields
+
+    return result
+
+
+def find_py_class_fields(node: Node, source: bytes, class_name: str) -> list[TypeField]:
+    """Extract typed fields from a Python class (Pydantic BaseModel, dataclass, etc.).
+
+    Looks for annotated assignments: name: str, price: float = 0.0, etc.
+    """
+    for child in node.children:
+        if child.type != "class_definition":
+            continue
+        name_node = child.child_by_field_name("name")
+        if not name_node or node_text(name_node, source) != class_name:
+            continue
+
+        body = child.child_by_field_name("body")
+        if not body:
+            continue
+
+        return _extract_py_class_body_fields(body, source)
+
+    return []
+
+
+def _extract_py_class_body_fields(body: Node, source: bytes) -> list[TypeField]:
+    """Extract annotated assignments from a Python class body."""
+    fields = []
+    for stmt in body.children:
+        if stmt.type != "expression_statement":
+            continue
+
+        text = node_text(stmt, source).strip()
+        if ":" not in text:
+            continue
+
+        # Split on first ":" to get name and type
+        colon_idx = text.index(":")
+        name = text[:colon_idx].strip()
+        rest = text[colon_idx + 1:].strip()
+
+        # Remove default value if present
+        type_str = rest.split("=")[0].strip()
+        has_default = "=" in rest
+        optional = "Optional" in type_str or "| None" in type_str or has_default
+
+        if name and not name.startswith(("#", "def", "class", "@")):
+            fields.append(TypeField(name=name, type_str=type_str, optional=optional))
+
+    return fields
+
+
+def find_py_imports_with_names(node: Node, source: bytes) -> list["PyImport"]:
+    """Extract Python from...import statements with individual names.
+
+    Handles: from .schemas import UserCreate, UserResponse
+    """
+    imports = []
+    for child in node.children:
+        if child.type != "import_from_statement":
+            continue
+
+        text = node_text(child, source)
+        line = child.start_point[0] + 1
+
+        # Extract module path and names from the text via regex
+        import re as _re
+        m = _re.match(r"from\s+(\S+)\s+import\s+(.+)", text)
+        if not m:
+            continue
+
+        module_path = m.group(1)
+        names_str = m.group(2).strip().strip("()")
+        names = [n.strip().split(" as ")[-1].strip() for n in names_str.split(",") if n.strip()]
+
+        if names:
+            imports.append(PyImport(names=names, module_path=module_path, line=line))
+
+    return imports
+
+
+@dataclass
+class PyImport:
+    """A parsed Python from...import statement."""
+    names: list[str]
+    module_path: str
+    line: int
+
+
+# ──────────────────────────────────────────────
+# Generic type parsing
+# ──────────────────────────────────────────────
+
+def parse_generic_type(type_str: str) -> tuple[str, list[str]] | None:
+    """Parse a generic type string into its base type and arguments.
+
+    Examples:
+      "User[]"                     -> ("Array", ["User"])
+      "Array<User>"                -> ("Array", ["User"])
+      "Promise<User>"              -> ("Promise", ["User"])
+      "Pick<User, \\"id\\" | \\"name\\">"  -> ("Pick", ["User", "\\"id\\" | \\"name\\""])
+      "Partial<User>"              -> ("Partial", ["User"])
+      "ApiResponse<User>"          -> ("ApiResponse", ["User"])
+      "Map<string, User>"          -> ("Map", ["string", "User"])
+      "string"                     -> None (not generic)
+
+    Returns (base_type, [args]) or None if not a generic type.
+    """
+    type_str = type_str.strip()
+
+    # Handle array shorthand: User[] -> ("Array", ["User"])
+    if type_str.endswith("[]"):
+        inner = type_str[:-2].strip()
+        if inner:
+            return ("Array", [inner])
+        return None
+
+    # Handle generic syntax: Name<Arg1, Arg2, ...>
+    lt_idx = type_str.find("<")
+    if lt_idx == -1:
+        return None
+
+    base = type_str[:lt_idx].strip()
+    if not base:
+        return None
+
+    # Extract the content between < and the matching >
+    args_str = _extract_between_angles(type_str, lt_idx)
+    if args_str is None:
+        return None
+
+    # Split arguments by top-level commas (respecting nested <> and quotes)
+    args = _split_generic_args(args_str)
+    return (base, args) if args else None
+
+
+def _extract_between_angles(text: str, start: int) -> str | None:
+    """Extract content between < and matching >, respecting nesting."""
+    depth = 0
+    i = start
+    while i < len(text):
+        if text[i] == "<":
+            depth += 1
+        elif text[i] == ">":
+            depth -= 1
+            if depth == 0:
+                return text[start + 1:i].strip()
+        i += 1
+    return None
+
+
+def _split_generic_args(args_str: str) -> list[str]:
+    """Split generic arguments by top-level commas, respecting nested <>, quotes, and |."""
+    parts = []
+    depth = 0
+    current = ""
+    in_string = None
+
+    for ch in args_str:
+        if in_string:
+            current += ch
+            if ch == in_string:
+                in_string = None
+            continue
+
+        if ch in ("'", '"'):
+            in_string = ch
+            current += ch
+        elif ch == "<":
+            depth += 1
+            current += ch
+        elif ch == ">":
+            depth -= 1
+            current += ch
+        elif ch == "," and depth == 0:
+            if current.strip():
+                parts.append(current.strip())
+            current = ""
+        else:
+            current += ch
+
+    if current.strip():
+        parts.append(current.strip())
+    return parts
+
+
+def extract_type_parameters(node: Node, source: bytes) -> list[str]:
+    """Extract type parameter names from an interface or type alias declaration.
+
+    For `interface ApiResponse<T>` returns ["T"].
+    For `type Result<T, E>` returns ["T", "E"].
+    """
+    params = []
+    for child in node.children:
+        if child.type == "type_parameters":
+            for param_node in child.children:
+                if param_node.type == "type_parameter":
+                    name_node = param_node.child_by_field_name("name")
+                    if name_node:
+                        params.append(node_text(name_node, source))
+    return params
+
+
+# ──────────────────────────────────────────────
+# Class method type extraction (for controller handlers)
+# ──────────────────────────────────────────────
+
+@dataclass
+class ClassMethod:
+    """A class method with its request body type annotation."""
+    class_name: str
+    method_name: str
+    request_body_type: str | None
+    file_path: str
+    line: int
+
+
+@dataclass
+class ClassInstance:
+    """A variable instantiated from a class: const x = new ClassName()."""
+    var_name: str
+    class_name: str
+    file_path: str
+    line: int
+
+
+def find_ts_class_methods(node: Node, source: bytes, file_path: str = "") -> list[ClassMethod]:
+    """Find class methods with Request type annotations in their parameters.
+
+    Handles:
+      class UserController {
+        async create(req: Request<{}, {}, CreateUserBody>, res: Response) { ... }
+      }
+    """
+    import re as _re
+    results = []
+
+    for child in node.children:
+        target = child
+        if child.type == "export_statement":
+            for sub in child.children:
+                if sub.type == "class_declaration":
+                    target = sub
+                    break
+
+        if target.type != "class_declaration":
+            continue
+
+        class_name_node = target.child_by_field_name("name")
+        if not class_name_node:
+            continue
+        class_name = node_text(class_name_node, source)
+
+        # Find the class body
+        body = target.child_by_field_name("body")
+        if not body:
+            continue
+
+        for member in body.children:
+            if member.type != "method_definition":
+                continue
+
+            # Get method name
+            method_name = None
+            for sub in member.children:
+                if sub.type == "property_identifier":
+                    method_name = node_text(sub, source)
+                    break
+
+            if not method_name:
+                continue
+
+            # Extract Request<P, Res, Body> from parameters
+            body_type = None
+            params_node = member.child_by_field_name("parameters")
+            if params_node:
+                params_text = node_text(params_node, source)
+                match = _re.search(r':\s*Request\s*<[^,]*,[^,]*,\s*(\w+)\s*>', params_text)
+                if match:
+                    body_type = match.group(1)
+
+            results.append(ClassMethod(
+                class_name=class_name,
+                method_name=method_name,
+                request_body_type=body_type,
+                file_path=file_path,
+                line=member.start_point[0] + 1,
+            ))
+
+    return results
+
+
+def find_ts_class_instances(node: Node, source: bytes, file_path: str = "") -> list[ClassInstance]:
+    """Find variable declarations that instantiate a class.
+
+    Handles:
+      export const projectController = new ProjectController();
+      const controller = new UserController();
+    """
+    results = []
+
+    for child in node.children:
+        target = child
+        if child.type == "export_statement":
+            for sub in child.children:
+                if sub.type == "lexical_declaration":
+                    target = sub
+                    break
+
+        if target.type != "lexical_declaration":
+            continue
+
+        for decl in target.children:
+            if decl.type != "variable_declarator":
+                continue
+
+            name_node = decl.child_by_field_name("name")
+            value_node = decl.child_by_field_name("value")
+            if not name_node or not value_node:
+                continue
+
+            # Check if value is a new_expression: new ClassName()
+            if value_node.type != "new_expression":
+                continue
+
+            var_name = node_text(name_node, source)
+
+            # Extract class name from new ClassName(...)
+            constructor_node = value_node.child_by_field_name("constructor")
+            if constructor_node:
+                class_name = node_text(constructor_node, source)
+            else:
+                # Fallback: first identifier child
+                class_name = None
+                for sub in value_node.children:
+                    if sub.type == "identifier":
+                        class_name = node_text(sub, source)
+                        break
+
+            if class_name:
+                results.append(ClassInstance(
+                    var_name=var_name,
+                    class_name=class_name,
+                    file_path=file_path,
+                    line=decl.start_point[0] + 1,
+                ))
+
+    return results
+
+
+# ──────────────────────────────────────────────
+# Re-export (barrel file) detection
+# ──────────────────────────────────────────────
+
+@dataclass
+class JSReExport:
+    """A re-export statement: export { X } from "./y" or export * from "./y"."""
+    names: list[str]    # ["User", "Post"] or ["*"] for star exports
+    module_path: str    # "./user"
+    line: int
+
+
+def find_js_re_exports(node: Node, source: bytes) -> list[JSReExport]:
+    """Find all re-export statements in a JS/TS file.
+
+    Handles:
+      export { User, Post } from "./types";
+      export { User as AppUser } from "./types";
+      export * from "./helpers";
+    """
+    results = []
+    for child in node.children:
+        if child.type != "export_statement":
+            continue
+
+        # Look for a source module string (the "from" part)
+        module_path = None
+        for sub in child.children:
+            if sub.type == "string":
+                module_path = node_text(sub, source).strip("'\"")
+                break
+
+        if not module_path:
+            continue  # Not a re-export (it's a local export)
+
+        line = child.start_point[0] + 1
+        names = []
+
+        # Check for star export: export * from "./y"
+        child_text = node_text(child, source)
+        if "* from" in child_text or "*from" in child_text:
+            results.append(JSReExport(names=["*"], module_path=module_path, line=line))
+            continue
+
+        # Check for named re-exports: export { X, Y } from "./y"
+        for sub in child.children:
+            if sub.type == "export_clause":
+                for spec in sub.children:
+                    if spec.type == "export_specifier":
+                        name_node = spec.child_by_field_name("name")
+                        alias_node = spec.child_by_field_name("alias")
+                        if name_node:
+                            # Use the original name (not alias) for looking up the definition
+                            exported_name = node_text(alias_node, source) if alias_node else node_text(name_node, source)
+                            names.append(exported_name)
+
+        if names:
+            results.append(JSReExport(names=names, module_path=module_path, line=line))
+
+    return results
+
+
+# ──────────────────────────────────────────────
+# Dynamic URL resolution helpers
+# ──────────────────────────────────────────────
+
+def resolve_url_from_node(node: Node, source: bytes, constants: dict[str, str] | None = None) -> str | None:
+    """Attempt to resolve a URL from various AST node types.
+
+    Handles:
+      - String literals: "/api/users"
+      - Template literals: `/api/users/${id}`
+      - String concatenation: BASE + "/users/" + id
+      - Variable references: BASE_URL (looked up in constants dict)
+
+    Returns a URL pattern string with unresolvable parts replaced by :param,
+    or None if no URL can be extracted.
+    """
+    if constants is None:
+        constants = {}
+
+    if node.type in ("string", "string_fragment"):
+        text = node_text(node, source).strip("'\"`")
+        return text if text else None
+
+    if node.type == "template_string":
+        return _resolve_template_literal(node, source, constants)
+
+    if node.type == "binary_expression":
+        return _resolve_concatenation(node, source, constants)
+
+    if node.type == "identifier":
+        name = node_text(node, source)
+        if name in constants:
+            return constants[name]
+        return None
+
+    if node.type == "member_expression":
+        # process.env.API_URL or similar
+        text = node_text(node, source)
+        if text in constants:
+            return constants[text]
+        return None
+
+    return None
+
+
+def _resolve_template_literal(node: Node, source: bytes, constants: dict[str, str]) -> str | None:
+    """Resolve a template literal like `/api/users/${id}` to a URL pattern.
+
+    Strategy: keep static string fragments, resolve known constants,
+    replace unknown interpolations with :param placeholders.
+    """
+    parts = []
+    for child in node.children:
+        if child.type == "string_fragment":
+            parts.append(node_text(child, source))
+        elif child.type == "template_substitution":
+            # The expression inside ${}
+            expr = None
+            for sub in child.children:
+                if sub.type not in ("${", "}"):
+                    expr = sub
+                    break
+            if expr:
+                expr_text = node_text(expr, source)
+                # Try to resolve from constants
+                if expr_text in constants:
+                    parts.append(constants[expr_text])
+                elif "." in expr_text and expr_text in constants:
+                    parts.append(constants[expr_text])
+                else:
+                    # Unknown variable — use as param placeholder
+                    # Clean up the variable name for a readable param name
+                    param_name = expr_text.split(".")[-1].strip()
+                    if param_name:
+                        parts.append(f":{param_name}")
+                    else:
+                        parts.append(":param")
+        elif child.type in ("`",):
+            continue  # skip the backtick delimiters
+
+    result = "".join(parts)
+    return result if result else None
+
+
+def _resolve_concatenation(node: Node, source: bytes, constants: dict[str, str]) -> str | None:
+    """Resolve a binary expression (string concatenation) to a URL pattern.
+
+    Handles: BASE + "/users/" + id
+    Strategy: flatten the + chain, resolve what we can, placeholder the rest.
+    """
+    parts = _flatten_binary_expression(node, source, constants)
+    if not parts:
+        return None
+
+    result = "".join(parts)
+    # If we got nothing useful (all placeholders, no path-like content), bail
+    if "/" not in result:
+        return None
+    return result
+
+
+def _flatten_binary_expression(node: Node, source: bytes, constants: dict[str, str]) -> list[str]:
+    """Recursively flatten a + concatenation into resolved parts."""
+    if node.type == "binary_expression":
+        # Check operator is +
+        op = None
+        left = node.child_by_field_name("left")
+        right = node.child_by_field_name("right")
+        for child in node.children:
+            if node_text(child, source) == "+":
+                op = "+"
+                break
+        if op != "+":
+            return []
+        left_parts = _flatten_binary_expression(left, source, constants) if left else []
+        right_parts = _flatten_binary_expression(right, source, constants) if right else []
+        return left_parts + right_parts
+
+    if node.type in ("string", "string_fragment"):
+        text = node_text(node, source).strip("'\"`")
+        return [text] if text else []
+
+    if node.type == "template_string":
+        resolved = _resolve_template_literal(node, source, constants)
+        return [resolved] if resolved else []
+
+    if node.type == "identifier":
+        name = node_text(node, source)
+        if name in constants:
+            return [constants[name]]
+        # Unknown variable — use as param placeholder
+        return [f":{name}"]
+
+    if node.type == "member_expression":
+        text = node_text(node, source)
+        if text in constants:
+            return [constants[text]]
+        return [f":{text.split('.')[-1]}"]
+
+    # Unknown node type — try raw text as fallback
+    return []
+
+
+def build_constants_from_file(root_node: Node, source: bytes, env: dict[str, str] | None = None) -> dict[str, str]:
+    """Build a constants dict from top-level const/let assignments in a JS/TS file.
+
+    Resolves:
+      const BASE = "/api"           -> {"BASE": "/api"}
+      const API_URL = process.env.API_URL  -> {"API_URL": env value or ""}
+      const BASE = process.env.NEXT_PUBLIC_API_URL || "/api"  -> {"BASE": env value or "/api"}
+
+    Also includes env vars with their process.env.X full names.
+    """
+    constants: dict[str, str] = {}
+    if env is None:
+        env = {}
+
+    # Add process.env.* entries from .env files
+    for key, value in env.items():
+        constants[f"process.env.{key}"] = value
+        constants[f"import.meta.env.{key}"] = value
+
+    # Scan top-level variable declarations
+    for child in root_node.children:
+        _extract_const_declarations(child, source, constants, env)
+
+    return constants
+
+
+def _extract_const_declarations(node: Node, source: bytes, constants: dict[str, str], env: dict[str, str]) -> None:
+    """Extract const/let declarations with string literal or env var values."""
+    # Handle: const X = "value" or export const X = "value"
+    target = node
+    if node.type == "export_statement":
+        for sub in node.children:
+            if sub.type == "lexical_declaration":
+                target = sub
+                break
+
+    if target.type != "lexical_declaration":
+        return
+
+    for decl in target.children:
+        if decl.type != "variable_declarator":
+            continue
+
+        name_node = decl.child_by_field_name("name")
+        value_node = decl.child_by_field_name("value")
+
+        if not name_node or not value_node:
+            continue
+
+        name = node_text(name_node, source)
+
+        # Direct string literal: const BASE = "/api"
+        if value_node.type in ("string",):
+            val = node_text(value_node, source).strip("'\"`")
+            if val:
+                constants[name] = val
+            continue
+
+        # process.env.VAR reference
+        if value_node.type == "member_expression":
+            ref = node_text(value_node, source)
+            if ref.startswith(("process.env.", "import.meta.env.")):
+                var_key = ref.split(".")[-1]
+                if var_key in env:
+                    constants[name] = env[var_key]
+                    constants[ref] = env[var_key]
+            continue
+
+        # Logical OR fallback: process.env.VAR || "/default"
+        if value_node.type == "binary_expression":
+            val_text = node_text(value_node, source)
+            # Pattern: process.env.X || "/fallback"
+            import re as _re
+            m = _re.match(r'(process\.env\.\w+|import\.meta\.env\.\w+)\s*\|\|\s*["\']([^"\']+)["\']', val_text)
+            if m:
+                env_ref = m.group(1)
+                fallback = m.group(2)
+                var_key = env_ref.split(".")[-1]
+                resolved = env.get(var_key, fallback)
+                constants[name] = resolved
+                constants[env_ref] = resolved
+            continue