sentinel-codegraph 0.3.0__py3-none-any.whl

codegraph/parser/links.py

@@ -0,0 +1,314 @@
+"""Cross-file linking: import map + call-edge join (pure).
+
+Two-pass join for the Python pipeline:
+
+1. Collect (per file, no global state): defs, imports with alias
+   originals, buffered bare-name call sites — see
+   :mod:`codegraph.parser.lang_python` and :mod:`codegraph.parser.rows`.
+2. Link (here, global state): one :class:`ImportEntry` per bound name
+   (module specifier -> resolved ``rel_path``), then every call site
+   joins ``(file, name)`` against the definition registry. Anything
+   unresolvable yields no edge — never a dangling one.
+"""
+
+from __future__ import annotations
+
+import posixpath
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+from codegraph.models import Edge, EdgeKind, new_id
+from codegraph.parser.rows import FileRows
+
+
+@dataclass(frozen=True, slots=True)
+class ImportEntry:
+    """One bound name's import map row: specifier + resolved target file."""
+
+    module: str  # raw module specifier, e.g. "pkg.utils" | ".sibling"
+    bound: str  # name bound in the importing file, e.g. "h"
+    original: str  # name in the defining module, e.g. "helper"
+    resolved_rel: str | None  # indexed rel_path of the target, if any
+
+
+def build_import_index(file_set: Iterable[str]) -> dict[str, str]:
+    """Build the frozen ``absolute dotted module -> rel_path`` index.
+
+    Pure path math over POSIX rel paths — no parsing, no I/O. Covers
+    ``pkg/utils.py`` → ``pkg.utils`` plus the ``pkg/__init__.py`` →
+    ``pkg`` package fallback. First registration wins.
+
+    Retained for the (currently unwired) TS/Go emitters and their unit
+    tests; the Python link phase below resolves modules with
+    root-prefix-tolerant suffix matching instead.
+    """
+    index: dict[str, str] = {}
+    for rel in sorted(file_set):
+        # rel->rel overlay: TS/Go emitters probe relative candidates
+        # directly via ``import_index.get`` on the same mapping.
+        index.setdefault(rel, rel)
+        if not rel.endswith(".py"):
+            continue
+        stem: str = rel[: -len(".py")]
+        dotted: str = stem.replace("/", ".")
+        index.setdefault(dotted, rel)
+        if stem.endswith("/__init__"):
+            index.setdefault(dotted[: -len(".__init__")], rel)
+        elif stem == "__init__":
+            index.setdefault("", rel)
+    return index
+
+
+_TS_EXTENSIONS: tuple[str, ...] = (".ts", ".tsx", ".js", ".jsx")
+"""Candidate extensions when resolving a relative TS/JS module."""
+
+
+def _resolve_python_module(
+    module: str, importer_rel: str, indexed: set[str]
+) -> str | None:
+    """Resolve a Python module specifier to an indexed ``rel_path``.
+
+    Relative specifiers resolve against the importer's directory
+    (root-prefix agnostic by construction). Absolute specifiers match
+    the longest specifier suffix against indexed stems, tolerating a
+    root-relative prefix on the indexed side (``src.app.x`` satisfies
+    ``import app.x``) — the ``src/app`` vs ``app`` skew.
+    """
+    if module.startswith("."):
+        level: int = len(module) - len(module.lstrip("."))
+        rest: str = module.lstrip(".")
+        base = PurePosixPath(importer_rel).parent
+        for _ in range(level - 1):
+            base = base.parent
+        target: str = (
+            (base / PurePosixPath(*rest.split("."))).as_posix() if rest else base.as_posix()
+        )
+        for trial in (target + ".py", target + "/__init__.py"):
+            if trial in indexed:
+                return trial
+        return None
+    parts: list[str] = [p for p in module.split(".") if p]
+    if not parts:
+        return None
+    stems: dict[str, str] = {}
+    for path in indexed:
+        if not path.endswith(".py"):
+            continue
+        stems.setdefault(path[: -len(".py")].replace("/", "."), path)
+    for start in range(len(parts)):
+        suffix: str = ".".join(parts[start:])
+        init_suffix: str = suffix + ".__init__"
+        matches: list[str] = sorted(
+            path
+            for stem, path in stems.items()
+            if stem == suffix
+            or stem.endswith("." + suffix)
+            or stem == init_suffix
+            or stem.endswith("." + init_suffix)
+        )
+        if matches:
+            matches.sort(key=lambda p: (len(p), p))
+            return matches[0]
+    return None
+
+
+def build_file_import_map(
+    rows: FileRows, indexed: set[str]
+) -> dict[str, ImportEntry]:
+    """Build one file's bound-name -> :class:`ImportEntry` map.
+
+    First registration wins per bound name. Star imports (``*``) and
+    Go dot imports (``.``) are recorded but never resolve a bare call
+    site directly — export tracking is out of scope (Go dot-imported
+    files are searched separately, see :func:`build_dot_import_targets`).
+    """
+    file_map: dict[str, ImportEntry] = {}
+    for parsed_import in rows.import_details:
+        if parsed_import.name in file_map:
+            continue
+        if parsed_import.name in ("*", "."):
+            file_map.setdefault(
+                parsed_import.name,
+                ImportEntry(
+                    module=parsed_import.module,
+                    bound=parsed_import.name,
+                    original=parsed_import.effective_original,
+                    resolved_rel=None,
+                ),
+            )
+            continue
+        resolved: str | None = _resolve_module(
+            parsed_import.module, rows.rel_path, rows.language, indexed
+        )
+        file_map.setdefault(
+            parsed_import.name,
+            ImportEntry(
+                module=parsed_import.module,
+                bound=parsed_import.name,
+                original=parsed_import.effective_original,
+                resolved_rel=resolved,
+            ),
+        )
+    return file_map
+
+
+def build_dot_import_targets(rows: FileRows, indexed: set[str]) -> list[str]:
+    """Return resolved files this Go file dot-imports, sorted.
+
+    A dot import (``import . "pkg/utils"``) brings the package's
+    exported names into unqualified scope, so bare call sites fall
+    back to these files' definitions when no import-map entry matches.
+    Non-Go files and files without dot imports yield ``[]``.
+    """
+    if rows.language != "go":
+        return []
+    targets: set[str] = set()
+    for parsed_import in rows.import_details:
+        if parsed_import.name != ".":
+            continue
+        resolved: str | None = _resolve_go_module(
+            parsed_import.module, rows.rel_path, indexed
+        )
+        if resolved is not None:
+            targets.add(resolved)
+    return sorted(targets)
+
+
+def _resolve_ts_module(module: str, importer_rel: str, indexed: set[str]) -> str | None:
+    """Resolve a relative TS/JS module specifier to an indexed ``rel_path``.
+
+    Bare specifiers (npm packages) never resolve — they have no file.
+    """
+    if not module.startswith("."):
+        return None
+    base: str = posixpath.normpath(
+        posixpath.join(posixpath.dirname(importer_rel), module)
+    )
+    candidates: list[str] = [base]
+    candidates.extend(base + ext for ext in _TS_EXTENSIONS)
+    candidates.extend(base + "/index" + ext for ext in _TS_EXTENSIONS)
+    for trial in candidates:
+        if trial in indexed:
+            return trial
+    return None
+
+
+def _resolve_go_module(module: str, importer_rel: str, indexed: set[str]) -> str | None:
+    """Resolve a Go import path to an indexed ``rel_path``.
+
+    Relative paths resolve against the importer's directory; otherwise
+    the import tail (package base name) matches the indexed ``.go``
+    stem, shortest path first for determinism.
+    """
+    if module.startswith("."):
+        base: str = posixpath.normpath(
+            posixpath.join(posixpath.dirname(importer_rel), module)
+        )
+        for trial in (base, base + ".go"):
+            if trial in indexed:
+                return trial
+        return None
+    tail: str = module.rsplit("/", 1)[-1]
+    if not tail:
+        return None
+    candidates: list[str] = sorted(
+        path for path in indexed if Path(path).stem == tail and path.endswith(".go")
+    )
+    if not candidates:
+        return None
+    candidates.sort(key=lambda p: (len(p), p))
+    return candidates[0]
+
+
+def _resolve_module(
+    module: str, importer_rel: str, language: str, indexed: set[str]
+) -> str | None:
+    """Resolve a module specifier to an indexed ``rel_path`` (or ``None``)."""
+    if language in ("typescript", "javascript"):
+        return _resolve_ts_module(module, importer_rel, indexed)
+    if language == "go":
+        return _resolve_go_module(module, importer_rel, indexed)
+    return _resolve_python_module(module, importer_rel, indexed)
+
+
+def resolve_call_edges(files: list[FileRows], root: str) -> list[Edge]:
+    """Resolve every file's buffered call sites into ``calls`` edges.
+
+    Resolution order per site: same-file definition first, then the
+    callee's import-map entry joined against the resolved file's
+    definitions on a single candidate name — the *original*
+    (defining-module) name when the import carries one
+    (``from utils import helper as h`` → ``helper``), else the bound
+    name (plain and default imports). Go files additionally fall back
+    to their dot-imported files' definitions. The join key is the
+    ``(rel_path, name)`` registry pair — dotted module strings never
+    take part, so a root-relative prefix on indexed paths (``src/app``
+    vs ``import app``) cannot break the join.
+
+    A callee may be a function, method, class, interface, *or* type
+    node — class instantiation and ``new C()`` are calls. Anything
+    else (natives, stdlib / third-party / unindexed modules,
+    star-import calls, names missing from the target file) yields no
+    edge, never a dangling one. One edge per caller → callee pair,
+    stamped with the call-site line.
+    """
+    indexed: set[str] = {rows.rel_path for rows in files}
+    def_ids: dict[tuple[str, str], str] = {}
+    for rows in files:
+        for name, node_id in rows.definitions.items():
+            def_ids.setdefault((rows.rel_path, name), node_id)
+    file_maps: dict[str, dict[str, ImportEntry]] = {
+        rows.rel_path: build_file_import_map(rows, indexed) for rows in files
+    }
+    dot_targets: dict[str, list[str]] = {
+        rows.rel_path: build_dot_import_targets(rows, indexed) for rows in files
+    }
+    seen: set[tuple[str, str]] = set()
+    edges: list[Edge] = []
+    for rows in files:
+        file_map: dict[str, ImportEntry] = file_maps[rows.rel_path]
+        dots: list[str] = dot_targets[rows.rel_path]
+        for call in rows.calls:
+            src_id: str | None = def_ids.get((rows.rel_path, call.caller))
+            if src_id is None:
+                continue
+            dst_id: str | None = def_ids.get((rows.rel_path, call.callee))
+            if dst_id is None:
+                entry: ImportEntry | None = file_map.get(call.callee)
+                if entry is not None and entry.resolved_rel is not None:
+                    candidate: str = (
+                        entry.original if entry.original else entry.bound
+                    )
+                    dst_id = def_ids.get((entry.resolved_rel, candidate))
+                if dst_id is None:
+                    for target in dots:
+                        dst_id = def_ids.get((target, call.callee))
+                        if dst_id is not None:
+                            break
+                if dst_id is None:
+                    continue
+            if (src_id, dst_id) in seen:
+                continue
+            seen.add((src_id, dst_id))
+            edges.append(
+                Edge(
+                    id=new_id(),
+                    root=root,
+                    src_id=src_id,
+                    dst_id=dst_id,
+                    kind=EdgeKind.CALLS,
+                    target_module=None,
+                    site_line=call.site_line,
+                )
+            )
+    return edges
+
+
+__all__ = [
+    "ImportEntry",
+    "build_dot_import_targets",
+    "build_file_import_map",
+    "build_import_index",
+    "resolve_call_edges",
+]

codegraph/parser/queries.py

@@ -0,0 +1,114 @@
+"""Bare-name call-site extraction via compiled tree-sitter queries.
+
+The only query surface in the package: each query captures a bare
+``(identifier)`` in call-function position. Attribute calls
+(``obj.method()``, ``self.x()``, ``pkg.Fn()``) never match by
+construction. The caller is the innermost enclosing named definition;
+module-level call sites are dropped. All functions are pure given the
+already-parsed tree.
+"""
+
+from __future__ import annotations
+
+from tree_sitter import Language, Node, Query, QueryCursor
+from tree_sitter_language_pack import get_parser
+
+from codegraph.parser.base import ParsedCall
+from codegraph.parser.raw_core import field_text, node_text
+
+_CALL_QUERIES: dict[str, str] = {
+    "python": "(call function: (identifier) @callee)",
+    "typescript": "(call_expression function: (identifier) @callee)",
+    "javascript": "(call_expression function: (identifier) @callee)",
+    "go": "(call_expression function: (identifier) @callee)",
+}
+
+_SCOPE_TYPES: dict[str, frozenset[str]] = {
+    "python": frozenset({"function_definition"}),
+    "typescript": frozenset(
+        {
+            "function_declaration",
+            "function_expression",
+            "arrow_function",
+            "method_definition",
+        }
+    ),
+    "javascript": frozenset(
+        {
+            "function_declaration",
+            "function_expression",
+            "arrow_function",
+            "method_definition",
+        }
+    ),
+    "go": frozenset({"function_declaration", "method_declaration"}),
+}
+
+
+def _scope_name(scope: Node) -> str | None:
+    """Return a scope node's declared name, if it has one."""
+    name: str = field_text(scope, "name")
+    if name:
+        return name
+    if scope.type in ("arrow_function", "function_expression"):
+        parent: Node | None = scope.parent
+        if parent is not None and parent.type == "variable_declarator":
+            bound: str = field_text(parent, "name")
+            if bound:
+                return bound
+        if parent is not None and parent.type == "assignment_expression":
+            target: Node | None = parent.child_by_field_name("left")
+            if target is not None:
+                text: str = node_text(target)
+                if text.isidentifier():
+                    return text
+    if scope.type == "method_declaration":
+        # Go: name is a field_identifier, not identifier.
+        name_node: Node | None = scope.child_by_field_name("name")
+        if name_node is not None:
+            text = node_text(name_node)
+            if text:
+                return text
+    return None
+
+
+def _enclosing_caller(start: Node | None, scopes: frozenset[str]) -> str | None:
+    """Walk up to the innermost enclosing named scope."""
+    probe: Node | None = start
+    while probe is not None:
+        if probe.type in scopes:
+            name: str | None = _scope_name(probe)
+            if name is not None:
+                return name
+        probe = probe.parent
+    return None
+
+
+def extract_calls(language: str, root: Node, grammar: Language) -> list[ParsedCall]:
+    """Extract bare-name call sites from an already-parsed ``root``."""
+    query_src: str | None = _CALL_QUERIES.get(language)
+    scopes: frozenset[str] | None = _SCOPE_TYPES.get(language)
+    if query_src is None or scopes is None:
+        return []
+    query = Query(grammar, query_src)
+    captures: dict[str, list[Node]] = QueryCursor(query).captures(root)
+    found: list[ParsedCall] = []
+    for node in captures.get("callee", []):
+        callee: str = node_text(node)
+        if not callee:
+            continue
+        caller: str | None = _enclosing_caller(node.parent, scopes)
+        if caller is None:
+            continue
+        found.append(ParsedCall(caller=caller, callee=callee))
+    return found
+
+
+def grammar_of(language: str) -> Language:
+    """Return the compiled grammar for ``language`` (for query binding)."""
+    grammar: Language | None = get_parser(language).language
+    assert grammar is not None
+    return grammar
+
+
+__all__ = ["extract_calls", "grammar_of"]

codegraph/parser/raw_core.py

@@ -0,0 +1,66 @@
+"""Raw tree-sitter surface for the v2 pipeline.
+
+Thin wrapper over ``tree_sitter_language_pack.get_parser`` + ``parse``.
+Parsing runs on the calling thread: ``Parser`` / ``Tree`` / ``Node``
+are not thread-safe. Walk helpers are pure and iterative — no recursion,
+no queries here (queries live in ``queries.py``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from tree_sitter import Node, Parser, Tree
+from tree_sitter_language_pack import get_parser
+
+
+def parse(language: str, source: bytes) -> Tree:
+    """Parse ``source`` with the ``language`` grammar on this thread."""
+    parser: Parser = get_parser(language)
+    return parser.parse(source)
+
+
+def node_text(node: Node) -> str:
+    """Decode a node's source text (empty when the node has none)."""
+    raw: bytes | None = node.text
+    if raw is None:
+        return ""
+    return raw.decode("utf-8", errors="ignore")
+
+
+def field_text(node: Node, field: str) -> str:
+    """Decode a named field's text (empty when absent)."""
+    child: Node | None = node.child_by_field_name(field)
+    if child is None:
+        return ""
+    return node_text(child)
+
+
+def span(node: Node) -> tuple[int, int]:
+    """Return a node's 1-based ``(start_line, end_line)`` span."""
+    start: int = node.start_point[0] + 1
+    end: int = node.end_point[0] + 1
+    return (start, max(end, start))
+
+
+def has_error(root: Node) -> bool:
+    """Return True when the tree contains an error node."""
+    stack: list[Node] = [root]
+    while stack:
+        node: Node = stack.pop()
+        if node.type == "ERROR" or node.is_missing:
+            return True
+        stack.extend(node.named_children)
+    return False
+
+
+def walk(root: Node) -> Iterator[Node]:
+    """Yield every named node in the tree, depth-first (iterative)."""
+    stack: list[Node] = [root]
+    while stack:
+        node: Node = stack.pop()
+        yield node
+        stack.extend(reversed(node.named_children))
+
+
+__all__ = ["field_text", "has_error", "node_text", "parse", "span", "walk"]

codegraph/parser/rows.py

@@ -0,0 +1,191 @@
+"""Per-file row builders: source text -> storage rows (pure).
+
+Collect phase output: nodes + ``contains`` / ``imports`` edges plus the
+resolution maps (definitions, imports with alias originals, buffered
+call sites). ``calls`` edges are never emitted here — they resolve
+across files in :mod:`codegraph.parser.links`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from codegraph.models import Edge, EdgeKind, Node, NodeKind, new_id
+from codegraph.parser.base import ParsedCall, ParsedFile, ParsedImport
+from codegraph.parser.raw_core import parse
+
+
+@dataclass(slots=True)
+class FileRows:
+    """Per-file build output: storage rows plus resolution maps."""
+
+    rel_path: str
+    language: str
+    nodes: list[Node] = field(default_factory=lambda: list[Node]())
+    edges: list[Edge] = field(default_factory=lambda: list[Edge]())
+    definitions: dict[str, str] = field(default_factory=lambda: dict[str, str]())
+    imports: dict[str, str] = field(default_factory=lambda: dict[str, str]())
+    import_details: list[ParsedImport] = field(
+        default_factory=lambda: list[ParsedImport]()
+    )
+    calls: list[ParsedCall] = field(default_factory=lambda: list[ParsedCall]())
+
+
+def _node_kind(kind: str) -> NodeKind:
+    if kind == "class":
+        return NodeKind.CLASS
+    if kind == "method":
+        return NodeKind.METHOD
+    if kind == "function":
+        return NodeKind.FUNCTION
+    return NodeKind.FUNCTION
+
+
+def build_file_rows(
+    root: str,
+    rel_path: str,
+    language: str,
+    parsed: ParsedFile,
+) -> FileRows:
+    """Convert one :class:`ParsedFile` into nodes + ``contains`` / ``imports``.
+
+    ``calls`` edges are NOT emitted here — they resolve across files in
+    ``links.resolve_call_edges``. The file node always exists, even for
+    empty files. Duplicate names in one file resolve to the first
+    registration.
+    """
+    file_id: str = new_id()
+    file_node = Node(
+        id=file_id,
+        root=root,
+        file_path=rel_path,
+        kind=NodeKind.FILE,
+        name=Path(rel_path).name,
+        language=language,
+        start_line=1,
+        end_line=parsed.total_lines,
+        parent_id=None,
+    )
+    rows = FileRows(rel_path=rel_path, language=language)
+    rows.nodes.append(file_node)
+
+    def_ids: dict[str, str] = {}
+    for definition in parsed.definitions:
+        node_id: str = new_id()
+        parent_id: str = file_id
+        if definition.parent is not None and definition.parent in def_ids:
+            parent_id = def_ids[definition.parent]
+        kind = _node_kind(definition.kind)
+        rows.nodes.append(
+            Node(
+                id=node_id,
+                root=root,
+                file_path=rel_path,
+                kind=kind,
+                name=definition.name,
+                language=language,
+                start_line=definition.start_line,
+                end_line=definition.end_line,
+                parent_id=parent_id,
+            )
+        )
+        rows.edges.append(
+            Edge(
+                id=new_id(),
+                root=root,
+                src_id=parent_id,
+                dst_id=node_id,
+                kind=EdgeKind.CONTAINS,
+                target_module=None,
+            )
+        )
+        def_ids.setdefault(definition.name, node_id)
+        rows.definitions.setdefault(definition.name, node_id)
+
+    for imported in parsed.imports:
+        node_id = new_id()
+        rows.nodes.append(
+            Node(
+                id=node_id,
+                root=root,
+                file_path=rel_path,
+                kind=NodeKind.IMPORT,
+                name=imported.name,
+                language=language,
+                start_line=imported.start_line,
+                end_line=imported.end_line,
+                parent_id=file_id,
+            )
+        )
+        rows.edges.append(
+            Edge(
+                id=new_id(),
+                root=root,
+                src_id=file_id,
+                dst_id=node_id,
+                kind=EdgeKind.IMPORTS,
+                target_module=imported.module,
+            )
+        )
+        rows.imports.setdefault(imported.name, imported.module)
+        rows.import_details.append(imported)
+
+    rows.calls.extend(parsed.calls)
+    return rows
+
+
+def build_python_file_rows(
+    root: str,
+    rel_path: str,
+    source_text: str,
+    _import_index: Mapping[str, str],
+) -> FileRows:
+    """Build one Python file's rows via the collect phase.
+
+    Nodes + ``contains`` / ``imports`` edges come out of
+    :func:`lang_python.collect_python_file` directly; ``calls`` edges
+    are never emitted here — ``rows.calls`` carries the buffered call
+    sites for :func:`codegraph.parser.links.resolve_call_edges`.
+    ``_import_index`` is accepted for builder-signature uniformity and
+    ignored: the link phase resolves modules from the full file set.
+    """
+    from codegraph.parser import lang_python
+
+    total_lines: int = max(source_text.count("\n") + 1, 1)
+    rows = FileRows(rel_path=rel_path, language="python")
+    if not source_text.strip():
+        file_node = Node(
+            id=rel_path,
+            root=root,
+            file_path=rel_path,
+            kind=NodeKind.FILE,
+            name=Path(rel_path).name,
+            language="python",
+            start_line=1,
+            end_line=total_lines,
+            parent_id=None,
+        )
+        rows.nodes.append(file_node)
+        return rows
+    tree = parse("python", source_text.encode("utf-8"))
+
+    out = lang_python.collect_python_file(
+        rel_path, tree.root_node, root, total_lines
+    )
+    rows.nodes.extend(out.nodes.values())
+    rows.edges.extend(out.edges)
+    rows.definitions.update(out.definitions)
+    for parsed_import in out.imports:
+        rows.imports.setdefault(parsed_import.name, parsed_import.module)
+    rows.import_details.extend(out.imports)
+    rows.calls.extend(out.calls)
+    return rows
+
+
+__all__ = [
+    "FileRows",
+    "build_file_rows",
+    "build_python_file_rows",
+]