graphlens-typescript 0.2.2__py3-none-any.whl

graphlens_typescript/__init__.py

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

graphlens_typescript/_adapter.py

@@ -0,0 +1,304 @@
+"""TypescriptAdapter — orchestrates TypeScript project analysis."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from graphlens import (
+    GraphLens,
+    LanguageAdapter,
+    Node,
+    NodeKind,
+    Relation,
+    RelationKind,
+)
+from graphlens.utils import make_node_id
+
+from graphlens_typescript._deps import (
+    TYPESCRIPT_DEFAULT_DEP_PARSERS,
+    get_stdlib_names,
+)
+from graphlens_typescript._module_resolver import (
+    file_to_qualified_name,
+    find_source_roots,
+)
+from graphlens_typescript._project_detector import (
+    detect_project_name,
+    find_typescript_roots,
+    is_typescript_project,
+)
+from graphlens_typescript._visitor import (
+    ImportClassifier,
+    TypescriptASTVisitor,
+    VisitorContext,
+    parse_typescript,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from graphlens.contracts import DependencyFileParser
+
+logger = logging.getLogger("graphlens_typescript")
+
+_STDLIB = get_stdlib_names()
+
+# Declaration files contain only type information — skip them during analysis
+_DECLARATION_SUFFIXES: tuple[str, ...] = (".d.ts", ".d.mts", ".d.cts")
+
+
+class TypescriptAdapter(LanguageAdapter):
+    """Language adapter for TypeScript projects."""
+
+    def __init__(
+        self,
+        dep_parsers: list[DependencyFileParser] | None = None,
+    ) -> None:
+        """
+        Initialize the TypeScript adapter.
+
+        Args:
+            dep_parsers: parsers used to extract third-party dependency
+                names from manifest files. Pass a custom list to support
+                non-standard package managers.
+                Defaults to ``TYPESCRIPT_DEFAULT_DEP_PARSERS``.
+
+        """
+        self._dep_parsers = (
+            dep_parsers
+            if dep_parsers is not None
+            else TYPESCRIPT_DEFAULT_DEP_PARSERS
+        )
+
+    def language(self) -> str:
+        return "typescript"
+
+    def file_extensions(self) -> set[str]:
+        return {".ts", ".tsx", ".mts", ".cts"}
+
+    def can_handle(self, project_root: Path) -> bool:
+        return is_typescript_project(project_root)
+
+    def collect_files(self, project_root: Path) -> list[Path]:
+        """
+        Collect TypeScript source files, excluding declaration files.
+
+        Declaration files (``.d.ts``, ``.d.mts``, ``.d.cts``) contain only
+        type information and no implementation — they are skipped.
+        """
+        files = super().collect_files(project_root)
+        return [
+            f for f in files
+            if not any(str(f).endswith(suf) for suf in _DECLARATION_SUFFIXES)
+        ]
+
+    def analyze(
+        self,
+        project_root: Path,
+        files: list[Path] | None = None,
+    ) -> GraphLens:
+        graph = GraphLens()
+
+        if files is not None:
+            _analyze_root(
+                graph,
+                project_root,
+                project_root,
+                files,
+                self._dep_parsers,
+            )
+        else:
+            for lang_root in find_typescript_roots(project_root):
+                root_files = self.collect_files(lang_root)
+                _analyze_root(
+                    graph,
+                    project_root,
+                    lang_root,
+                    root_files,
+                    self._dep_parsers,
+                )
+
+        return graph
+
+
+def _analyze_root(
+    graph: GraphLens,
+    project_root: Path,
+    lang_root: Path,
+    files: list[Path],
+    dep_parsers: list[DependencyFileParser],
+) -> None:
+    """Analyze one TypeScript project root and populate graph in-place."""
+    project_name = detect_project_name(lang_root)
+    source_roots = find_source_roots(lang_root, files)
+
+    # Pre-pass: collect internal top-level names from file paths (no parsing)
+    internal_tops: set[str] = set()
+    for f in files:
+        sr = _find_source_root_for(f, source_roots) or source_roots[0]
+        try:
+            qname = file_to_qualified_name(f, sr)
+            internal_tops.add(qname.split(".")[0])
+        except ValueError:
+            pass
+
+    # Parse dependency manifests
+    third_party: set[str] = set()
+    for parser in dep_parsers:
+        if parser.can_parse(lang_root):
+            third_party.update(parser.parse(lang_root))
+
+    classifier = ImportClassifier(
+        stdlib=_STDLIB,
+        third_party=frozenset(third_party),
+        internal=frozenset(internal_tops),
+    )
+
+    project_id = make_node_id(
+        project_name, project_name, NodeKind.PROJECT.value
+    )
+    if project_id not in graph.nodes:
+        graph.add_node(
+            Node(
+                id=project_id,
+                kind=NodeKind.PROJECT,
+                qualified_name=project_name,
+                name=project_name,
+            )
+        )
+
+    modules: dict[str, str] = {}
+
+    for file in files:
+        source_root = (
+            _find_source_root_for(file, source_roots) or source_roots[0]
+        )
+
+        try:
+            module_qname = file_to_qualified_name(file, source_root)
+        except ValueError:
+            logger.warning(
+                "Cannot compute qualified name for %s, skipping", file
+            )
+            continue
+
+        _ensure_module_chain(graph, project_name, module_qname, modules)
+
+        try:
+            relative_path = str(file.relative_to(project_root))
+        except ValueError:
+            relative_path = str(file.relative_to(lang_root))
+
+        file_id = make_node_id(
+            project_name, relative_path, NodeKind.FILE.value
+        )
+        if file_id not in graph.nodes:
+            graph.add_node(
+                Node(
+                    id=file_id,
+                    kind=NodeKind.FILE,
+                    qualified_name=relative_path,
+                    name=file.name,
+                    file_path=relative_path,
+                )
+            )
+            leaf_module_id = modules[module_qname]
+            graph.add_relation(
+                Relation(
+                    source_id=leaf_module_id,
+                    target_id=file_id,
+                    kind=RelationKind.CONTAINS,
+                )
+            )
+
+        try:
+            source_bytes = file.read_bytes()
+        except OSError as e:
+            logger.warning("Cannot read %s: %s — skipping", file, e)
+            continue
+
+        is_tsx = file.suffix.lower() == ".tsx"
+        tree = parse_typescript(source_bytes, tsx=is_tsx)
+        if tree.root_node.has_error:
+            logger.warning(
+                "Parse errors in %s — continuing with partial results",
+                file,
+            )
+
+        ctx = VisitorContext(
+            project_name=project_name,
+            file_path=file,
+            file_relative_path=relative_path,
+            source_root=source_root,
+            module_qualified_name=module_qname,
+            modules=modules,
+        )
+        visitor = TypescriptASTVisitor(
+            ctx, graph, file_id, source_bytes, classifier
+        )
+        visitor.visit(tree.root_node)
+
+    # PROJECT --CONTAINS--> top-level modules
+    top_level = {qn: mid for qn, mid in modules.items() if "." not in qn}
+    for module_id in top_level.values():
+        graph.add_relation(
+            Relation(
+                source_id=project_id,
+                target_id=module_id,
+                kind=RelationKind.CONTAINS,
+            )
+        )
+
+
+def _find_source_root_for(file: Path, source_roots: list[Path]) -> Path | None:
+    for root in source_roots:
+        try:
+            file.relative_to(root)
+            return root
+        except ValueError:
+            continue
+    return None
+
+
+def _ensure_module_chain(
+    graph: GraphLens,
+    project_name: str,
+    module_qname: str,
+    modules: dict[str, str],
+) -> str:
+    """
+    Ensure MODULE nodes exist for the full chain a.b.c.
+
+    Returns the node ID of the leaf module.
+    Creates CONTAINS relations between parent and child modules.
+    """
+    parts = module_qname.split(".")
+    parent_id: str | None = None
+
+    for i in range(1, len(parts) + 1):
+        qname = ".".join(parts[:i])
+        if qname not in modules:
+            node_id = make_node_id(project_name, qname, NodeKind.MODULE.value)
+            graph.add_node(
+                Node(
+                    id=node_id,
+                    kind=NodeKind.MODULE,
+                    qualified_name=qname,
+                    name=parts[i - 1],
+                )
+            )
+            modules[qname] = node_id
+
+            if parent_id is not None:
+                graph.add_relation(
+                    Relation(
+                        source_id=parent_id,
+                        target_id=node_id,
+                        kind=RelationKind.CONTAINS,
+                    )
+                )
+
+        parent_id = modules[qname]
+
+    return modules[module_qname]

graphlens_typescript/_deps.py

@@ -0,0 +1,117 @@
+"""Dependency file parsers for TypeScript / Node.js projects."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from graphlens.contracts import DependencyFileParser, normalize_pkg_name
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Package.json parser
+# ---------------------------------------------------------------------------
+
+
+class PackageJsonParser(DependencyFileParser):
+    """
+    Reads declared dependencies from ``package.json``.
+
+    Includes ``dependencies``, ``devDependencies``, ``peerDependencies``,
+    and ``optionalDependencies`` so that test-only and peer imports are
+    classified as ``third_party`` rather than ``unknown``.
+    """
+
+    def can_parse(self, project_root: Path) -> bool:
+        return (project_root / "package.json").exists()
+
+    def parse(self, project_root: Path) -> frozenset[str]:
+        path = project_root / "package.json"
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            return frozenset()
+
+        names: set[str] = set()
+        for section in (
+            "dependencies",
+            "devDependencies",
+            "peerDependencies",
+            "optionalDependencies",
+        ):
+            for dep in data.get(section, {}):
+                n = normalize_pkg_name(dep)
+                if n:
+                    names.add(n)
+        return frozenset(names)
+
+
+# ---------------------------------------------------------------------------
+# Default parser list
+# ---------------------------------------------------------------------------
+
+TYPESCRIPT_DEFAULT_DEP_PARSERS: list[DependencyFileParser] = [
+    PackageJsonParser(),
+]
+
+
+# ---------------------------------------------------------------------------
+# Node.js stdlib / built-in module names
+# ---------------------------------------------------------------------------
+
+def get_stdlib_names() -> frozenset[str]:
+    """
+    Return top-level module names that ship with Node.js.
+
+    These are the importable names callers use, without the ``node:``
+    scheme prefix (e.g. ``"fs"``, not ``"node:fs"``).  The adapter strips
+    ``node:`` prefixes from import paths before calling
+    ``ImportClassifier.classify()``, so plain names are sufficient.
+    """
+    return frozenset({
+        # Core Node.js built-in modules (stable API)
+        "assert",
+        "async_hooks",
+        "buffer",
+        "child_process",
+        "cluster",
+        "console",
+        "constants",
+        "crypto",
+        "dgram",
+        "diagnostics_channel",
+        "dns",
+        "domain",
+        "events",
+        "fs",
+        "http",
+        "http2",
+        "https",
+        "inspector",
+        "module",
+        "net",
+        "os",
+        "path",
+        "perf_hooks",
+        "process",
+        "punycode",
+        "querystring",
+        "readline",
+        "repl",
+        "stream",
+        "string_decoder",
+        "sys",
+        "timers",
+        "tls",
+        "trace_events",
+        "tty",
+        "url",
+        "util",
+        "v8",
+        "vm",
+        "wasi",
+        "worker_threads",
+        "zlib",
+    })

graphlens_typescript/_module_resolver.py

@@ -0,0 +1,114 @@
+"""Module qualified name resolution and source root detection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Extensions to strip when converting file path to module name
+_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"})
+
+
+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``.
+    """
+    src = project_root / "src"
+    if (
+        src.is_dir()
+        and files
+        and any(f.is_relative_to(src) for f in files)
+    ):
+        return [src]
+    return [project_root]
+
+
+def file_to_qualified_name(file_path: Path, source_root: Path) -> str:
+    """
+    Convert a TypeScript file path to a dotted module qualified name.
+
+    Examples:
+      src/mypackage/index.ts   ->  ``"mypackage"``
+      src/mypackage/utils.ts   ->  ``"mypackage.utils"``
+      src/mypackage/ui.tsx     ->  ``"mypackage.ui"``
+
+    Declaration files (.d.ts) follow the same mapping — they are filtered
+    out at the adapter level, but the resolver handles them correctly.
+
+    """
+    relative = file_path.relative_to(source_root)
+    parts = list(relative.parts)
+
+    # Strip TypeScript extension from last segment
+    last = Path(parts[-1])
+    # Handle compound extensions like .d.ts, .d.mts
+    if last.suffix in _TS_EXTENSIONS:
+        stem = last.stem
+        # Strip inner .d suffix for declaration files (e.g. foo.d → foo)
+        if stem.endswith(".d"):
+            stem = stem[:-2]
+        parts[-1] = stem
+    else:
+        parts[-1] = last.stem
+
+    # Drop index files (they represent the package itself, like __init__.py)
+    if parts and parts[-1] in _INDEX_STEMS:
+        parts = parts[:-1]
+
+    if not parts:
+        return source_root.name
+
+    return ".".join(parts)
+
+
+def resolve_relative_import(
+    current_module_qname: str,
+    import_path: str,
+) -> str:
+    """
+    Resolve a TypeScript relative import path to an absolute qualified name.
+
+    Args:
+        current_module_qname: dotted name of the module that contains the
+            import statement, e.g. ``"mypackage.core"``.
+        import_path: raw import path string (already stripped of quotes),
+            e.g. ``"./utils"``, ``"../shared"``, ``"."``.
+
+    Examples:
+        resolve_relative_import("mypackage.core", "./utils")
+            -> "mypackage.utils"
+        resolve_relative_import("mypackage.core", "../shared")
+            -> "shared"
+        resolve_relative_import("mypackage.core", ".")
+            -> "mypackage"
+
+    """
+    current_parts = current_module_qname.split(".")
+    # Start at the directory containing the current file (drop module name)
+    base_parts: list[str] = (
+        current_parts[:-1] if len(current_parts) > 1 else []
+    )
+
+    for segment in import_path.replace("\\", "/").split("/"):
+        if segment in ("", "."):
+            pass  # stay at current level
+        elif segment == "..":
+            base_parts = base_parts[:-1] if base_parts else []
+        else:
+            # Strip file extensions if present in the import path
+            stem = segment.split(".")[0] if "." in segment else segment
+            if stem and stem not in _INDEX_STEMS:
+                base_parts = [*base_parts, stem]
+            # For "index" imports stay at the current package level
+
+    if not base_parts:
+        # Went above root — return the top-level part of the original qname
+        return current_parts[0]
+    return ".".join(base_parts)

graphlens_typescript/_project_detector.py

@@ -0,0 +1,107 @@
+"""TypeScript project detection: marker files and project name extraction."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+TYPESCRIPT_MARKERS: tuple[str, ...] = (
+    "package.json",
+    "tsconfig.json",
+)
+
+_EXCLUDED_DIRS: frozenset[str] = frozenset({
+    ".venv", "venv", "__pycache__", ".git",
+    "dist", "build", ".eggs", "node_modules",
+    "out", "coverage", ".next", ".nuxt",
+})
+
+_NAME_NORMALIZE_RE = re.compile(r"[^a-z0-9_]")
+
+
+def is_typescript_project(project_root: Path) -> bool:
+    """
+    Return True if the directory looks like a TypeScript project.
+
+    Detection order:
+    1. TypeScript-specific marker files (package.json, tsconfig.json)
+    2. Fallback: any .ts or .tsx file exists anywhere under project_root
+    """
+    if _has_typescript_markers(project_root):
+        return True
+    return any(
+        project_root.rglob("*.ts")
+    ) or any(project_root.rglob("*.tsx"))
+
+
+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.
+    """
+    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)
+
+    return sorted(roots) if roots else [search_root]
+
+
+def detect_project_name(project_root: Path) -> str:
+    """
+    Extract the project name from manifest or fall back to directory name.
+
+    Resolution order:
+    1. package.json "name" field (hyphens → underscores, lowercased)
+    2. project_root directory name
+    """
+    package_json = project_root / "package.json"
+    if package_json.exists():
+        try:
+            data = json.loads(package_json.read_text(encoding="utf-8"))
+            raw = data.get("name", "")
+            if raw:
+                # Strip npm scope (e.g. "@scope/pkg" → "pkg")
+                if raw.startswith("@") and "/" in raw:
+                    raw = raw.split("/", 1)[1]
+                # Normalize: lowercase, non-alnum → underscore
+                name = _NAME_NORMALIZE_RE.sub("_", raw.lower()).strip("_")
+                if name:
+                    return name
+        except (
+            json.JSONDecodeError,
+            OSError,
+            KeyError,
+            TypeError,
+            AttributeError,
+        ):
+            pass
+    return _normalize_name(project_root.name)
+
+
+def _normalize_name(name: str) -> str:
+    """Normalize a directory name to a valid Python identifier."""
+    return _NAME_NORMALIZE_RE.sub("_", name.lower()).strip("_") or name
+
+
+def _has_typescript_markers(directory: Path) -> bool:
+    return any((directory / m).exists() for m in TYPESCRIPT_MARKERS)