compass-code 0.1.0__py3-none-any.whl

compass_core/languages/python/import_resolver.py

@@ -0,0 +1,107 @@
+"""Python import resolution: relative imports, packages, __init__.py.
+
+Moved from resolver/import_map.py, adapted to the ImportResolver Protocol
+and IR types. Relative imports (`.user`, `..utils`) are resolved against the
+importing file's own package, per Python's relative-import level rules:
+one leading dot means "this file's package", each additional dot walks up
+one more parent package. A package's `__init__.py` *is* its package, so its
+own leading-dot imports resolve relative to its own module_name rather than
+a parent of it.
+"""
+
+from __future__ import annotations
+
+from compass_core.ir.models import ParsedFile
+from compass_core.shared_types import Language
+
+
+class PythonImportResolver:
+    language_id = Language.PYTHON
+
+    def resolve(self, files: list[ParsedFile]) -> dict[str, dict[str, str | None]]:
+        module_to_path = _module_index(files)
+        return {pf.path: _resolve_file_imports(pf, module_to_path) for pf in files}
+
+
+def _module_index(files: list[ParsedFile]) -> dict[str, str]:
+    """Build a mapping of module names to their file paths."""
+    return {pf.module_name: pf.path for pf in files}
+
+
+def _resolve_file_imports(pf: ParsedFile, module_to_path: dict[str, str]) -> dict[str, str | None]:
+    """Resolve all imports in a single file to their source file paths."""
+    mapping: dict[str, str | None] = {}
+    for imp in pf.imports:
+        resolved = _resolve_module(imp.module, pf, module_to_path)
+        if imp.names:
+            # `from X import a, b, *` — each name gets its own entry
+            for name in imp.names:
+                local = imp.alias if (len(imp.names) == 1 and imp.alias) else name
+                target = resolved
+                if imp.is_relative and not imp.module.lstrip("."):
+                    # `from . import name` / `from .. import name` — each
+                    # imported name is usually a submodule of the base
+                    # package (try that first); fall back to the generic
+                    # resolution (the base package's own file) for names
+                    # that are attributes defined in its __init__.py itself.
+                    target = (
+                        _resolve_bare_relative(imp.module, name, pf, module_to_path) or resolved
+                    )
+                mapping[local] = target
+        else:
+            # `import X` or `import X as Y`
+            local = imp.alias or imp.module.split(".")[0]
+            mapping[local] = resolved
+    return mapping
+
+
+def _resolve_module(
+    module: str, importer: ParsedFile, module_to_path: dict[str, str]
+) -> str | None:
+    """Resolve a dotted module name to an absolute file path.
+
+    Returns the file path if the module is internal to the repo, or None
+    if it is an external dependency.
+    """
+    if not module.startswith("."):
+        return module_to_path.get(module)
+
+    base_parts = _base_package_parts(module, importer)
+    remainder = module.lstrip(".")
+    target_parts = base_parts + remainder.split(".") if remainder else base_parts
+    candidate = ".".join(part for part in target_parts if part)
+    return module_to_path.get(candidate)
+
+
+def _base_package_parts(module: str, importer: ParsedFile) -> list[str]:
+    """Compute the dotted package an import's leading dots are relative to.
+
+    One dot means "the importing file's own package". A package's
+    `__init__.py` *is* that package, so its own module_name is the base;
+    any other file's base is its module_name with the last (leaf module)
+    segment stripped. Each dot beyond the first walks up one more level.
+    """
+    level = len(module) - len(module.lstrip("."))
+    is_package_init = importer.path.endswith("__init__.py") or importer.path.endswith(
+        "__init__.pyi"
+    )
+    parts = importer.module_name.split(".") if importer.module_name else []
+    if not is_package_init:
+        parts = parts[:-1]
+    climb = level - 1
+    if climb:
+        parts = parts[:-climb] if climb <= len(parts) else []
+    return parts
+
+
+def _resolve_bare_relative(
+    module: str, name: str, importer: ParsedFile, module_to_path: dict[str, str]
+) -> str | None:
+    """Resolve one name from `from . import name` / `from .. import name`.
+
+    Each name here is a submodule of the base package rather than an
+    attribute of a single target module, so it must be resolved per-name.
+    """
+    base_parts = _base_package_parts(module, importer)
+    candidate = ".".join([*base_parts, name])
+    return module_to_path.get(candidate)

compass_core/languages/registry.py

@@ -0,0 +1,89 @@
+"""Extension/language-id -> plugin lookup. No phase past Phase 1 may know a
+specific language — this module is the only place that maps a file
+extension to a concrete LanguageExtractor."""
+
+from __future__ import annotations
+
+from compass_core.errors import UnsupportedLanguageError
+from compass_core.languages.base import ImportResolver, LanguageExtractor
+from compass_core.shared_types import Language
+
+_extractors_by_extension: dict[str, LanguageExtractor] = {}
+_extractors_by_language: dict[Language, LanguageExtractor] = {}
+_import_resolvers_by_language: dict[Language, ImportResolver] = {}
+
+
+def register_extractor(extractor: LanguageExtractor) -> None:
+    for ext in extractor.file_extensions:
+        _extractors_by_extension[ext] = extractor
+    _extractors_by_language[extractor.language_id] = extractor
+
+
+def register_import_resolver(resolver: ImportResolver) -> None:
+    _import_resolvers_by_language[resolver.language_id] = resolver
+
+
+def get_extractor_for_extension(ext: str) -> LanguageExtractor:
+    try:
+        return _extractors_by_extension[ext]
+    except KeyError:
+        raise UnsupportedLanguageError(
+            f"no extractor registered for extension {ext!r}", language=ext
+        ) from None
+
+
+def get_extractor_for_language(language_id: Language) -> LanguageExtractor:
+    try:
+        return _extractors_by_language[language_id]
+    except KeyError:
+        raise UnsupportedLanguageError(
+            f"no extractor registered for language {language_id!r}", language=language_id
+        ) from None
+
+
+def get_import_resolver(language_id: Language) -> ImportResolver:
+    try:
+        return _import_resolvers_by_language[language_id]
+    except KeyError:
+        raise UnsupportedLanguageError(
+            f"no import resolver registered for language {language_id!r}", language=language_id
+        ) from None
+
+
+def registered_extensions() -> set[str]:
+    return set(_extractors_by_extension.keys())
+
+
+def _snapshot_for_tests() -> tuple[
+    dict[str, LanguageExtractor], dict[Language, LanguageExtractor], dict[Language, ImportResolver]
+]:
+    """Test-only: capture current registry state so it can be restored after a test wipes it."""
+    return (
+        dict(_extractors_by_extension),
+        dict(_extractors_by_language),
+        dict(_import_resolvers_by_language),
+    )
+
+
+def _restore_for_tests(
+    snapshot: tuple[
+        dict[str, LanguageExtractor],
+        dict[Language, LanguageExtractor],
+        dict[Language, ImportResolver],
+    ],
+) -> None:
+    """Test-only: restore registry state captured by _snapshot_for_tests."""
+    by_ext, by_lang, resolvers = snapshot
+    _extractors_by_extension.clear()
+    _extractors_by_extension.update(by_ext)
+    _extractors_by_language.clear()
+    _extractors_by_language.update(by_lang)
+    _import_resolvers_by_language.clear()
+    _import_resolvers_by_language.update(resolvers)
+
+
+def _reset_for_tests() -> None:
+    """Test-only: clear registry state between tests. Not part of the public API."""
+    _extractors_by_extension.clear()
+    _extractors_by_language.clear()
+    _import_resolvers_by_language.clear()

compass_core/logger.py

@@ -0,0 +1,42 @@
+"""Centralized logging configuration for Code Compass.
+
+Call :func:`setup` once at process startup (e.g. from the CLI entry point).
+All other modules should continue to use ``logging.getLogger(__name__)`` —
+this module only configures the root handler.
+
+Example::
+
+    from compass_core.log import setup
+    setup(level="INFO")
+"""
+
+from __future__ import annotations
+
+import logging
+
+from rich.logging import RichHandler
+
+
+def setup(level: str = "WARNING", *, show_path: bool = False) -> None:
+    """Configure the root logger with a Rich console handler.
+
+    Args:
+        level: Log level string (e.g. ``"DEBUG"``, ``"INFO"``, ``"WARNING"``).
+            Defaults to ``"WARNING"`` so only important messages surface in the
+            CLI by default.
+        show_path: Whether Rich should append the source file/line to each
+            log line.  Useful in debug mode, noisy otherwise.
+    """
+    handler = RichHandler(
+        rich_tracebacks=True,
+        markup=True,
+        show_path=show_path,
+        log_time_format="[%X]",
+    )
+    logging.basicConfig(
+        level=level.upper(),
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[handler],
+        force=True,
+    )

compass_core/phases/base.py

@@ -0,0 +1,58 @@
+"""The Phase Protocol and IngestContext that flows through phases 0-5.
+Enables `compass ingest --stop-after <phase>` for debugging and lets any
+phase be unit-tested with a hand-built ctx, no upstream phase required."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from compass_core.graph.writer import WriteResult
+from compass_core.ir.graph import ResolvedGraph
+from compass_core.ir.models import ParsedFile
+from compass_core.progress import ProgressReporter
+from compass_core.shared_types import Language
+
+
+@dataclass(slots=True)
+class FileMetadata:
+    path: Path
+    language: Language
+    content_hash: str
+
+
+@dataclass
+class FileManifest:
+    files: list[FileMetadata]
+    dirs_scanned: int = 0
+    ignored_count: int = 0
+
+
+@dataclass
+class IngestReport:
+    resolved_by_language: dict[Language, float]
+    unresolved_by_language: dict[Language, float]
+    dangling_import_count: int
+    orphan_node_count: int
+    degraded_file_count: int
+
+
+@dataclass
+class IngestContext:
+    repo_root: Path
+    manifest: FileManifest | None = None
+    parsed_files: list[ParsedFile] | None = None
+    symbol_table: dict[str, str] | None = None
+    import_map: dict[str, dict[str, str | None]] | None = None
+    resolved_graph: ResolvedGraph | None = None
+    report: IngestReport | None = None
+    reporter: ProgressReporter | None = None
+    write_result: WriteResult | None = None
+
+
+@runtime_checkable
+class Phase(Protocol):
+    name: str
+
+    def run(self, ctx: IngestContext) -> IngestContext: ...

compass_core/phases/discovery.py

@@ -0,0 +1,167 @@
+"""Phase 0: repo path -> FileManifest. Walks the repo respecting
+.gitignore/.compassignore, detects language per file via the registry's
+known extensions, filters binaries/vendored/generated code, and computes a
+content_hash per file (unused for skip-logic yet — captured now for future
+incremental re-index, per spec)."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+import pathspec
+
+from compass_core.errors import DiscoveryError
+from compass_core.languages import registry
+from compass_core.phases.base import FileManifest, FileMetadata, IngestContext
+
+logger = logging.getLogger(__name__)
+
+_SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".claude",
+        "__pycache__",
+        "node_modules",
+        ".venv",
+        "venv",
+        "env",
+        "dist",
+        "build",
+        ".tox",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+        ".eggs",
+        "*.egg-info",
+    }
+)
+_MAX_BYTES = 500 * 1024
+
+
+@dataclass
+class _WalkStats:
+    """Counts skipped directories/files as a byproduct of the walk, so the
+    manifest can report how much of the repo was filtered out without a
+    second traversal."""
+
+    dirs_scanned: int = 0
+    ignored_count: int = 0
+
+
+class DiscoveryPhase:
+    name = "discovery"
+
+    def run(self, ctx: IngestContext) -> IngestContext:
+        root = ctx.repo_root.resolve()
+        if not root.is_dir():
+            raise DiscoveryError(f"not a directory: {root}", phase_name=self.name)
+
+        spec = _load_ignore_spec(root)
+        extensions = registry.registered_extensions()
+        stats = _WalkStats()
+        files: list[FileMetadata] = []
+        for path in _walk(root, root, spec, extensions, stats):
+            language = registry.get_extractor_for_extension(path.suffix).language_id
+            content_hash = hashlib.sha256(path.read_bytes()).hexdigest()
+            files.append(FileMetadata(path=path, language=language, content_hash=content_hash))
+
+        ctx.manifest = FileManifest(
+            files=files, dirs_scanned=stats.dirs_scanned, ignored_count=stats.ignored_count
+        )
+        ctx.repo_root = root
+        if ctx.reporter is not None:
+            ctx.reporter.update("discovery", len(files), len(files))
+        return ctx
+
+
+def _load_ignore_spec(root: Path) -> pathspec.PathSpec | None:
+    """Load and merge .gitignore and .compassignore pattern sets from *root*.
+
+    Moved from parser/file_walker.py::_load_gitignore, extended to also
+    consider a .compassignore file (if present), merging both pattern sets
+    into a single PathSpec.
+    """
+    lines: list[str] = []
+    for name in (".gitignore", ".compassignore"):
+        ignore_file = root / name
+        if not ignore_file.is_file():
+            continue
+        try:
+            lines.extend(ignore_file.read_text(encoding="utf-8", errors="replace").splitlines())
+        except OSError as exc:
+            logger.warning("Could not read %s: %s", name, exc)
+
+    if not lines:
+        return None
+    return pathspec.PathSpec.from_lines("gitwildmatch", lines)
+
+
+def _walk(
+    current: Path,
+    root: Path,
+    spec: pathspec.PathSpec | None,
+    extensions: set[str],
+    stats: _WalkStats,
+) -> Iterator[Path]:
+    """Recursively traverse directories to find files with a registered extension.
+
+    Generalized from parser/file_walker.py::_recurse — same PermissionError
+    isolation (catch, log at debug, skip) and _should_skip_dir/_should_skip_file
+    logic, but filters on `entry.suffix in extensions` instead of `== ".py"`.
+    """
+    try:
+        entries = sorted(current.iterdir(), key=lambda p: (p.is_file(), p.name))
+    except PermissionError as exc:
+        logger.debug("Permission denied, skipping: %s (%s)", current, exc)
+        return
+
+    stats.dirs_scanned += 1
+    for entry in entries:
+        if entry.is_dir():
+            if _should_skip_dir(entry, root, spec):
+                stats.ignored_count += 1
+                continue
+            yield from _walk(entry, root, spec, extensions, stats)
+
+        elif entry.is_file() and entry.suffix in extensions:
+            if _should_skip_file(entry, root, spec):
+                stats.ignored_count += 1
+                continue
+            yield entry
+
+
+def _should_skip_dir(entry: Path, root: Path, spec: pathspec.PathSpec | None) -> bool:
+    """Determine if a directory should be skipped during traversal.
+
+    Checks against common skip directories and .gitignore/.compassignore rules.
+    """
+    if entry.name in _SKIP_DIRS:
+        return True
+    if spec is not None:
+        # pathspec expects forward-slash paths; append "/" for directory matching
+        rel = entry.relative_to(root).as_posix() + "/"
+        if spec.match_file(rel):
+            return True
+    return False
+
+
+def _should_skip_file(entry: Path, root: Path, spec: pathspec.PathSpec | None) -> bool:
+    """Determine if a file should be skipped during discovery.
+
+    Checks against .gitignore/.compassignore rules and file size limits.
+    """
+    if spec is not None:
+        rel = entry.relative_to(root).as_posix()
+        if spec.match_file(rel):
+            return True
+    try:
+        if entry.stat().st_size > _MAX_BYTES:
+            logger.debug("Skipping large file (%d bytes): %s", entry.stat().st_size, entry)
+            return True
+    except OSError:
+        return True
+    return False

compass_core/phases/parse.py

@@ -0,0 +1,80 @@
+"""Phase 1: FileManifest -> list[ParsedFile]. tree-sitter parse per file,
+dispatched via the language registry, run in ProcessPoolExecutor. Per-file
+errors isolate (degraded flag on ParsedFile), never kill the pool — this is
+the single most important error-isolation point in the pipeline."""
+
+from __future__ import annotations
+
+import os
+import traceback
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from functools import cache
+from pathlib import Path
+
+from compass_core.ir.models import ParsedFile
+from compass_core.languages import registry
+from compass_core.languages.base import LanguageExtractor
+from compass_core.phases.base import IngestContext
+from compass_core.shared_types import Language
+
+
+@cache
+def _get_extractor(language_id: Language) -> LanguageExtractor:
+    return registry.get_extractor_for_language(language_id)
+
+
+def _parse_one(language_id: Language, abs_path: str, rel_path: str) -> ParsedFile:
+    """rel_path is abs_path made relative to ctx.repo_root by the caller.
+    Extractors receive the relative path (per the languages/python module-name
+    contract established in Task 5: file_path is repo-relative, not absolute,
+    so module-name derivation can build a dotted name without needing root
+    itself) — abs_path is only used here, to actually read the file's bytes."""
+    extractor = _get_extractor(language_id)
+    with open(abs_path, "rb") as f:
+        source = f.read()
+    return extractor.parse(source, Path(rel_path))
+
+
+def _parse_worker(args: tuple[Language, str, str]) -> ParsedFile:
+    language_id, abs_path, rel_path = args
+    try:
+        return _parse_one(language_id, abs_path, rel_path)
+    except Exception as exc:  # noqa: BLE001 — per-file isolation boundary, see module docstring
+        traceback.print_exc()
+        return ParsedFile(
+            path=rel_path,
+            language=language_id,
+            module_name="",
+            content_hash="",
+            definitions=[],
+            imports=[],
+            call_sites=[],
+            degraded=True,
+            error=str(exc),
+        )
+
+
+class ParsePhase:
+    name = "parse"
+
+    def __init__(self, max_workers: int | None = None) -> None:
+        self._max_workers = max_workers
+
+    def run(self, ctx: IngestContext) -> IngestContext:
+        assert ctx.manifest is not None, "ParsePhase requires DiscoveryPhase to run first"
+        tasks = [
+            (f.language, str(f.path), str(f.path.relative_to(ctx.repo_root)))
+            for f in ctx.manifest.files
+        ]
+        workers = self._max_workers or os.cpu_count() or 1
+
+        parsed: list[ParsedFile] = []
+        with ProcessPoolExecutor(max_workers=workers) as pool:
+            futures = {pool.submit(_parse_worker, task): task for task in tasks}
+            for done, future in enumerate(as_completed(futures), start=1):
+                parsed.append(future.result())
+                if ctx.reporter is not None:
+                    ctx.reporter.update("parse", done, len(tasks))
+
+        ctx.parsed_files = parsed
+        return ctx

compass_core/phases/persistence.py

@@ -0,0 +1,33 @@
+"""Phase 5: ResolvedGraph -> LadybugDB. Nodes before edges, per
+graph/writer.py's write order (File -> Class -> Function -> ExternalFunction
+nodes, then CONTAINS -> IMPORTS -> INHERITS -> CALLS -> CALLS_EXTERN edges).
+
+Deliberately deviates from the uniform Phase Protocol: `run` takes an extra
+`db: GraphDB` argument because the DB connection is a context-managed
+resource owned by phases/pipeline.py, not something this phase constructs
+itself. pipeline.py calls this phase specially, not through the generic
+phase loop."""
+
+from __future__ import annotations
+
+from compass_core.errors import PersistenceError
+from compass_core.graph.db import GraphDB
+from compass_core.graph.writer import write
+from compass_core.phases.base import IngestContext
+
+
+class PersistencePhase:
+    name = "persistence"
+
+    def run(self, ctx: IngestContext, db: GraphDB) -> IngestContext:
+        assert ctx.resolved_graph is not None
+        try:
+            ctx.write_result = write(db, ctx.resolved_graph, reporter=ctx.reporter)
+        except PersistenceError:
+            raise
+        except Exception as exc:  # noqa: BLE001 — unrecoverable DB failure boundary
+            raise PersistenceError(
+                f"failed to persist resolved graph: {exc}",
+                phase_name=self.name,
+            ) from exc
+        return ctx