sentinel-codegraph 0.3.0__py3-none-any.whl

codegraph/graph_store.py

@@ -0,0 +1,455 @@
+"""Ladybug persistence for the code graph.
+
+Embedded property-graph backend. Schema (created once via
+:meth:`LadybugStore.create_all`):
+
+- ``CodeNode`` — one row per structural node (``id`` primary key).
+  ``is_placeholder`` is retained on the column for old databases but
+  new builds never write placeholder rows: unresolvable call sites
+  are dropped at build time, so every stored edge has both endpoints.
+- ``Contains`` / ``Imports`` / ``Calls`` — rel tables between
+  ``CodeNode`` rows (``site_line`` on ``Calls``, ``target_module`` on
+  ``Imports``).
+
+Bulk ingest uses single-call ``execute`` + ``UNWIND $batch`` (no
+dataframe dependency). Callers never touch the connection directly
+beyond :func:`create_store`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import ladybug as lb
+
+from codegraph.models import Edge, EdgeKind, Node, NodeKind
+
+
+async def _fetch(
+    conn: lb.AsyncConnection, query: str, params: dict[str, Any] | None = None
+) -> list[tuple[Any, ...]]:
+    """Run ``query`` and return rows as plain tuples.
+
+    Ladybug rows index positionally at runtime, but the shipped stubs
+    type ``QueryResult.__getitem__`` as str-keyed only — so normalise
+    through ``tuple()`` once, here, and keep the rest of the module
+    strictly typed.
+    """
+    result: Any = await conn.execute(query, params or {})
+    return [tuple(row) for row in result]
+
+
+_NODE_FIELDS: tuple[str, ...] = (
+    "id",
+    "root",
+    "file_path",
+    "kind",
+    "name",
+    "language",
+    "start_line",
+    "end_line",
+    "parent_id",
+    "is_placeholder",
+)
+"""CodeNode columns in canonical order (select + mapping share it)."""
+
+
+def _node_cols(alias: str) -> str:
+    """Return the comma-separated ``alias.col`` select list for a node."""
+    return ", ".join(f"{alias}.{field}" for field in _NODE_FIELDS)
+
+
+def _node_from_row(row: tuple[Any, ...]) -> Node:
+    """Map the first ten columns of a result row onto a :class:`Node`."""
+    return Node(
+        id=str(row[0]),
+        root=str(row[1]),
+        file_path=str(row[2]),
+        kind=NodeKind(str(row[3])),
+        name=str(row[4]),
+        language=str(row[5]),
+        start_line=int(row[6]),
+        end_line=int(row[7]),
+        parent_id=str(row[8]) if row[8] is not None else None,
+        is_placeholder=bool(row[9]),
+    )
+
+
+class LadybugStore:
+    """Owns one Ladybug database + async connection."""
+
+    def __init__(self, path: str) -> None:
+        self._path: str = path
+        self._db: lb.Database = lb.Database(path)
+        self._conn: lb.AsyncConnection = lb.AsyncConnection(self._db)
+
+    async def create_all(self) -> None:
+        """Create node/rel tables when they do not exist yet."""
+        await self._conn.execute(
+            "CREATE NODE TABLE IF NOT EXISTS CodeNode("
+            "id STRING PRIMARY KEY, root STRING, file_path STRING, "
+            "kind STRING, name STRING, language STRING, "
+            "start_line INT64, end_line INT64, "
+            "parent_id STRING, is_placeholder BOOLEAN DEFAULT false)"
+        )
+        await self._conn.execute(
+            "CREATE REL TABLE IF NOT EXISTS Contains(FROM CodeNode TO CodeNode)"
+        )
+        await self._conn.execute(
+            "CREATE REL TABLE IF NOT EXISTS Imports("
+            "FROM CodeNode TO CodeNode, target_module STRING)"
+        )
+        await self._conn.execute(
+            "CREATE REL TABLE IF NOT EXISTS Calls("
+            "FROM CodeNode TO CodeNode, site_line INT64)"
+        )
+
+    async def clear_all(self) -> None:
+        """Delete every node/edge row in the database (full flush)."""
+        await self._conn.execute("MATCH (n:CodeNode) DETACH DELETE n")
+
+    async def clear_root(self, root: str) -> None:
+        """Delete every node/edge previously indexed under ``root``."""
+        await self._conn.execute(
+            "MATCH (n:CodeNode) WHERE n.root = $root DETACH DELETE n",
+            {"root": root},
+        )
+
+    async def add_all(self, nodes: Sequence[Node], edges: Sequence[Edge]) -> None:
+        """Bulk-insert one batch of nodes plus their edges.
+
+        Straight persist: every edge endpoint is a stored node id (the
+        build drops unresolvable call sites instead of emitting
+        dangling refs), so no rewriting or stub synthesis happens here.
+        """
+        node_rows: list[dict[str, Any]] = [
+            {
+                "id": n.id,
+                "root": n.root,
+                "file_path": n.file_path,
+                "kind": n.kind.value,
+                "name": n.name,
+                "language": n.language,
+                "start_line": n.start_line,
+                "end_line": n.end_line,
+                "parent_id": n.parent_id,
+                "is_placeholder": n.is_placeholder,
+            }
+            for n in nodes
+        ]
+        contains_rows: list[dict[str, Any]] = []
+        imports_rows: list[dict[str, Any]] = []
+        calls_rows: list[dict[str, Any]] = []
+        for e in edges:
+            if e.kind == EdgeKind.CONTAINS:
+                contains_rows.append({"src": e.src_id, "dst": e.dst_id})
+            elif e.kind == EdgeKind.IMPORTS:
+                imports_rows.append(
+                    {"src": e.src_id, "dst": e.dst_id, "mod": e.target_module}
+                )
+            else:
+                calls_rows.append(
+                    {"src": e.src_id, "dst": e.dst_id, "site": e.site_line}
+                )
+        if node_rows:
+            await self._conn.execute(
+                "UNWIND $batch AS row CREATE (n:CodeNode {"
+                "id: row.id, root: row.root, file_path: row.file_path, "
+                "kind: row.kind, name: row.name, language: row.language, "
+                "start_line: row.start_line, end_line: row.end_line, "
+                "parent_id: row.parent_id, is_placeholder: row.is_placeholder})",
+                {"batch": node_rows},
+            )
+        if contains_rows:
+            await self._conn.execute(
+                "UNWIND $batch AS row "
+                "MATCH (a:CodeNode {id: row.src}), (b:CodeNode {id: row.dst}) "
+                "CREATE (a)-[:Contains]->(b)",
+                {"batch": contains_rows},
+            )
+        if imports_rows:
+            await self._conn.execute(
+                "UNWIND $batch AS row "
+                "MATCH (a:CodeNode {id: row.src}), (b:CodeNode {id: row.dst}) "
+                "CREATE (a)-[:Imports {target_module: row.mod}]->(b)",
+                {"batch": imports_rows},
+            )
+        if calls_rows:
+            await self._conn.execute(
+                "UNWIND $batch AS row "
+                "MATCH (a:CodeNode {id: row.src}), (b:CodeNode {id: row.dst}) "
+                "CREATE (a)-[:Calls {site_line: row.site}]->(b)",
+                {"batch": calls_rows},
+            )
+
+    async def count_by_node_kind(self, root: str | None = None) -> dict[str, int]:
+        """Return row counts grouped by node kind (keys are kind values)."""
+        query: str = "MATCH (n:CodeNode)"
+        params: dict[str, Any] = {}
+        if root is not None:
+            query += " WHERE n.root = $root"
+            params["root"] = root
+        query += " RETURN n.kind AS k, COUNT(*) AS c"
+        return {str(k): int(c) for k, c in await _fetch(self._conn, query, params)}
+
+    async def count_by_edge_kind(self, root: str | None = None) -> dict[str, int]:
+        """Return row counts grouped by edge kind (keys are kind values)."""
+        out: dict[str, int] = {}
+        for label in ("Contains", "Imports", "Calls"):
+            query: str = f"MATCH (a:CodeNode)-[e:{label}]->(:CodeNode)"
+            params: dict[str, Any] = {}
+            if root is not None:
+                query += " WHERE a.root = $root"
+                params["root"] = root
+            rows: list[tuple[Any, ...]] = await _fetch(
+                self._conn, query + " RETURN COUNT(*)", params
+            )
+            out[label.lower()] = int(rows[0][0])
+        return out
+
+    async def count_by_language(self, root: str | None = None) -> dict[str, int]:
+        """Return file-node counts grouped by language."""
+        query: str = "MATCH (n:CodeNode) WHERE n.kind = 'file'"
+        params: dict[str, Any] = {}
+        if root is not None:
+            query += " AND n.root = $root"
+            params["root"] = root
+        query += " RETURN n.language AS l, COUNT(*) AS c"
+        return {str(l): int(c) for l, c in await _fetch(self._conn, query, params)}
+
+    async def total_counts(self, root: str | None = None) -> tuple[int, int, int]:
+        """Return ``(files, nodes, edges)`` totals."""
+        params: dict[str, Any] = {"root": root} if root is not None else {}
+        root_and: str = " AND n.root = $root" if root is not None else ""
+        root_where_a: str = " WHERE a.root = $root" if root is not None else ""
+        files_rows: list[tuple[Any, ...]] = await _fetch(
+            self._conn,
+            "MATCH (n:CodeNode) WHERE n.kind = 'file'" + root_and + " RETURN COUNT(*)",
+            params,
+        )
+        nodes_rows: list[tuple[Any, ...]] = await _fetch(
+            self._conn,
+            "MATCH (n:CodeNode)"
+            + (" WHERE n.root = $root" if root is not None else "")
+            + " RETURN COUNT(*)",
+            params,
+        )
+        edge_total: int = 0
+        for label in ("Contains", "Imports", "Calls"):
+            rel_rows: list[tuple[Any, ...]] = await _fetch(
+                self._conn,
+                f"MATCH (a:CodeNode)-[:{label}]->(:CodeNode)"
+                + root_where_a
+                + " RETURN COUNT(*)",
+                params,
+            )
+            edge_total += int(rel_rows[0][0])
+        return (int(files_rows[0][0]), int(nodes_rows[0][0]), edge_total)
+
+    async def top_importers(self, limit: int = 10) -> list[tuple[str, int]]:
+        """Return ``(file_path, import_count)`` ordered by import count."""
+        rows: list[tuple[Any, ...]] = await _fetch(
+            self._conn,
+            "MATCH (a:CodeNode)-[:Imports]->(:CodeNode) "
+            "RETURN a.file_path AS p, COUNT(*) AS c "
+            "ORDER BY c DESC LIMIT $limit",
+            {"limit": limit},
+        )
+        return [(str(path), int(count)) for path, count in rows]
+
+    async def list_nodes(self, root: str | None = None) -> list[Node]:
+        """Return nodes, optionally scoped to ``root``, in stable order."""
+        query: str = (
+            "MATCH (n:CodeNode)"
+            + (" WHERE n.root = $root" if root is not None else "")
+            + f" RETURN {_node_cols('n')} "
+            "ORDER BY n.file_path, n.kind, n.start_line"
+        )
+        params: dict[str, Any] = {"root": root} if root is not None else {}
+        return [_node_from_row(row) for row in await _fetch(self._conn, query, params)]
+
+    async def get_node(self, node_id: str, root: str | None = None) -> Node | None:
+        """Return one node by id (``None`` when absent). Pure read."""
+        query: str = "MATCH (n:CodeNode) WHERE n.id = $id"
+        params: dict[str, Any] = {"id": node_id}
+        if root is not None:
+            query += " AND n.root = $root"
+            params["root"] = root
+        query += f" RETURN {_node_cols('n')}"
+        rows: list[tuple[Any, ...]] = await _fetch(self._conn, query, params)
+        return _node_from_row(rows[0]) if rows else None
+
+    async def callees(
+        self, node_id: str, root: str | None = None
+    ) -> list[tuple[Node, int | None]]:
+        """Return ``(node, site_line)`` for outgoing ``Calls``, in call order.
+
+        Sorted by call-site line (unknown lines last), then callee
+        span — never worse than alphabetical. Pure read.
+        """
+        query: str = "MATCH (c:CodeNode {id: $id})-[e:Calls]->(d:CodeNode)"
+        params: dict[str, Any] = {"id": node_id}
+        if root is not None:
+            query += " WHERE c.root = $root"
+            params["root"] = root
+        query += f" RETURN {_node_cols('d')}, e.site_line"
+        found: list[tuple[Node, int | None]] = [
+            (
+                _node_from_row(row[: len(_NODE_FIELDS)]),
+                int(row[len(_NODE_FIELDS)]) if row[len(_NODE_FIELDS)] is not None else None,
+            )
+            for row in await _fetch(self._conn, query, params)
+        ]
+        found.sort(
+            key=lambda item: (
+                item[1] is None,
+                item[1] if item[1] is not None else 0,
+                item[0].start_line,
+                item[0].name,
+            )
+        )
+        return found
+
+    async def callers(
+        self, node_id: str, root: str | None = None
+    ) -> list[tuple[Node, int | None]]:
+        """Return ``(node, site_line)`` for incoming ``Calls``, in call order.
+
+        Pure read; same ordering as :meth:`callees`.
+        """
+        query: str = "MATCH (s:CodeNode)-[e:Calls]->(c:CodeNode {id: $id})"
+        params: dict[str, Any] = {"id": node_id}
+        if root is not None:
+            query += " WHERE c.root = $root"
+            params["root"] = root
+        query += f" RETURN {_node_cols('s')}, e.site_line"
+        found: list[tuple[Node, int | None]] = [
+            (
+                _node_from_row(row[: len(_NODE_FIELDS)]),
+                int(row[len(_NODE_FIELDS)]) if row[len(_NODE_FIELDS)] is not None else None,
+            )
+            for row in await _fetch(self._conn, query, params)
+        ]
+        found.sort(
+            key=lambda item: (
+                item[1] is None,
+                item[1] if item[1] is not None else 0,
+                item[0].start_line,
+                item[0].name,
+            )
+        )
+        return found
+
+    async def children(
+        self, node_id: str, root: str | None = None
+    ) -> list[Node]:
+        """Return outgoing ``Contains`` targets in span order. Pure read."""
+        query: str = "MATCH (p:CodeNode {id: $id})-[:Contains]->(d:CodeNode)"
+        params: dict[str, Any] = {"id": node_id}
+        if root is not None:
+            query += " WHERE p.root = $root"
+            params["root"] = root
+        query += f" RETURN {_node_cols('d')} ORDER BY d.start_line, d.name"
+        return [_node_from_row(row) for row in await _fetch(self._conn, query, params)]
+
+    async def file_imports(
+        self, file_rel: str, root: str | None = None
+    ) -> list[tuple[Node, str | None]]:
+        """Return ``(import node, target_module)`` for a file, in line order.
+
+        The file node id is its ``rel_path``. Pure read.
+        """
+        query: str = "MATCH (f:CodeNode {id: $id})-[e:Imports]->(i:CodeNode)"
+        params: dict[str, Any] = {"id": file_rel}
+        if root is not None:
+            query += " WHERE f.root = $root"
+            params["root"] = root
+        query += f" RETURN {_node_cols('i')}, e.target_module ORDER BY i.start_line"
+        return [
+            (
+                _node_from_row(row[: len(_NODE_FIELDS)]),
+                str(row[len(_NODE_FIELDS)]) if row[len(_NODE_FIELDS)] is not None else None,
+            )
+            for row in await _fetch(self._conn, query, params)
+        ]
+
+    async def list_files(self, root: str | None = None) -> list[Node]:
+        """Return file nodes, optionally scoped to ``root``, by path. Pure read."""
+        query: str = "MATCH (n:CodeNode) WHERE n.kind = 'file'"
+        params: dict[str, Any] = {}
+        if root is not None:
+            query += " AND n.root = $root"
+            params["root"] = root
+        query += f" RETURN {_node_cols('n')} ORDER BY n.file_path"
+        return [_node_from_row(row) for row in await _fetch(self._conn, query, params)]
+
+    async def list_edges(self, root: str | None = None) -> list[Edge]:
+        """Return edges, optionally scoped to ``root``, in stable order."""
+        params: dict[str, Any] = {"root": root} if root is not None else {}
+        where: str = " WHERE a.root = $root" if root is not None else ""
+        found: list[Edge] = []
+        for row in await _fetch(
+            self._conn,
+            "MATCH (a:CodeNode)-[:Contains]->(b:CodeNode)"
+            + where
+            + " RETURN a.root, a.id, b.id",
+            params,
+        ):
+            found.append(
+                Edge(
+                    id=f"{row[1]}::contains::{row[2]}",
+                    root=str(row[0]),
+                    src_id=str(row[1]),
+                    dst_id=str(row[2]),
+                    kind=EdgeKind.CONTAINS,
+                )
+            )
+        for row in await _fetch(
+            self._conn,
+            "MATCH (a:CodeNode)-[e:Imports]->(b:CodeNode)"
+            + where
+            + " RETURN a.root, a.id, b.id, e.target_module",
+            params,
+        ):
+            found.append(
+                Edge(
+                    id=f"{row[1]}::imports::{row[2]}",
+                    root=str(row[0]),
+                    src_id=str(row[1]),
+                    dst_id=str(row[2]),
+                    kind=EdgeKind.IMPORTS,
+                    target_module=str(row[3]) if row[3] is not None else None,
+                )
+            )
+        for row in await _fetch(
+            self._conn,
+            "MATCH (a:CodeNode)-[e:Calls]->(b:CodeNode)"
+            + where
+            + " RETURN a.root, a.id, b.id, e.site_line",
+            params,
+        ):
+            found.append(
+                Edge(
+                    id=f"{row[1]}::calls::{row[2]}",
+                    root=str(row[0]),
+                    src_id=str(row[1]),
+                    dst_id=str(row[2]),
+                    kind=EdgeKind.CALLS,
+                    site_line=int(row[3]) if row[3] is not None else None,
+                )
+            )
+        found.sort(key=lambda e: (e.src_id, e.kind.value))
+        return found
+
+    async def dispose(self) -> None:
+        """Release the connection (embedded DB needs no pool teardown)."""
+        return None
+
+
+def create_store(path: str) -> LadybugStore:
+    """Create a :class:`LadybugStore` bound to ``path`` (or ``:memory:``)."""
+    return LadybugStore(path)
+
+
+__all__ = ["EdgeKind", "LadybugStore", "NodeKind", "create_store"]

codegraph/models.py

@@ -0,0 +1,87 @@
+"""Plain dataclasses for the code graph.
+
+Single source of truth for the row shapes. Persistence lives in
+:mod:`codegraph.graph_store` (Ladybug); these types never touch the
+database layer.
+
+Graph contract (two-pass build: Python, TypeScript/JavaScript, Go):
+
+- ``Node`` kinds: file | class | function | method | interface |
+  type | import. Interfaces own their method signatures; type aliases
+  are leaves.
+- ``Edge`` kinds: contains (file -> def, class/interface -> method,
+  function -> nested def) | imports (file -> import, carrying the raw
+  ``target_module`` string) | calls (function|method ->
+  function|method|class, bare-name call sites only, real node ids).
+- Unresolvable call sites are dropped at build time: every stored
+  ``calls`` edge has both endpoints, and no placeholder rows are
+  written (``is_placeholder`` stays on the schema for old databases).
+"""
+
+from __future__ import annotations
+
+import enum
+import uuid
+from dataclasses import dataclass, field
+
+
+def new_id() -> str:
+    """Return a random hex id for a graph row."""
+    return uuid.uuid4().hex
+
+
+class NodeKind(str, enum.Enum):
+    """Structural node types extracted by the raw parsers."""
+
+    FILE = "file"
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+    INTERFACE = "interface"
+    TYPE = "type"
+    IMPORT = "import"
+
+
+class EdgeKind(str, enum.Enum):
+    """Structural edge types between nodes."""
+
+    CONTAINS = "contains"
+    IMPORTS = "imports"
+    CALLS = "calls"
+
+
+@dataclass(slots=True)
+class Node:
+    """One structural element of a scanned codebase."""
+
+    id: str = field(default_factory=new_id)
+    root: str = ""
+    file_path: str = ""
+    kind: NodeKind = NodeKind.FILE
+    name: str = ""
+    language: str = ""
+    start_line: int = 1
+    end_line: int = 1
+    parent_id: str | None = None
+    is_placeholder: bool = False
+
+
+@dataclass(slots=True)
+class Edge:
+    """One structural relation between two nodes.
+
+    Both ``src_id`` and ``dst_id`` always point at stored nodes; the
+    link phase drops call sites that resolve to nothing instead of
+    emitting dangling refs.
+    """
+
+    id: str = field(default_factory=new_id)
+    root: str = ""
+    src_id: str = ""
+    dst_id: str = ""
+    kind: EdgeKind = EdgeKind.CONTAINS
+    target_module: str | None = None
+    site_line: int | None = None
+
+
+__all__ = ["Edge", "EdgeKind", "Node", "NodeKind", "new_id"]

codegraph/parser/__init__.py

@@ -0,0 +1,27 @@
+"""Parser barrel: re-exports only, no logic.
+
+Per-file rows live in :mod:`codegraph.parser.rows`, cross-file
+linking (import map + call join) in :mod:`codegraph.parser.links`,
+the Python collect phase in :mod:`codegraph.parser.lang_python`;
+``lang_go`` / ``lang_typescript`` are kept, currently unwired.
+"""
+
+from codegraph.parser.links import (
+    ImportEntry,
+    build_dot_import_targets,
+    build_file_import_map,
+    build_import_index,
+    resolve_call_edges,
+)
+from codegraph.parser.rows import FileRows, build_file_rows, build_python_file_rows
+
+__all__ = [
+    "FileRows",
+    "ImportEntry",
+    "build_dot_import_targets",
+    "build_file_import_map",
+    "build_file_rows",
+    "build_import_index",
+    "build_python_file_rows",
+    "resolve_call_edges",
+]

codegraph/parser/base.py

@@ -0,0 +1,114 @@
+"""Shared intermediate representation for the raw parsers.
+
+Each language extractor turns a tree-sitter tree into a :class:`ParsedFile`
+— flat lists of definitions, imports, and call sites with 1-based line
+spans. The graph builder (``parser/__init__.py``) then converts the IR
+into ``Node`` / ``Edge`` rows, so parsers never touch the database layer.
+All IR constructors are pure.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedDefinition:
+    """A class, function, or method found in a source file."""
+
+    kind: str  # "class" | "function" | "method"
+    name: str
+    start_line: int  # 1-based, inclusive
+    end_line: int  # 1-based, inclusive
+    parent: str | None = None  # nearest enclosing def name (any kind)
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedImport:
+    """A single imported name (one row per name, not per statement)."""
+
+    module: str  # raw module specifier, e.g. "os" | "pkg.utils" | ".sibling"
+    name: str  # bound symbol in the importing file, or "*" for star imports
+    start_line: int  # 1-based
+    end_line: int  # 1-based
+    original: str = ""  # name in the defining module; "" means same as ``name``
+    # ``from utils import helper as h`` -> name="h", original="helper".
+    # ``from utils import helper`` -> name="helper", original="".
+    # ``import os`` -> name="os", original="".
+
+    @property
+    def effective_original(self) -> str:
+        """Return the defining-module name (falls back to the bound name)."""
+        return self.original or self.name
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedCall:
+    """A bare-name call site: ``caller`` calls ``callee``.
+
+    ``caller`` is the innermost enclosing named definition; module-level
+    call sites are dropped, so ``caller`` is never empty. ``callee`` is
+    the called bare name — resolution to a node happens in the link
+    phase, which drops names that resolve to nothing indexed.
+    """
+
+    caller: str
+    callee: str
+    site_line: int | None = None  # 1-based call-site line (None = unknown)
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedFile:
+    """Parser output for one source file."""
+
+    language: str
+    definitions: tuple[ParsedDefinition, ...] = ()
+    imports: tuple[ParsedImport, ...] = ()
+    calls: tuple[ParsedCall, ...] = ()
+    total_lines: int = 1
+    has_error: bool = False
+
+
+def empty_file(language: str, total_lines: int = 1) -> ParsedFile:
+    """Return an empty :class:`ParsedFile` (unparseable or blank source)."""
+    return ParsedFile(
+        language=language,
+        definitions=(),
+        imports=(),
+        calls=(),
+        total_lines=max(total_lines, 1),
+        has_error=True,
+    )
+
+
+@dataclass(slots=True)
+class FileAccumulator:
+    """Mutable builder collected during a tree walk."""
+
+    language: str
+    total_lines: int = 1
+    has_error: bool = False
+    definitions: list[ParsedDefinition] = field(default_factory=list)
+    imports: list[ParsedImport] = field(default_factory=list)
+    calls: list[ParsedCall] = field(default_factory=list)
+
+    def build(self) -> ParsedFile:
+        """Freeze the accumulator into a :class:`ParsedFile`."""
+        return ParsedFile(
+            language=self.language,
+            definitions=tuple(self.definitions),
+            imports=tuple(self.imports),
+            calls=tuple(self.calls),
+            total_lines=max(self.total_lines, 1),
+            has_error=self.has_error,
+        )
+
+
+__all__ = [
+    "FileAccumulator",
+    "ParsedCall",
+    "ParsedDefinition",
+    "ParsedFile",
+    "ParsedImport",
+    "empty_file",
+]