node-walk 0.1.0__py3-none-any.whl

node_walk/indexer.py

@@ -0,0 +1,188 @@
+"""
+Indexer — orchestrates file discovery, analysis, storage, and cross-file resolution.
+
+Usage:
+    from node_walk.indexer import Indexer
+    from node_walk.storage.repository import SQLiteGraphStore
+
+    store = SQLiteGraphStore(".node_walk/graph.db")
+    indexer = Indexer(store)
+    indexer.index("./my_repo")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from node_walk.analysis.base import FileDiscovery, LanguageAnalyzer
+from node_walk.analysis.python import PythonAnalyzer
+from node_walk.ir.models import AnalysisResult
+from node_walk.ir.enums import Language, RelationshipType, ResolutionStatus
+from node_walk.storage.base import GraphStore
+
+
+class Indexer:
+    """
+    Orchestrates a full index run:
+      1. Discover files
+      2. Analyze each file with the appropriate LanguageAnalyzer
+      3. Store all results
+      4. Run cross-file resolution pass (fix EXTENDS/IMPLEMENTS/CALLS/IMPORTS)
+    """
+
+    def __init__(
+        self,
+        store: GraphStore,
+        analyzers: list[LanguageAnalyzer] | None = None,
+        progress_callback: Callable[[str, int, int], None] | None = None,
+    ) -> None:
+        self._store = store
+        self._analyzers: list[LanguageAnalyzer] = analyzers or [PythonAnalyzer()]
+        self._progress = progress_callback  # (file_path, current, total)
+
+        # Build language → analyzer map
+        self._lang_map: dict[Language, LanguageAnalyzer] = {}
+        for a in self._analyzers:
+            for lang in a.supported_languages:
+                self._lang_map[lang] = a
+
+    def index(self, root: str | Path, clear: bool = True) -> IndexStats:
+        """
+        Index *root* directory.
+
+        If *clear* is True (default), wipes the existing graph first
+        (full re-index). Set to False for incremental updates (future).
+        """
+        root = Path(root).resolve()
+
+        if clear:
+            self._store.clear()
+
+        # --- 1. Discover files ---
+        discovery = FileDiscovery(root, include_languages=list(self._lang_map.keys()))
+        file_pairs = discovery.discover()
+        total = len(file_pairs)
+
+        # --- 2. Analyze ---
+        results: list[AnalysisResult] = []
+        errors: list[str] = []
+
+        for i, (file_info, source) in enumerate(file_pairs, start=1):
+            if self._progress:
+                self._progress(file_info.path, i, total)
+
+            analyzer = self._lang_map.get(file_info.language)
+            if not analyzer:
+                continue
+
+            try:
+                result = analyzer.analyze(file_info, source)
+                results.append(result)
+            except Exception as exc:  # noqa: BLE001
+                errors.append(f"{file_info.path}: {exc}")
+
+        # --- 3. Store ---
+        self._store.store_results(results)
+
+        # --- 4. Cross-file resolution ---
+        resolved_count = self._resolve_cross_file(results)
+
+        symbols_total = sum(len(r.symbols) for r in results)
+        rels_total = sum(len(r.relationships) for r in results)
+
+        return IndexStats(
+            files_discovered=total,
+            files_analyzed=len(results),
+            symbols_extracted=symbols_total,
+            relationships_extracted=rels_total,
+            relationships_resolved=resolved_count,
+            errors=errors,
+        )
+
+    # ------------------------------------------------------------------
+    # Cross-file resolution
+    # ------------------------------------------------------------------
+
+    def _resolve_cross_file(self, results: list[AnalysisResult]) -> int:
+        """
+        Fix unresolved relationships by matching target_name metadata
+        against all known symbols across the entire indexed corpus.
+
+        Returns the number of newly resolved relationships.
+        """
+        # Build a lookup: simple name → [Symbol], qualified_name → Symbol
+        name_to_syms: dict[str, list] = {}
+        qname_to_sym: dict[str, object] = {}
+
+        all_symbols = self._store.get_all_symbols()
+        for sym in all_symbols:
+            name_to_syms.setdefault(sym.name, []).append(sym)
+            qname_to_sym[sym.qualified_name] = sym
+
+        unresolved = self._store.get_all_unresolved_relationships()
+        resolved_count = 0
+
+        for rel in unresolved:
+            target_name: str = rel.metadata.get("target_name", "")
+            if not target_name:
+                continue
+
+            # Try exact qualified name first
+            match = qname_to_sym.get(target_name)
+            if match is None:
+                # Try suffix: e.g. "UserService" in "myapp.services.UserService"
+                suffix_matches = [
+                    s for s in all_symbols
+                    if s.qualified_name.endswith(f".{target_name}") or s.name == target_name
+                ]
+                if len(suffix_matches) == 1:
+                    match = suffix_matches[0]
+                elif len(suffix_matches) > 1:
+                    # Multiple matches — pick the most specific (shortest qualified name)
+                    match = min(suffix_matches, key=lambda s: len(s.qualified_name))
+
+            if match:
+                resolution = (
+                    ResolutionStatus.RESOLVED
+                    if qname_to_sym.get(target_name) == match
+                    else ResolutionStatus.PROBABLE
+                )
+                self._store.update_relationship(rel.id, match.id, resolution)  # type: ignore[arg-type]
+                resolved_count += 1
+
+        return resolved_count
+
+
+# ---------------------------------------------------------------------------
+# Stats dataclass
+# ---------------------------------------------------------------------------
+
+
+class IndexStats:
+    """Summary statistics from an index run."""
+
+    def __init__(
+        self,
+        files_discovered: int,
+        files_analyzed: int,
+        symbols_extracted: int,
+        relationships_extracted: int,
+        relationships_resolved: int,
+        errors: list[str],
+    ) -> None:
+        self.files_discovered = files_discovered
+        self.files_analyzed = files_analyzed
+        self.symbols_extracted = symbols_extracted
+        self.relationships_extracted = relationships_extracted
+        self.relationships_resolved = relationships_resolved
+        self.errors = errors
+
+    def __repr__(self) -> str:
+        return (
+            f"IndexStats(files={self.files_analyzed}/{self.files_discovered}, "
+            f"symbols={self.symbols_extracted}, "
+            f"relationships={self.relationships_extracted}, "
+            f"resolved={self.relationships_resolved}, "
+            f"errors={len(self.errors)})"
+        )

node_walk/ir/__init__.py

@@ -0,0 +1,39 @@
+"""
+node_walk.ir — Code Intermediate Representation.
+
+Re-exports everything from enums and models so consumers can do:
+
+    from node_walk.ir import Symbol, SymbolKind, Relationship
+    # or
+    from node_walk.ir.models import Symbol
+    # or
+    from node_walk.ir.enums import SymbolKind
+"""
+
+from node_walk.ir.enums import (
+    Language,
+    RelationshipType,
+    ResolutionStatus,
+    SymbolKind,
+)
+from node_walk.ir.models import (
+    AnalysisResult,
+    FileInfo,
+    Relationship,
+    SourceLocation,
+    Symbol,
+)
+
+__all__ = [
+    # enums
+    "Language",
+    "RelationshipType",
+    "ResolutionStatus",
+    "SymbolKind",
+    # models
+    "AnalysisResult",
+    "FileInfo",
+    "Relationship",
+    "SourceLocation",
+    "Symbol",
+]

node_walk/ir/enums.py

@@ -0,0 +1,61 @@
+"""
+Code IR enums — all enumerated types used across the graph model.
+
+Kept separate from data models so enum values can be imported
+without pulling in Pydantic (e.g. in lightweight scripts or tests).
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class SymbolKind(StrEnum):
+    """Canonical kinds of code symbols across all supported languages."""
+
+    FILE = "FILE"
+    MODULE = "MODULE"
+    PACKAGE = "PACKAGE"
+    CLASS = "CLASS"
+    INTERFACE = "INTERFACE"   # ABCs and typing.Protocol in Python
+    FUNCTION = "FUNCTION"
+    METHOD = "METHOD"
+    VARIABLE = "VARIABLE"
+    CONSTANT = "CONSTANT"
+    FIELD = "FIELD"           # class-level attribute / instance variable
+
+
+class RelationshipType(StrEnum):
+    """Canonical relationship types between symbols."""
+
+    # Structural
+    CONTAINS = "CONTAINS"       # parent → child (module → class, class → method, …)
+
+    # Dependencies
+    IMPORTS = "IMPORTS"         # file/module → imported symbol or module
+
+    # Call graph
+    CALLS = "CALLS"             # caller → callee
+
+    # References
+    REFERENCES = "REFERENCES"   # any name usage that isn't a call
+
+    # Inheritance / interface
+    EXTENDS = "EXTENDS"         # subclass → base class
+    IMPLEMENTS = "IMPLEMENTS"   # concrete class → ABC / Protocol
+    OVERRIDES = "OVERRIDES"     # overriding method → overridden method
+
+
+class Language(StrEnum):
+    """Supported programming languages."""
+
+    PYTHON = "python"
+    UNKNOWN = "unknown"
+
+
+class ResolutionStatus(StrEnum):
+    """How confidently a relationship was resolved."""
+
+    RESOLVED = "resolved"       # statically certain
+    PROBABLE = "probable"       # high-confidence heuristic
+    UNRESOLVED = "unresolved"   # could not determine target

node_walk/ir/models.py

@@ -0,0 +1,100 @@
+"""
+Code IR data models — Pydantic v2 models for the semantic graph.
+
+All models are immutable (frozen=True). Language analyzers produce
+AnalysisResult objects; the storage and query layers consume them.
+
+Enums live in node_walk.ir.enums — import from there if you only
+need enum values without the Pydantic models.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from node_walk.ir.enums import Language, RelationshipType, ResolutionStatus, SymbolKind
+
+
+class FileInfo(BaseModel):
+    """Represents a source file discovered during indexing."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    path: str                            # absolute path on disk
+    language: Language = Language.UNKNOWN
+    content_hash: str = ""               # SHA-256 hex; empty until computed
+    size_bytes: int = 0
+
+    model_config = {"frozen": True}
+
+
+class Symbol(BaseModel):
+    """
+    A named code entity (class, function, method, variable, …).
+
+    Every symbol belongs to a file and may have a parent symbol
+    (e.g., a method inside a class).
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    name: str                            # simple name: "createUser"
+    qualified_name: str                  # fully-qualified: "pkg.module.Class.method"
+    kind: SymbolKind
+    language: Language = Language.PYTHON
+    file_id: str                         # FK → FileInfo.id
+    start_line: int                      # 1-indexed
+    end_line: int                        # 1-indexed, inclusive
+    signature: str = ""                  # e.g. "(self, user: User) -> None"
+    parent_id: str | None = None         # FK → Symbol.id of enclosing scope
+    docstring: str = ""                  # first docstring if present
+    is_async: bool = False
+
+    model_config = {"frozen": True}
+
+
+class SourceLocation(BaseModel):
+    """A precise location in source code (for relationship call sites)."""
+
+    file_id: str
+    line: int       # 1-indexed
+    col: int = 0    # 0-indexed column
+
+    model_config = {"frozen": True}
+
+
+class Relationship(BaseModel):
+    """
+    A directed edge between two symbols in the semantic graph.
+
+    source → [type] → target
+
+    The ``resolution`` field captures how confident the analyzer was
+    when resolving the target symbol. UNRESOLVED relationships are
+    stored with target_id = "" so callers can filter them out.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    source_id: str                               # FK → Symbol.id
+    target_id: str                               # FK → Symbol.id; "" if unresolved
+    type: RelationshipType
+    source_location: SourceLocation | None = None  # call-site / import-site
+    resolution: ResolutionStatus = ResolutionStatus.RESOLVED
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"frozen": True}
+
+
+class AnalysisResult(BaseModel):
+    """
+    Complete output from analyzing a single file.
+
+    Produced by a LanguageAnalyzer and consumed by the storage layer.
+    """
+
+    file: FileInfo
+    symbols: list[Symbol] = Field(default_factory=list)
+    relationships: list[Relationship] = Field(default_factory=list)
+
+    model_config = {"frozen": True}

node_walk/query/__init__.py

@@ -0,0 +1 @@
+"""Query engine — semantic graph navigation."""