graphlens-typescript 0.2.2__tar.gz → 0.4.0__tar.gz

{graphlens_typescript-0.2.2 → graphlens_typescript-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: graphlens-typescript
-Version: 0.2.2
+Version: 0.4.0
 Summary: TypeScript language adapter for graphlens
 Requires-Dist: graphlens
 Requires-Dist: tree-sitter>=0.24

{graphlens_typescript-0.2.2 → graphlens_typescript-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphlens-typescript"
-version = "0.2.2"
+version = "0.4.0"
 description = "TypeScript language adapter for graphlens"
 requires-python = ">=3.13"
 dependencies = [
@@ -12,6 +12,8 @@ dependencies = [
 [build-system]
 requires = ["uv_build>=0.9.18,<0.12.0"]
 build-backend = "uv_build"
+# uv_build ships all files under src/graphlens_typescript/ by default,
+# so ts_resolver.js is included in the wheel without an explicit include rule.
 
 [tool.uv.sources]
 graphlens = { workspace = true }

{graphlens_typescript-0.2.2 → graphlens_typescript-0.4.0}/src/graphlens_typescript/__init__.py

@@ -1,5 +1,6 @@
 """graphlens_typescript — TypeScript language adapter for graphlens."""
 
 from graphlens_typescript._adapter import TypescriptAdapter
+from graphlens_typescript._resolver import TsResolver
 
-__all__ = ["TypescriptAdapter"]
+__all__ = ["TsResolver", "TypescriptAdapter"]

{graphlens_typescript-0.2.2 → graphlens_typescript-0.4.0}/src/graphlens_typescript/_adapter.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from graphlens import (
@@ -13,7 +14,8 @@ from graphlens import (
     Relation,
     RelationKind,
 )
-from graphlens.utils import make_node_id
+from graphlens.utils import SpanIndex, make_node_id
+from graphlens.utils.roots import filter_nested_root_files
 
 from graphlens_typescript._deps import (
     TYPESCRIPT_DEFAULT_DEP_PARSERS,
@@ -22,23 +24,24 @@ from graphlens_typescript._deps import (
 from graphlens_typescript._module_resolver import (
     file_to_qualified_name,
     find_source_roots,
+    load_tsconfig_path_aliases,
 )
 from graphlens_typescript._project_detector import (
     detect_project_name,
     find_typescript_roots,
     is_typescript_project,
 )
+from graphlens_typescript._resolver import TsResolver
 from graphlens_typescript._visitor import (
     ImportClassifier,
+    OccurrenceRef,
     TypescriptASTVisitor,
     VisitorContext,
     parse_typescript,
 )
 
 if TYPE_CHECKING:
-    from pathlib import Path
-
-    from graphlens.contracts import DependencyFileParser
+    from graphlens.contracts import DependencyFileParser, SymbolResolver
 
 logger = logging.getLogger("graphlens_typescript")
 
@@ -47,6 +50,18 @@ _STDLIB = get_stdlib_names()
 # Declaration files contain only type information — skip them during analysis
 _DECLARATION_SUFFIXES: tuple[str, ...] = (".d.ts", ".d.mts", ".d.cts")
 
+# ---------------------------------------------------------------------------
+# Role → RelationKind mapping
+# ---------------------------------------------------------------------------
+
+_ROLE_TO_KIND: dict[str, RelationKind] = {
+    "call": RelationKind.CALLS,
+    "base": RelationKind.INHERITS_FROM,
+    "annotation": RelationKind.HAS_TYPE,
+    "read": RelationKind.REFERENCES,
+    "write": RelationKind.REFERENCES,
+}
+
 
 class TypescriptAdapter(LanguageAdapter):
     """Language adapter for TypeScript projects."""
@@ -54,6 +69,7 @@ class TypescriptAdapter(LanguageAdapter):
     def __init__(
         self,
         dep_parsers: list[DependencyFileParser] | None = None,
+        resolver: SymbolResolver | None = None,
     ) -> None:
         """
         Initialize the TypeScript adapter.
@@ -63,6 +79,10 @@ class TypescriptAdapter(LanguageAdapter):
                 names from manifest files. Pass a custom list to support
                 non-standard package managers.
                 Defaults to ``TYPESCRIPT_DEFAULT_DEP_PARSERS``.
+            resolver: symbol resolver used for cross-file resolution of
+                calls, references, annotations, and base classes.
+                Defaults to ``TsResolver``. Inject a custom or null
+                resolver to override resolution behaviour.
 
         """
         self._dep_parsers = (
@@ -70,14 +90,20 @@ class TypescriptAdapter(LanguageAdapter):
             if dep_parsers is not None
             else TYPESCRIPT_DEFAULT_DEP_PARSERS
         )
+        self._resolver: SymbolResolver = (
+            resolver if resolver is not None else TsResolver()
+        )
 
     def language(self) -> str:
+        """Return the language identifier for this adapter."""
         return "typescript"
 
     def file_extensions(self) -> set[str]:
+        """Return the set of file extensions handled by this adapter."""
         return {".ts", ".tsx", ".mts", ".cts"}
 
     def can_handle(self, project_root: Path) -> bool:
+        """Return True if the project root is a TypeScript project."""
         return is_typescript_project(project_root)
 
     def collect_files(self, project_root: Path) -> list[Path]:
@@ -98,6 +124,18 @@ class TypescriptAdapter(LanguageAdapter):
         project_root: Path,
         files: list[Path] | None = None,
     ) -> GraphLens:
+        """
+        Analyze a TypeScript project and return a populated GraphLens.
+
+        Args:
+            project_root: the root directory of the project (or monorepo).
+            files: optional explicit list of files to analyze; when omitted
+                all TypeScript source files are collected automatically.
+
+        Returns:
+            A ``GraphLens`` containing the structural and relational nodes.
+
+        """
         graph = GraphLens()
 
         if files is not None:
@@ -107,27 +145,142 @@ class TypescriptAdapter(LanguageAdapter):
                 project_root,
                 files,
                 self._dep_parsers,
+                self._resolver,
             )
         else:
-            for lang_root in find_typescript_roots(project_root):
+            lang_roots = find_typescript_roots(project_root)
+            for lang_root in lang_roots:
                 root_files = self.collect_files(lang_root)
+                root_files = filter_nested_root_files(
+                    root_files,
+                    lang_root,
+                    lang_roots,
+                )
                 _analyze_root(
                     graph,
                     project_root,
                     lang_root,
                     root_files,
                     self._dep_parsers,
+                    self._resolver,
                 )
 
         return graph
 
 
-def _analyze_root(
+def _ensure_external_symbol(
+    graph: GraphLens, project_name: str, qname: str, origin: str
+) -> str:
+    """
+    Return the id of an EXTERNAL_SYMBOL node for ``qname``.
+
+    Creates the node if it does not yet exist in ``graph``.
+
+    Args:
+        graph: the graph to update in-place.
+        project_name: used as the namespace for ``make_node_id``.
+        qname: fully-qualified name of the external symbol.
+        origin: one of ``"stdlib"``, ``"third_party"``, ``"unknown"``,
+            or ``"internal"`` (fallback when the module node is absent).
+
+    Returns:
+        The node id of the EXTERNAL_SYMBOL.
+
+    """
+    sym_id = make_node_id(
+        project_name, qname, NodeKind.EXTERNAL_SYMBOL.value
+    )
+    if sym_id not in graph.nodes:
+        graph.add_node(
+            Node(
+                id=sym_id,
+                kind=NodeKind.EXTERNAL_SYMBOL,
+                qualified_name=qname,
+                name=qname.rsplit(".", maxsplit=1)[-1],
+                metadata={"origin": origin},
+            )
+        )
+    return sym_id
+
+
+def _resolve_occurrences(
+    graph: GraphLens,
+    project_name: str,
+    resolver: SymbolResolver,
+    span_index: SpanIndex,
+    occurrences: list[tuple[str, OccurrenceRef]],
+) -> None:
+    """
+    Resolve all accumulated occurrences and emit edges (batched).
+
+    Collects all (file, line, col) queries in one list, issues a single
+    ``resolver.resolve_all(queries)`` call, then maps results back to
+    graph edges.
+
+    For each ``(abs_path, occ)`` pair:
+
+    1. Receive the definition site from the batch result.
+    2. If ``ref is None`` — skip.
+    3. If the definition is internal, look up the target node id via
+       ``span_index.at()``.
+    4. If the node is not found (or origin is external), create/reuse an
+       ``EXTERNAL_SYMBOL`` fallback node.
+    5. Emit a ``Relation`` of the appropriate kind, with span metadata
+       and, for read/write occurrences, an ``access`` key.
+
+    Args:
+        graph: the graph to update in-place.
+        project_name: namespace used for EXTERNAL_SYMBOL node ids.
+        resolver: the symbol resolver that was already ``prepare()``d.
+        span_index: pre-built index of node spans from ``graph``.
+        occurrences: list of ``(absolute_file_path, OccurrenceRef)`` pairs
+            collected during the file-visit loop.
+
+    """
+    queries: list[tuple[Path, int, int]] = [
+        (Path(p), o.line, o.col) for (p, o) in occurrences
+    ]
+    refs = resolver.resolve_all(queries)
+    for (_p, occ), ref in zip(occurrences, refs, strict=True):
+        if ref is None:
+            continue
+        target_id: str | None = None
+        if ref.origin == "internal" and ref.file_path is not None:
+            target_id = span_index.at(
+                str(ref.file_path), ref.line, ref.col
+            )
+        if target_id is None:
+            fallback_qname = (
+                ref.full_name
+                if ref.full_name
+                else f"{occ.role}@{occ.line}:{occ.col}"
+            )
+            target_id = _ensure_external_symbol(
+                graph,
+                project_name,
+                fallback_qname,
+                ref.origin,
+            )
+        metadata: dict[str, object] = {"span": occ.span}
+        if occ.role in ("read", "write"):
+            metadata["access"] = occ.role
+        graph.add_relation(
+            Relation(
+                source_id=occ.enclosing_id,
+                target_id=target_id,
+                kind=_ROLE_TO_KIND[occ.role],
+                metadata=metadata,
+            )
+        )
+
+
+def _analyze_root(  # noqa: PLR0913, PLR0915
     graph: GraphLens,
     project_root: Path,
     lang_root: Path,
     files: list[Path],
     dep_parsers: list[DependencyFileParser],
+    resolver: SymbolResolver,
 ) -> None:
     """Analyze one TypeScript project root and populate graph in-place."""
     project_name = detect_project_name(lang_root)
@@ -149,6 +302,14 @@ def _analyze_root(
         if parser.can_parse(lang_root):
             third_party.update(parser.parse(lang_root))
 
+    # BUG 2 fix: root-level config files (e.g. next.config.ts) can contribute
+    # names like "next" or "sentry" to internal_tops.  When a name is also a
+    # declared third-party package, the package.json is authoritative.
+    internal_tops = {t for t in internal_tops if t not in third_party}
+
+    # Load tsconfig path aliases once per root (BUG 1 fix)
+    path_aliases = load_tsconfig_path_aliases(lang_root)
+
     classifier = ImportClassifier(
         stdlib=_STDLIB,
         third_party=frozenset(third_party),
@@ -169,6 +330,7 @@ def _analyze_root(
         )
 
     modules: dict[str, str] = {}
+    all_occurrences: list[tuple[str, OccurrenceRef]] = []
 
     for file in files:
         source_root = (
@@ -233,11 +395,22 @@ def _analyze_root(
             source_root=source_root,
             module_qualified_name=module_qname,
             modules=modules,
+            path_aliases=path_aliases,
         )
         visitor = TypescriptASTVisitor(
             ctx, graph, file_id, source_bytes, classifier
         )
         visitor.visit(tree.root_node)
+        all_occurrences.extend(
+            (visitor.abs_file_path, o) for o in visitor.occurrences
+        )
+
+    # Resolution pass: bind occurrences to real nodes or EXTERNAL_SYMBOL
+    span_index = SpanIndex.from_graph(graph)
+    resolver.prepare(lang_root, files)
+    _resolve_occurrences(
+        graph, project_name, resolver, span_index, all_occurrences
+    )
 
     # PROJECT --CONTAINS--> top-level modules
     top_level = {qn: mid for qn, mid in modules.items() if "." not in qn}

{graphlens_typescript-0.2.2 → graphlens_typescript-0.4.0}/src/graphlens_typescript/_module_resolver.py

@@ -2,12 +2,24 @@
 
 from __future__ import annotations
 
+import json
+import re
 from pathlib import Path
 
+# Matches "prefix/*": ["./target/*"] — single target, glob on both sides
+_ALIAS_RE = re.compile(
+    r'"([^"]+)/\*"\s*:\s*\[\s*"\./([^"]*)/\*"\s*\]'
+)
+
 # Extensions to strip when converting file path to module name
-_TS_EXTENSIONS: frozenset[str] = frozenset({
-    ".ts", ".tsx", ".mts", ".cts",
-})
+_TS_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        ".ts",
+        ".tsx",
+        ".mts",
+        ".cts",
+    }
+)
 
 # Files that represent the package root (like __init__.py in Python)
 _INDEX_STEMS: frozenset[str] = frozenset({"index"})
@@ -17,19 +29,70 @@ def find_source_roots(project_root: Path, files: list[Path]) -> list[Path]:
     """
     Detect TypeScript source roots.
 
-    Prefers a ``src/`` sub-directory when source files live there.
-    Falls back to ``project_root``.
+    Prefers a ``src/`` sub-directory when source files live there,
+    but also includes ``project_root`` for files outside ``src/``.
+    Falls back to ``[project_root]`` for non-src-layout projects.
     """
     src = project_root / "src"
-    if (
-        src.is_dir()
-        and files
-        and any(f.is_relative_to(src) for f in files)
-    ):
-        return [src]
+    if src.is_dir() and files and any(f.is_relative_to(src) for f in files):
+        return [src, project_root]
     return [project_root]
 
 
+def load_tsconfig_path_aliases(project_root: Path) -> dict[str, str]:
+    """
+    Read ``tsconfig.json`` and return a prefix-alias map.
+
+    Extracts ``compilerOptions.paths`` entries of the form
+    ``"<prefix>/*": ["<target>/*"]`` and converts them to
+    ``{"<prefix>/": "<target>/"}`` (stripping the ``/*`` glob and
+    leading ``./``).  Multi-target entries and non-glob patterns are
+    silently ignored.  Returns ``{}`` on any error — never raises.
+    """
+    tsconfig = project_root / "tsconfig.json"
+    try:
+        raw = tsconfig.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    try:
+        # Strip // line comments and trailing commas before parsing
+        clean = re.sub(r"//[^\n]*", "", raw)
+        clean = re.sub(r",(\s*[}\]])", r"\1", clean)
+        data = json.loads(clean)
+        paths = data.get("compilerOptions", {}).get("paths", {})
+        if not isinstance(paths, dict):
+            return {}
+    except Exception:
+        return {}
+    aliases: dict[str, str] = {}
+    for alias_pattern, targets in paths.items():
+        if not alias_pattern.endswith("/*"):
+            continue
+        if not isinstance(targets, list) or len(targets) != 1:
+            continue
+        target = targets[0]
+        if not isinstance(target, str) or not target.endswith("/*"):
+            continue
+        alias_prefix = alias_pattern[:-1]  # strip trailing *
+        target_prefix = target.lstrip("./")[:-1]  # strip ./ and trailing *
+        aliases[alias_prefix] = target_prefix
+    return aliases
+
+
+def apply_path_alias(import_path: str, aliases: dict[str, str]) -> str:
+    """
+    Rewrite ``import_path`` if it matches a tsconfig path alias prefix.
+
+    For example, with ``aliases = {"@/": "src/"}``, rewrites
+    ``"@/client/v2"`` → ``"src/client/v2"``.
+    Returns ``import_path`` unchanged when no alias prefix matches.
+    """
+    for prefix, target in aliases.items():
+        if import_path.startswith(prefix):
+            return target + import_path[len(prefix):]
+    return import_path
+
+
 def file_to_qualified_name(file_path: Path, source_root: Path) -> str:
     """
     Convert a TypeScript file path to a dotted module qualified name.

{graphlens_typescript-0.2.2 → graphlens_typescript-0.4.0}/src/graphlens_typescript/_project_detector.py

@@ -6,6 +6,8 @@ import json
 import re
 from typing import TYPE_CHECKING
 
+from graphlens.utils import collect_marker_roots
+
 if TYPE_CHECKING:
     from pathlib import Path
 
@@ -42,26 +44,30 @@ def find_typescript_roots(search_root: Path) -> list[Path]:
     """
     Find TypeScript project roots within search_root (monorepo support).
 
-    Returns [search_root] if search_root itself has markers.
-    Otherwise walks subdirectories for marker files and returns distinct roots.
-    Falls back to [search_root] if nothing found.
+    A marker at ``search_root`` does not hide nested package roots.
+    ``tsconfig`` files inside an existing ``package.json`` root are treated as
+    that package's config rather than as independent roots.
     """
-    if _has_typescript_markers(search_root):
-        return [search_root]
-
-    roots: list[Path] = []
-    for marker in TYPESCRIPT_MARKERS:
-        for marker_file in sorted(search_root.rglob(marker)):
-            rel_parts = marker_file.relative_to(search_root).parts
-            if _EXCLUDED_DIRS & set(rel_parts):
-                continue
-            candidate = marker_file.parent
-            if any(
-                candidate == r or candidate.is_relative_to(r)
-                for r in roots
-            ):
-                continue
-            roots.append(candidate)
+    package_roots = collect_marker_roots(
+        search_root,
+        ("package.json",),
+        excluded_dirs=_EXCLUDED_DIRS,
+        fallback_to_search_root=False,
+    )
+    tsconfig_roots = collect_marker_roots(
+        search_root,
+        ("tsconfig.json",),
+        excluded_dirs=_EXCLUDED_DIRS,
+        fallback_to_search_root=False,
+    )
+
+    roots = list(package_roots)
+    for tsconfig_root in tsconfig_roots:
+        if tsconfig_root in roots:
+            continue
+        if any(tsconfig_root.is_relative_to(root) for root in package_roots):
+            continue
+        roots.append(tsconfig_root)
 
     return sorted(roots) if roots else [search_root]
 

graphlens_typescript-0.4.0/src/graphlens_typescript/_resolver.py

@@ -0,0 +1,137 @@
+"""TypeScript type-aware resolver via a Node subprocess (Compiler API)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess  # nosec B404
+from importlib.resources import files as _pkg_files
+from pathlib import Path
+
+from graphlens.contracts import Occurrence, ResolvedRef, SymbolResolver
+
+logger = logging.getLogger("graphlens_typescript")
+
+_TS_VERSION = "5.8.3"
+Query = tuple[Path, int, int]  # (absolute file, 1-based line, 1-based col)
+
+_BRIDGE_JS = "ts_resolver.js"
+
+
+def _cache_root() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / "graphlens" / "ts-resolver"
+
+
+class TsResolver(SymbolResolver):
+    """Resolves TS symbols via a bundled Node script. Never raises."""
+
+    def __init__(self, ts_version: str = _TS_VERSION) -> None:
+        """Initialise resolver with a pinned typescript version."""
+        self._ts_version = ts_version
+        self._root: Path | None = None
+        self._cache_dir: Path = _cache_root() / ts_version
+        self._disabled = False
+
+    def prepare(self, project_root: Path, files: list[Path]) -> None:  # noqa: ARG002
+        """Set up the engine for a project before any queries."""
+        self._root = project_root
+        try:
+            self.ensure_typescript()
+        except Exception:
+            logger.warning("TsResolver disabled: typescript unavailable")
+            self._disabled = True
+
+    def ensure_typescript(self) -> None:
+        """Install typescript into the cache dir if not already present."""
+        sentinel = (
+            self._cache_dir / "node_modules" / "typescript"
+            / "lib" / "typescript.js"
+        )
+        if sentinel.exists():
+            return
+        if shutil.which("node") is None or shutil.which("npm") is None:
+            msg = "node/npm not found"
+            raise RuntimeError(msg)
+        self._cache_dir.mkdir(parents=True, exist_ok=True)
+        (self._cache_dir / "package.json").write_text('{"private":true}')
+        subprocess.run(  # nosec B603 B607
+            ["npm", "install",  # noqa: S607
+             f"typescript@{self._ts_version}",
+             "--no-save", "--no-audit", "--prefer-offline"],
+            cwd=str(self._cache_dir),
+            check=True, capture_output=True, timeout=300,
+        )
+
+    def resolve_all(
+        self, queries: list[Query]
+    ) -> list[ResolvedRef | None]:
+        """Resolve a batch of positions; never raises."""
+        if self._disabled or not queries or self._root is None:
+            return [None] * len(queries)
+        try:
+            payload = self._run_bridge(self._build_request(queries))
+            return self._parse_response(payload)
+        except Exception:
+            logger.warning("TsResolver batch failed; degrading to None")
+            return [None] * len(queries)
+
+    def definition_at(
+        self, file: Path, line: int, col: int
+    ) -> ResolvedRef | None:
+        """Resolve the symbol at a position to its definition (cross-file)."""
+        return self.resolve_all([(file, line, col)])[0]
+
+    def infer_type_at(
+        self, file: Path, line: int, col: int
+    ) -> ResolvedRef | None:
+        """Infer the type of the expression at a position."""
+        return self.resolve_all([(file, line, col)])[0]
+
+    def references_to(self, file: Path, line: int, col: int) -> list[Occurrence]:  # noqa: ARG002, E501
+        """Return all references to the symbol at a position."""
+        return []  # references batch not used by the resolution pass; deferred
+
+    def _build_request(self, queries: list[Query]) -> dict:
+        """Build the JSON request payload for the Node bridge."""
+        return {
+            "project_root": str(self._root),
+            "queries": [
+                {"file": str(f), "line": ln, "col": c}
+                for (f, ln, c) in queries
+            ],
+        }
+
+    def _parse_response(
+        self, payload: dict
+    ) -> list[ResolvedRef | None]:
+        """Map the bridge JSON response to a list of ResolvedRef or None."""
+        out: list[ResolvedRef | None] = []
+        for item in payload.get("results", []):
+            if not item:
+                out.append(None)
+                continue
+            out.append(ResolvedRef(
+                full_name=item.get("name", ""),
+                file_path=Path(item["file"]) if item.get("file") else None,
+                line=item.get("line", 1),
+                col=item.get("col", 1),
+                kind=item.get("kind", "unknown"),
+                origin=item.get("origin", "unknown"),
+            ))
+        return out
+
+    def _run_bridge(self, request: dict) -> dict:
+        """Invoke the Node bridge as a subprocess, return parsed JSON."""
+        bridge = _pkg_files("graphlens_typescript") / _BRIDGE_JS
+        env = dict(os.environ, TS_CACHE_DIR=str(self._cache_dir))
+        completed = subprocess.run(  # nosec B603 B607
+            ["node", str(bridge)],  # noqa: S607
+            input=json.dumps(request),
+            capture_output=True, text=True, env=env,
+            cwd=str(self._root), timeout=600, check=False,
+        )
+        return json.loads(completed.stdout)