codepulse-engine 0.1.0__py3-none-any.whl

codepulse/mcp_server.py

@@ -0,0 +1,269 @@
+"""
+Phase 5.3 -- MCP server (roadmap §37 item 5.3; §13 MCP Strategy).
+
+§13, quoted and held to strictly: *"Recommendation: yes, expose an MCP
+server -- but strictly as an adapter, not a parallel implementation.
+Each MCP tool calls the exact same internal Python functions the REST
+API calls."* *"Proposed tools: search_code, get_symbol, find_callers,
+find_callees, impact_analysis, find_similar, get_context (the §12
+bundle)."* *"Permissions/repository selection: MCP connections are
+scoped to one or more repositories at connection-setup time (via the
+same API-key/permission model as REST -- §16), not per-tool-call."*
+*"Failure behavior: tool calls return structured errors
+({"error": "repository_not_indexed", "message": "..."}) rather than
+throwing opaque exceptions."*
+
+Architecture: this module is a THIN adapter over `IndexingEngine` and
+`codepulse.auth`/`codepulse.api.security`'s existing authorization
+primitives -- it introduces no new graph/retrieval/authorization logic
+of its own. `build_mcp_server(storage, engine, api_key)` resolves the
+given API key to an `AuthorizedKey` exactly ONCE, via the same
+`verify_api_key` (Phase 1.1) function REST's own `require_api_key`
+dependency calls -- not a second authentication mechanism -- and every
+tool call authorizes against that SAME resolved `repository_ids` set,
+never re-authenticating per call (per §13's own explicit "not
+per-tool-call" instruction; FastAPI's per-request `Depends(
+require_api_key)` mechanism does not apply here since MCP tool calls
+are not individual HTTP requests).
+
+Each tool below calls the exact same `IndexingEngine` method its REST
+counterpart calls (`search`, `analyze_impact`, `find_similar_symbols`,
+`get_context_bundle`) -- `find_callers`/`find_callees` both reuse
+`analyze_impact` internally (there is no dedicated standalone
+REST/engine method for either; §13 names them as separate TOOLS, not
+as evidence of a separate implementation, so they are built as thin
+projections of the one already-tested `analyze_impact` result rather
+than a second call-graph traversal). `get_symbol`'s `called_by`/`calls`
+query mirrors `GET /v1/symbols/{id}`'s own tested query exactly
+(including the Phase 4.1 compatibility correction's `relationship_type
+== "calls"` filter) -- a small, deliberate, disclosed duplication of a
+plain parameterized DB read (not a graph algorithm), not extracted into
+a third shared location this milestone; see CODEPULSE_PROGRESS.md's
+Phase 5.3 entry for the explicit reasoning.
+
+Backend-hardening addition (not a roadmap sprint item; §13's own
+literal tool list names exactly 7): `module_structure` -- an 8th tool,
+giving Phase 4.3's `IndexingEngine.analyze_module_structure` (built
+with no MCP caller at the time, by that milestone's own explicit
+approved scope) its first MCP surface, matching the REST/CLI query
+surfaces added in the same pass.
+"""
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from codepulse.auth import verify_api_key
+from codepulse.api.security import AuthorizedKey
+from codepulse.indexer.engine import IndexingEngine
+from codepulse.storage.db import APIKeyRepositoryModel, CallEdge, StorageManager, SymbolModel
+
+
+class MCPAuthenticationError(Exception):
+    """Raised by `build_mcp_server` when the supplied API key is missing, unknown, or revoked."""
+
+
+def _structured_error(code: str, message: str) -> dict[str, str]:
+    """§13's own literal failure-behavior contract: `{"error": "...", "message": "..."}`."""
+    return {"error": code, "message": message}
+
+
+def build_mcp_server(
+    storage: StorageManager, engine: IndexingEngine, api_key: str, name: str = "codepulse"
+) -> FastMCP:
+    """
+    Builds and returns a `FastMCP` server instance scoped to the
+    repositories the given `api_key` is authorized for -- resolved
+    ONCE, at connection-setup time, per §13's explicit instruction.
+    Raises `MCPAuthenticationError` for a missing/unknown/revoked key,
+    mirroring `require_api_key`'s own HTTP 401 case (there is no HTTP
+    response here to return, so this is a plain exception the caller
+    -- e.g. `codepulse serve`, Phase 6 -- decides how to report).
+    """
+    api_key_id = verify_api_key(storage, api_key)
+    if api_key_id is None:
+        raise MCPAuthenticationError("Invalid or revoked API key")
+
+    session = storage.get_session()
+    try:
+        repo_ids = {
+            row.repo_id
+            for row in session.query(APIKeyRepositoryModel)
+            .filter(APIKeyRepositoryModel.api_key_id == api_key_id)
+            .all()
+        }
+    finally:
+        session.close()
+
+    authorized = AuthorizedKey(api_key_id=api_key_id, repository_ids=frozenset(repo_ids))
+
+    mcp: FastMCP = FastMCP(name)
+
+    def _authorize(repo_id: int) -> Optional[dict[str, str]]:
+        if repo_id not in authorized.repository_ids:
+            return _structured_error(
+                "repository_not_authorized",
+                f"This connection is not authorized for repository {repo_id}.",
+            )
+        return None
+
+    def _load_symbol(symbol_id: int) -> Optional[dict[str, Any]]:
+        """Extracts every field a tool might need into a plain dict
+        WHILE the session is open (SQLAlchemy relationship access after
+        `session.close()` would raise `DetachedInstanceError`), exactly
+        matching the "access `sym.file` before closing" pattern every
+        REST symbol route already follows."""
+        db_session = storage.get_session()
+        try:
+            sym = db_session.query(SymbolModel).filter(SymbolModel.id == symbol_id).first()
+            if not sym or not sym.file:
+                return None
+            return {
+                "id": sym.id,
+                "name": sym.name,
+                "type": sym.type,
+                "file_path": sym.file.path,
+                "repo_id": sym.file.repo_id,
+                "signature": sym.signature,
+                "docstring": sym.docstring,
+                "body": sym.body,
+                "complexity": sym.complexity,
+            }
+        finally:
+            db_session.close()
+
+    @mcp.tool()
+    def search_code(
+        query: str, repository_id: int, limit: int = 20, search_type: str = "hybrid"
+    ) -> dict[str, Any]:
+        """Hybrid/keyword/semantic/RRF search over an indexed repository's code, scoped to this connection's authorized repositories."""
+        auth_error = _authorize(repository_id)
+        if auth_error:
+            return auth_error
+        results = engine.search(query, limit=limit, search_type=search_type, repository_id=repository_id)
+        return {"results": [r.to_dict() for r in results]}
+
+    @mcp.tool()
+    def get_symbol(symbol_id: int) -> dict[str, Any]:
+        """Fetches one symbol's definition plus its direct callers/callees (calls-only, matching GET /v1/symbols/{id})."""
+        loaded = _load_symbol(symbol_id)
+        if loaded is None:
+            return _structured_error("symbol_not_found", f"No symbol with id {symbol_id}.")
+        auth_error = _authorize(loaded["repo_id"])
+        if auth_error:
+            return auth_error
+
+        db_session = storage.get_session()
+        try:
+            called_by = (
+                db_session.query(CallEdge)
+                .filter(CallEdge.target_symbol_name == loaded["name"])
+                .filter(CallEdge.repo_id == loaded["repo_id"])
+                .filter(CallEdge.relationship_type == "calls")
+                .all()
+            )
+            calls = (
+                db_session.query(CallEdge)
+                .filter(CallEdge.source_symbol_name == loaded["name"])
+                .filter(CallEdge.repo_id == loaded["repo_id"])
+                .filter(CallEdge.relationship_type == "calls")
+                .all()
+            )
+        finally:
+            db_session.close()
+
+        return {
+            "symbol_id": loaded["id"],
+            "name": loaded["name"],
+            "type": loaded["type"],
+            "file": loaded["file_path"],
+            "docstring": loaded["docstring"],
+            "source_code": loaded["body"],
+            "called_by": [
+                {"symbol": d.source_symbol_name, "file": d.source_file, "confidence": d.confidence}
+                for d in called_by
+            ],
+            "calls": [
+                {"symbol": d.target_symbol_name, "file": d.target_file, "confidence": d.confidence}
+                for d in calls
+            ],
+            "complexity": loaded["complexity"],
+        }
+
+    @mcp.tool()
+    def find_callers(symbol_id: int, depth: int = 3) -> dict[str, Any]:
+        """Symbols that call this one, direct and transitive, confidence-scored and depth-bucketed (a projection of impact_analysis's own callers side)."""
+        loaded = _load_symbol(symbol_id)
+        if loaded is None:
+            return _structured_error("symbol_not_found", f"No symbol with id {symbol_id}.")
+        auth_error = _authorize(loaded["repo_id"])
+        if auth_error:
+            return auth_error
+        impact = engine.analyze_impact(loaded["name"], loaded["file_path"], loaded["repo_id"], max_depth=depth)
+        return {"symbol": loaded["name"], "callers": impact["call_chain"]}
+
+    @mcp.tool()
+    def find_callees(symbol_id: int, depth: int = 3) -> dict[str, Any]:
+        """Symbols this one calls, direct and transitive, confidence-scored and depth-bucketed (a projection of impact_analysis's own callees side)."""
+        loaded = _load_symbol(symbol_id)
+        if loaded is None:
+            return _structured_error("symbol_not_found", f"No symbol with id {symbol_id}.")
+        auth_error = _authorize(loaded["repo_id"])
+        if auth_error:
+            return auth_error
+        impact = engine.analyze_impact(loaded["name"], loaded["file_path"], loaded["repo_id"], max_depth=depth)
+        return {"symbol": loaded["name"], "callees": impact["dependencies"]}
+
+    @mcp.tool()
+    def impact_analysis(symbol_id: int, depth: int = 3) -> dict[str, Any]:
+        """Direct-vs-transitive impact bucketing for a symbol (calls only; see CODEPULSE_PROGRESS.md's Phase 4.2 Decision 1)."""
+        loaded = _load_symbol(symbol_id)
+        if loaded is None:
+            return _structured_error("symbol_not_found", f"No symbol with id {symbol_id}.")
+        auth_error = _authorize(loaded["repo_id"])
+        if auth_error:
+            return auth_error
+        return engine.analyze_impact(loaded["name"], loaded["file_path"], loaded["repo_id"], max_depth=depth)
+
+    @mcp.tool()
+    def find_similar(symbol_id: int, threshold: float = 0.75, limit: int = 10) -> dict[str, Any]:
+        """Semantically similar symbols within the SAME repository (embedding-based, repository-scoped)."""
+        loaded = _load_symbol(symbol_id)
+        if loaded is None:
+            return _structured_error("symbol_not_found", f"No symbol with id {symbol_id}.")
+        auth_error = _authorize(loaded["repo_id"])
+        if auth_error:
+            return auth_error
+        query_text = f"{loaded['signature']}\n{loaded['docstring'] or ''}\n{loaded['body'][:500]}"
+        similar = engine.find_similar_symbols(query_text, loaded["name"], loaded["repo_id"], threshold=threshold, limit=limit)
+        return {"query_symbol": {"id": loaded["id"], "name": loaded["name"]}, "similar": similar}
+
+    @mcp.tool()
+    def get_context(symbol_id: int, include_body: bool = False, max_related: int = 10) -> dict[str, Any]:
+        """The §12 agent-native context bundle: definition, direct callers/callees, semantically related symbols, snapshot commit, and a truncation flag."""
+        loaded = _load_symbol(symbol_id)
+        if loaded is None:
+            return _structured_error("symbol_not_found", f"No symbol with id {symbol_id}.")
+        auth_error = _authorize(loaded["repo_id"])
+        if auth_error:
+            return auth_error
+        return engine.get_context_bundle(
+            loaded["name"], loaded["file_path"], loaded["repo_id"],
+            signature=loaded["signature"], docstring=loaded["docstring"], body=loaded["body"],
+            include_body=include_body, max_related=max_related,
+        )
+
+    @mcp.tool()
+    def module_structure(repository_id: int) -> dict[str, Any]:
+        """Module clusters + raw inbound/outbound degree rankings for a repository's file-level import graph (Phase 4.3's ModuleGraphBuilder, reused unmodified)."""
+        auth_error = _authorize(repository_id)
+        if auth_error:
+            return auth_error
+        module_graph = engine.analyze_module_structure(repository_id)
+        return {
+            "repository_id": repository_id,
+            "clusters": module_graph.clusters,
+            "ranked_by_inbound": module_graph.rank_by_inbound(),
+            "ranked_by_outbound": module_graph.rank_by_outbound(),
+        }
+
+    return mcp

codepulse/models.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import hashlib
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class SymbolType(str, Enum):
+    # Backend-hardening cleanup (not a roadmap sprint item): INTERFACE and
+    # VARIABLE were removed here -- grep-confirmed, before removal, to be
+    # produced by neither parser (codepulse/parser/python.py,
+    # codepulse/parser/javascript.py) and referenced nowhere else in the
+    # codebase or test suite, and confirmed absent from every row in the
+    # real codepulse.db's own symbols table. If a future parser needs to
+    # classify variables or interfaces as their own symbol kind, add the
+    # value back deliberately at that point, backed by a real producer,
+    # rather than carrying an always-empty classification indefinitely.
+    FUNCTION = "function"
+    METHOD = "method"
+    CLASS = "class"
+    MODULE = "module"
+
+
+class Symbol(BaseModel):
+    """Represents an extracted code symbol (function, method, class, etc.)."""
+    name: str
+    type: SymbolType
+    file_path: str
+    start_line: int = Field(ge=1, description="1-indexed starting line")
+    end_line: int = Field(ge=1, description="1-indexed ending line")
+    signature: str = ""
+    docstring: Optional[str] = None
+    body: str = ""
+    body_hash: str = ""
+    language: str
+    parent_symbol: Optional[str] = None
+    complexity: int = 1
+    # Phase 4.1 (roadmap §37 item 4.1: "Base-class/inheritance extraction
+    # (Python + JS/TS)"; §29: "Symbol... needs... base-class field").
+    # Raw, unresolved base-class expressions exactly as written in source
+    # (e.g. ["Base", "pkg.Mixin"]) -- populated only for CLASS symbols,
+    # always empty for every other symbol type. This is the honest,
+    # never-fabricated extraction; RESOLVING each name to a real symbol
+    # (with confidence) is a separate, derived step performed by
+    # `CallGraphBuilder` -- the exact same layering already established
+    # for `CallReference.callee_name` (raw) vs. `CallGraphEdge` (resolved,
+    # confidence-scored). A `keyword_argument` in a Python class's base
+    # list (e.g. `metaclass=Meta`) is deliberately excluded here -- it is
+    # not a base class. A TypeScript `implements` clause is also
+    # deliberately excluded -- interface implementation is a different
+    # relationship than base-class inheritance, not extracted in this
+    # milestone.
+    base_classes: list[str] = Field(default_factory=list)
+
+    def model_post_init(self, __context) -> None:
+        if not self.body_hash and self.body:
+            self.body_hash = hashlib.sha256(self.body.strip().encode("utf-8")).hexdigest()
+
+
+class ImportItem(BaseModel):
+    """An imported item with an optional alias (e.g., `from math import sqrt as s`)."""
+    name: str
+    alias: Optional[str] = None
+
+
+class ImportStatement(BaseModel):
+    """Represents an import in source code."""
+    module: str
+    items: list[ImportItem] = Field(default_factory=list)
+    is_relative: bool = False
+    level: int = 0  # Number of leading dots in relative imports
+    line_number: int = 1
+    file_path: str = ""
+
+
+class CallReference(BaseModel):
+    """A reference where a symbol/function is invoked."""
+    caller_symbol: str
+    callee_name: str
+    line_number: int
+    file_path: str
+
+
+class CallGraphEdge(BaseModel):
+    """A resolved or partially resolved call graph edge between two symbols."""
+    source_symbol_name: str
+    source_file: str
+    target_symbol_name: str
+    target_file: Optional[str] = None
+    call_count: int = 1
+    # Phase 3.4 (roadmap §37 item 3.4; §11): "high" -- resolved through an
+    # explicit import mapping to a known file+symbol; "low" -- resolved
+    # only by bare-name match against same-file symbols; "unresolved" --
+    # the callee couldn't be matched to any known symbol at all. Always
+    # set explicitly by CallGraphBuilder._build_graph (see its own
+    # comments) -- the "unresolved" default here is a safe fallback for
+    # any other construction path, never itself a claim of resolution.
+    # May be None ONLY for a legacy durable `call_edges` row written before
+    # Phase 3.4 added confidence (restored by `CallGraphBuilder.from_edges`);
+    # a graph built from parse results always sets it explicitly.
+    confidence: Optional[str] = "unresolved"
+    # Phase 4.1 (roadmap §37 item 4.1): "calls" (default, matching every
+    # edge this project has ever persisted before this field existed) or
+    # "inherits" (a resolved base-class relationship). Always set
+    # explicitly by CallGraphBuilder._build_graph for both kinds -- the
+    # "calls" default here is a safe fallback for any other construction
+    # path, matching this project's existing historical data exactly.
+    relationship_type: str = "calls"
+
+
+class FileParseResult(BaseModel):
+    """Complete AST parse result for a single file."""
+    file_path: str
+    language: str
+    symbols: list[Symbol] = Field(default_factory=list)
+    imports: list[ImportStatement] = Field(default_factory=list)
+    calls: list[CallReference] = Field(default_factory=list)
+    file_size_bytes: int = 0
+    line_count: int = 0
+    content_hash: str = Field(
+        default="",
+        description=(
+            "SHA-256 hex digest of the file's raw source content, used as the "
+            "change-detection key for idempotent File upsert (Phase 0.3)."
+        ),
+    )
+
+
+def compute_content_hash(content: str) -> str:
+    """
+    Computes a deterministic SHA-256 hex digest for whole-file content.
+
+    Follows the same hashing convention already used for `Symbol.body_hash`
+    (SHA-256 over UTF-8-encoded text). Unlike `Symbol.body_hash`, the content
+    is NOT stripped first: a file's identity hash must reflect the exact
+    persisted bytes so that whitespace-only edits still register as a real
+    content change during incremental re-indexing.
+    """
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()

codepulse/observability.py

@@ -0,0 +1,130 @@
+"""
+Phase 7.4 -- Observability wiring (roadmap §37 item 7.4; §18
+Observability Architecture: "actually wire the already-declared
+dependency" (`prometheus-client`, `structlog`) -- both were declared in
+`pyproject.toml` since Phase 0.9 but never installed or imported by any
+code until this milestone; both are now genuinely installed and used).
+
+§18, quoted and implemented exactly:
+  - **Metrics** (real Prometheus counters/histograms/gauge, named
+    exactly as listed): `search_requests_total{search_type}`,
+    `search_latency_seconds`, `indexing_jobs_total{status}`,
+    `indexing_duration_seconds`, `files_indexed_total`,
+    `symbols_indexed_total`, `embedding_duration_seconds`,
+    `job_queue_depth`, `api_errors_total{endpoint,status_code}`,
+    `search_zero_result_total`.
+  - **Logs**: structured JSON via `structlog`, with the exact field
+    set §18 names: `request_id`, `repository_id`, `job_id`,
+    `api_key_id`, `operation`, `duration_ms`, `error_type`.
+  - **Health endpoints** (`codepulse/api/app.py`): `/health/live`
+    (process up) and `/health/ready` (DB reachable, embedding model
+    loaded, index storage writable) -- built in `app.py` itself using
+    this module's `check_readiness`, kept out of this module because
+    they need live references to `storage_manager`/`indexing_engine`.
+
+This module holds a DEDICATED `CollectorRegistry` (not
+`prometheus_client`'s global default) so importing it repeatedly across
+this project's own test suite (many isolated test modules, potentially
+several `TestClient(app)` instances per test session) can never raise
+"Duplicated timeseries in CollectorRegistry" -- module-level singletons
+are created exactly once per Python process regardless of how many
+tests import this module, which is what makes a dedicated registry
+unnecessary in principle, but using one anyway is the standard,
+recommended `prometheus_client` pattern for avoiding any accidental
+collision with a DIFFERENT library's own use of the global default
+registry in the same process.
+
+Every counter/histogram below is incremented/observed from a REAL,
+already-happening event (a request actually being served, a job
+actually transitioning state, an embedding call actually completing) --
+never a fabricated/synthetic value, per CLAUDE.md's "no fabricated
+metrics" invariant applied to observability data too.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+import structlog
+from prometheus_client import CONTENT_TYPE_LATEST, CollectorRegistry, Counter, Gauge, Histogram, generate_latest
+
+REGISTRY = CollectorRegistry()
+
+search_requests_total = Counter(
+    "search_requests_total", "Total search requests served, by search_type", ["search_type"], registry=REGISTRY
+)
+search_latency_seconds = Histogram(
+    "search_latency_seconds", "Search request latency in seconds", registry=REGISTRY
+)
+search_zero_result_total = Counter(
+    "search_zero_result_total", "Total search requests that returned zero results", registry=REGISTRY
+)
+indexing_jobs_total = Counter(
+    "indexing_jobs_total", "Total indexing jobs, by terminal/transition status", ["status"], registry=REGISTRY
+)
+indexing_duration_seconds = Histogram(
+    "indexing_duration_seconds", "Wall-clock duration of one index_directory() run, in seconds", registry=REGISTRY
+)
+files_indexed_total = Counter(
+    "files_indexed_total", "Total files processed across all indexing runs", registry=REGISTRY
+)
+symbols_indexed_total = Counter(
+    "symbols_indexed_total", "Total symbols processed across all indexing runs", registry=REGISTRY
+)
+embedding_duration_seconds = Histogram(
+    "embedding_duration_seconds", "Duration of one CodeEmbedder.encode() call, in seconds", registry=REGISTRY
+)
+job_queue_depth = Gauge(
+    "job_queue_depth", "Current number of queued+running IndexJob rows", registry=REGISTRY
+)
+api_errors_total = Counter(
+    "api_errors_total", "Total error responses, by endpoint path and status code", ["endpoint", "status_code"], registry=REGISTRY
+)
+
+
+def render_metrics() -> tuple[bytes, str]:
+    """Returns `(body, content_type)` for the `/metrics` endpoint -- the real, current state of `REGISTRY`, generated fresh on every call (never cached/stale)."""
+    return generate_latest(REGISTRY), CONTENT_TYPE_LATEST
+
+
+_logging_configured = False
+
+
+def configure_logging() -> None:
+    """
+    Configures `structlog` for JSON-rendered structured log output, per
+    §18: "structured (JSON via structlog)... every log line carries
+    enough to reconstruct a request's full path." Idempotent -- safe to
+    call more than once (e.g. once per test module importing
+    `codepulse.api.app`), only actually reconfigures the first time.
+    """
+    global _logging_configured
+    if _logging_configured:
+        return
+    structlog.configure(
+        processors=[
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.JSONRenderer(),
+        ],
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stdout),
+        wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
+        cache_logger_on_first_use=True,
+    )
+    _logging_configured = True
+
+
+def get_logger() -> Any:
+    """
+    Returns a structlog bound logger. §18's own exact field set
+    (`request_id`, `repository_id`, `job_id`, `api_key_id`,
+    `operation`, `duration_ms`, `error_type`) is bound by each CALL
+    SITE via `.bind(...)`/keyword arguments -- this function does not
+    hardcode which fields a given log line carries, since not every
+    operation has all of them (e.g. a search request has no `job_id`).
+    """
+    configure_logging()
+    return structlog.get_logger()

codepulse/parser/__init__.py

@@ -0,0 +1,8 @@
+"""
+CodePulse AST parsing subsystem.
+"""
+
+from codepulse.parser.base import LanguageParser
+from codepulse.parser.factory import get_parser_for_file, get_parser_for_language
+
+__all__ = ["LanguageParser", "get_parser_for_file", "get_parser_for_language"]

codepulse/parser/base.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from codepulse.models import (
+    FileParseResult,
+    ImportStatement,
+    Symbol,
+    CallReference,
+    compute_content_hash,
+)
+
+
+class LanguageParser(ABC):
+    """Abstract Base Class for language-specific AST parsers."""
+
+    @property
+    @abstractmethod
+    def language(self) -> str:
+        """Returns the canonical language identifier (e.g. 'python', 'javascript')."""
+        pass
+
+    @abstractmethod
+    def extract_symbols(self, source_code: str, file_path: str = "") -> list[Symbol]:
+        """Extract functions, classes, methods, and types with their signatures and docstrings."""
+        pass
+
+    @abstractmethod
+    def extract_imports(self, source_code: str, file_path: str = "") -> list[ImportStatement]:
+        """Extract module imports and imported identifiers."""
+        pass
+
+    @abstractmethod
+    def extract_calls(
+        self, source_code: str, file_path: str = "", symbols: list[Symbol] | None = None
+    ) -> list[CallReference]:
+        """Extract function/method invocations mapped to their enclosing caller symbols."""
+        pass
+
+    def parse_file(self, file_path: str, source_code: str) -> FileParseResult:
+        """Parse source code completely and return aggregated FileParseResult."""
+        symbols = self.extract_symbols(source_code, file_path=file_path)
+        imports = self.extract_imports(source_code, file_path=file_path)
+        calls = self.extract_calls(source_code, file_path=file_path, symbols=symbols)
+        
+        line_count = len(source_code.splitlines())
+        file_size_bytes = len(source_code.encode("utf-8"))
+        content_hash = compute_content_hash(source_code)
+
+        return FileParseResult(
+            file_path=file_path,
+            language=self.language,
+            symbols=symbols,
+            imports=imports,
+            calls=calls,
+            file_size_bytes=file_size_bytes,
+            line_count=line_count,
+            content_hash=content_hash,
+        )

codepulse/parser/factory.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+from codepulse.parser.base import LanguageParser
+from codepulse.parser.python import PythonParser
+from codepulse.parser.javascript import JavaScriptParser
+
+_PARSERS: dict[str, LanguageParser] = {}
+
+
+def get_parser_for_language(language: str) -> LanguageParser:
+    """Retrieve a cached parser instance for the requested language."""
+    lang_lower = language.lower().strip()
+    if lang_lower not in _PARSERS:
+        if lang_lower in ("python", "py"):
+            _PARSERS[lang_lower] = PythonParser()
+        elif lang_lower in ("javascript", "js"):
+            _PARSERS[lang_lower] = JavaScriptParser(is_typescript=False)
+        elif lang_lower in ("typescript", "ts"):
+            _PARSERS[lang_lower] = JavaScriptParser(is_typescript=True)
+        else:
+            raise ValueError(f"Unsupported language: '{language}'")
+    return _PARSERS[lang_lower]
+
+
+def get_parser_for_file(file_path: str) -> LanguageParser | None:
+    """Determine the appropriate parser based on file extension."""
+    _, ext = os.path.splitext(file_path)
+    ext_lower = ext.lower()
+
+    if ext_lower == ".py":
+        return get_parser_for_language("python")
+    elif ext_lower in (".js", ".jsx", ".mjs", ".cjs"):
+        return get_parser_for_language("javascript")
+    elif ext_lower in (".ts", ".tsx", ".mts", ".cts"):
+        return get_parser_for_language("typescript")
+    return None