node-walk 0.1.0__py3-none-any.whl

node_walk/__init__.py

@@ -0,0 +1,3 @@
+"""CodeGraph — Semantic code intelligence for humans and LLMs."""
+
+__version__ = "0.1.0"

node_walk/analysis/__init__.py

@@ -0,0 +1,12 @@
+"""
+node_walk.analysis — language analysis layer.
+
+Canonical imports:
+    from node_walk.analysis.base import LanguageAnalyzer, FileDiscovery
+    from node_walk.analysis.python import PythonAnalyzer
+"""
+
+from node_walk.analysis.base import FileDiscovery, LanguageAnalyzer
+from node_walk.analysis.python import PythonAnalyzer
+
+__all__ = ["FileDiscovery", "LanguageAnalyzer", "PythonAnalyzer"]

node_walk/analysis/base.py

@@ -0,0 +1,205 @@
+"""
+Language analysis base — adapter interface and file discovery.
+
+All language-specific analyzers must implement LanguageAnalyzer.
+FileDiscovery handles walking a repository and routing files to
+the correct analyzer based on extension / content sniffing.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from node_walk.ir.models import AnalysisResult, FileInfo, Language
+
+# ---------------------------------------------------------------------------
+# File extension → language mapping
+# ---------------------------------------------------------------------------
+
+_EXTENSION_MAP: dict[str, Language] = {
+    ".py": Language.PYTHON,
+    ".pyi": Language.PYTHON,
+}
+
+# Directories that are never useful to index
+_SKIP_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        "node_modules",
+        ".venv",
+        "venv",
+        "env",
+        ".env",
+        "dist",
+        "build",
+        ".node_walk",
+        ".eggs",
+        "*.egg-info",
+    }
+)
+
+# Files that are never useful to index
+_SKIP_FILE_PATTERNS: frozenset[str] = frozenset(
+    {
+        ".DS_Store",
+        "Thumbs.db",
+    }
+)
+
+
+def _should_skip_dir(name: str) -> bool:
+    return name in _SKIP_DIRS or name.endswith(".egg-info")
+
+
+def _compute_hash(path: Path) -> str:
+    """Return SHA-256 hex digest of a file's contents."""
+    h = hashlib.sha256()
+    try:
+        with path.open("rb") as f:
+            for chunk in iter(lambda: f.read(65536), b""):
+                h.update(chunk)
+    except OSError:
+        return ""
+    return h.hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Language analyzer interface
+# ---------------------------------------------------------------------------
+
+
+class LanguageAnalyzer(ABC):
+    """
+    Abstract base for language-specific analyzers.
+
+    Each implementation parses source files for one language and
+    returns an AnalysisResult containing the discovered symbols and
+    relationships (expressed as Code IR objects).
+    """
+
+    @property
+    @abstractmethod
+    def supported_languages(self) -> list[Language]:
+        """Languages this analyzer handles."""
+        ...
+
+    @abstractmethod
+    def analyze(self, file_info: FileInfo, source: str) -> AnalysisResult:
+        """
+        Parse *source* (the full text of *file_info.path*) and return
+        an AnalysisResult with all extracted symbols and relationships.
+
+        The analyzer must NOT perform I/O; the caller reads the file and
+        passes the text in. This makes analyzers trivially testable.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# File discovery
+# ---------------------------------------------------------------------------
+
+
+class FileDiscovery:
+    """
+    Walks a repository root, detects file languages, and produces FileInfo
+    objects ready for analysis.
+
+    Does not perform analysis itself — that is delegated to analyzers.
+    """
+
+    def __init__(self, root: str | Path, include_languages: list[Language] | None = None):
+        self.root = Path(root).resolve()
+        self._include = set(include_languages) if include_languages else None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def discover(self) -> list[tuple[FileInfo, str]]:
+        """
+        Walk the repository and return a list of (FileInfo, source_text)
+        tuples for every file that should be analyzed.
+
+        Skips binary files and directories in the skip list.
+        Returns files in a deterministic order (sorted by path).
+        """
+        results: list[tuple[FileInfo, str]] = []
+
+        for dirpath, dirnames, filenames in os.walk(self.root):
+            # Prune directories in-place so os.walk skips them
+            dirnames[:] = sorted(
+                d for d in dirnames if not _should_skip_dir(d)
+            )
+
+            for filename in sorted(filenames):
+                if filename in _SKIP_FILE_PATTERNS:
+                    continue
+
+                full_path = Path(dirpath) / filename
+                language = self._detect_language(full_path)
+
+                if language == Language.UNKNOWN:
+                    continue
+                if self._include and language not in self._include:
+                    continue
+
+                source = self._read_safe(full_path)
+                if source is None:
+                    continue  # binary or unreadable
+
+                rel_path = str(full_path.relative_to(self.root))
+                file_info = FileInfo(
+                    path=str(full_path),
+                    language=language,
+                    content_hash=_compute_hash(full_path),
+                    size_bytes=full_path.stat().st_size,
+                )
+                results.append((file_info, source))
+
+        return results
+
+    def discover_file(self, path: str | Path) -> tuple[FileInfo, str] | None:
+        """Discover a single file. Returns None if unsupported or unreadable."""
+        full_path = Path(path).resolve()
+        language = self._detect_language(full_path)
+        if language == Language.UNKNOWN:
+            return None
+        source = self._read_safe(full_path)
+        if source is None:
+            return None
+        file_info = FileInfo(
+            path=str(full_path),
+            language=language,
+            content_hash=_compute_hash(full_path),
+            size_bytes=full_path.stat().st_size,
+        )
+        return file_info, source
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _detect_language(path: Path) -> Language:
+        suffix = path.suffix.lower()
+        return _EXTENSION_MAP.get(suffix, Language.UNKNOWN)
+
+    @staticmethod
+    def _read_safe(path: Path) -> str | None:
+        """Read a text file. Returns None if it appears binary or cannot be read."""
+        try:
+            text = path.read_text(encoding="utf-8", errors="strict")
+            return text
+        except (UnicodeDecodeError, OSError):
+            return None

node_walk/analysis/python/__init__.py

@@ -0,0 +1,10 @@
+"""
+analysis.python — Python language adapter package.
+
+Canonical import:
+    from node_walk.analysis.python import PythonAnalyzer
+"""
+
+from node_walk.analysis.python.analyzer import PythonAnalyzer
+
+__all__ = ["PythonAnalyzer"]

node_walk/analysis/python/analyzer.py

@@ -0,0 +1,44 @@
+"""
+PythonAnalyzer — thin adapter that wires Tree-sitter parsing to the visitor.
+
+This module intentionally contains very little logic. Its job is to:
+  1. Parse source text into a Tree-sitter syntax tree.
+  2. Hand the tree to SymbolCollector.
+  3. Return the collected AnalysisResult.
+
+All symbol extraction and relationship logic lives in visitor.py.
+"""
+
+from __future__ import annotations
+
+from node_walk.analysis.base import LanguageAnalyzer
+from node_walk.analysis.python.visitor import SymbolCollector, _PARSER
+from node_walk.ir.enums import Language
+from node_walk.ir.models import AnalysisResult, FileInfo
+
+
+class PythonAnalyzer(LanguageAnalyzer):
+    """
+    Tree-sitter-based Python language adapter.
+
+    Thread-safe: the parser is a module-level singleton and parse()
+    returns a new tree each call.
+    """
+
+    @property
+    def supported_languages(self) -> list[Language]:
+        return [Language.PYTHON]
+
+    def analyze(self, file_info: FileInfo, source: str) -> AnalysisResult:
+        """Parse *source* and return all extracted symbols and relationships."""
+        source_bytes = source.encode("utf-8")
+        tree = _PARSER.parse(source_bytes)
+
+        collector = SymbolCollector(file_info, source_bytes)
+        collector.visit(tree.root_node)
+
+        return AnalysisResult(
+            file=file_info,
+            symbols=collector.symbols,
+            relationships=collector.relationships,
+        )

node_walk/analysis/python/scope.py

@@ -0,0 +1,44 @@
+"""
+Scope stack — tracks symbol nesting during AST traversal.
+
+Kept separate from the visitor so the visitor module stays focused
+on AST logic, not bookkeeping.
+"""
+
+from __future__ import annotations
+
+from node_walk.ir.models import Symbol
+
+
+class Scope:
+    """
+    Tracks the current nesting of symbols during AST traversal.
+
+    The scope stack mirrors the Python scope rules: module → class →
+    method/function → nested function. Push on entry, pop on exit.
+    """
+
+    def __init__(self) -> None:
+        self._stack: list[Symbol] = []
+
+    def push(self, sym: Symbol) -> None:
+        self._stack.append(sym)
+
+    def pop(self) -> Symbol | None:
+        return self._stack.pop() if self._stack else None
+
+    @property
+    def current(self) -> Symbol | None:
+        """The innermost enclosing symbol, or None at module top-level."""
+        return self._stack[-1] if self._stack else None
+
+    def qualified_prefix(self, module_qname: str) -> str:
+        """
+        Build the dotted qualified-name prefix for a new symbol.
+
+        Combines the module qualified name with all symbols currently
+        on the stack, e.g. "myapp.services.UserService".
+        """
+        parts = [module_qname] if module_qname else []
+        parts.extend(s.name for s in self._stack)
+        return ".".join(parts)