devcouncil 0.3.0 → 0.4.0

package/src/devcouncil/indexing/graph/schema.py

@@ -0,0 +1,103 @@
+"""Pydantic schema for the symbol-level code knowledge graph.
+
+devcouncil: allow-unwired — package-private types; imported by sibling graph modules.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List
+
+from pydantic import BaseModel, Field
+
+
+SCHEMA_VERSION = 2
+
+
+class NodeKind(str, Enum):
+    FILE = "file"
+    MODULE = "module"
+    NAMESPACE = "namespace"
+    PACKAGE = "package"
+    FUNCTION = "function"
+    CLASS = "class"
+    METHOD = "method"
+    INTERFACE = "interface"
+    TYPE = "type"
+    STRUCT = "struct"
+    ENUM = "enum"
+    TRAIT = "trait"
+    PROPERTY = "property"
+    VARIABLE = "variable"
+    ROUTE = "route"
+    EVENT = "event"
+    STATE = "state"
+    PROVIDER = "provider"
+    COMPONENT = "component"
+    DYNAMIC = "dynamic"
+    RATIONALE = "rationale"
+
+
+class Confidence(str, Enum):
+    EXTRACTED = "extracted"
+    INFERRED = "inferred"
+    AMBIGUOUS = "ambiguous"
+
+
+class GraphNode(BaseModel):
+    id: str
+    kind: NodeKind
+    path: str = ""
+    name: str = ""
+    line: int = 0
+    end_line: int = 0
+    area: str = ""
+    language: str = ""
+    exported: bool = False
+    community: str = ""
+    extras: Dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphEdge(BaseModel):
+    source: str
+    target: str
+    kind: str  # contains | imports | calls | inherits | implements | overrides | decorates | documents
+    confidence: Confidence = Confidence.EXTRACTED
+    reason: str = ""
+    extras: Dict[str, Any] = Field(default_factory=dict)
+
+
+class DeadCodeEntry(BaseModel):
+    id: str
+    path: str
+    line: int = 0
+    kind: str = ""
+    confidence: Confidence = Confidence.INFERRED
+    reason: str = ""
+
+
+class CodeGraph(BaseModel):
+    schema_version: int = SCHEMA_VERSION
+    nodes: List[GraphNode] = Field(default_factory=list)
+    edges: List[GraphEdge] = Field(default_factory=list)
+    dead_code: List[DeadCodeEntry] = Field(default_factory=list)
+    entry_roots: List[str] = Field(default_factory=list)
+    unwired_candidates: List[str] = Field(default_factory=list)
+    unreachable_files: List[str] = Field(default_factory=list)
+    generated_head: str = ""
+    indexed_hash: str = ""
+    content_fingerprint: str = ""
+    meta: Dict[str, Any] = Field(default_factory=dict)
+
+    def node_by_id(self) -> Dict[str, GraphNode]:
+        return {n.id: n for n in self.nodes}
+
+
+def file_node_id(path: str) -> str:
+    return path.replace("\\", "/")
+
+
+def symbol_node_id(path: str, qualname: str) -> str:
+    """Deterministic id: ``src/x.py::Class.method``."""
+    norm = path.replace("\\", "/")
+    return f"{norm}::{qualname}"

package/src/devcouncil/indexing/graph_index.py

@@ -1,48 +1,39 @@
-from typing import List, Dict, Any, Set
+"""Legacy artifact knowledge graph — deprecated compat shim.
+
+devcouncil: allow-unwired — deprecated compat shim; real graph is indexing/graph/.
+
+This module holds a minimal Pydantic model for requirements/tasks/files used by
+older integration experiments. It is **not** the symbol-level code graph in
+``indexing/graph/`` (built by ``dev map``).
+
+Do not extend this module for dead-code analysis, call-graph queries, or new
+features — use ``indexing/graph/`` instead. Kept only so imports remain stable.
+"""
+
+from typing import Any, Dict, List
+
 from pydantic import BaseModel, Field
 from pathlib import Path
 
+
 class GraphNode(BaseModel):
     id: str
-    type: str # "file", "symbol", "requirement", "task"
+    type: str  # "file", "symbol", "requirement", "task"
     metadata: Dict[str, Any] = Field(default_factory=dict)
 
+
 class GraphEdge(BaseModel):
     source: str
     target: str
-    relation: str # "imports", "implements", "validates", "contains"
+    relation: str  # "imports", "implements", "validates", "contains"
+
 
 class KnowledgeGraph(BaseModel):
     nodes: List[GraphNode] = []
     edges: List[GraphEdge] = []
 
+
 class GraphIndex:
     def __init__(self, project_root: Path):
         self.project_root = project_root
         self.graph = KnowledgeGraph()
-
-    def build_initial_graph(self, files: List[str]):
-        """
-        Bootstrap the graph from file list.
-        """
-        for f in files:
-            self.graph.nodes.append(GraphNode(
-                id=f,
-                type="file",
-                metadata={"extension": Path(f).suffix}
-            ))
-
-    def add_relation(self, source: str, target: str, relation: str):
-        self.graph.edges.append(GraphEdge(source=source, target=target, relation=relation))
-
-    def get_context_for_file(self, file_path: str) -> Set[str]:
-        """
-        Retrieve related paths for a given file.
-        """
-        related = {file_path}
-        for edge in self.graph.edges:
-            if edge.source == file_path:
-                related.add(edge.target)
-            if edge.target == file_path:
-                related.add(edge.source)
-        return related

package/src/devcouncil/indexing/lsp.py

@@ -16,15 +16,17 @@ class LspServerCandidate:
 
 
 class LspInspector:
-    """Language-server *detection* only — DevCouncil does not run an LSP client.
-
-    This inspector exists to answer one honest question: which language servers
-    for the repo's languages are installed on PATH? It does NOT spawn a server,
-    does NOT speak the LSP wire protocol, and does NOT send the ``initialize``
-    handshake. ``starter_initialize_payload`` builds the JSON-RPC ``initialize``
-    request a *future* client would send, but it is never transmitted — it is
-    surfaced purely as a reference/starter payload, clearly labelled as such, so
-    no consumer mistakes detection for a live LSP capability.
+    """Language-server detection, with optional live client mode.
+
+    By default this inspector only answers: which language servers for the repo's
+    languages are installed on PATH? It does NOT spawn a server or speak the wire
+    protocol. When ``client_enabled=True`` (config ``indexing.lsp_refs`` / ``dev map
+    --lsp-refs``), summaries report ``mode: "client"`` — the optional
+    :mod:`devcouncil.indexing.lsp_client` can then run ``initialize``,
+    ``textDocument/references``, and ``textDocument/definition``.
+
+    ``starter_initialize_payload`` remains a never-sent reference payload for
+    detection-only mode.
     """
 
     _LANGUAGE_SERVERS: dict[str, list[list[str]]] = {
@@ -86,12 +88,11 @@ class LspInspector:
         return candidates
 
     def starter_initialize_payload(self, language: str) -> dict[str, Any]:
-        """Build the JSON-RPC ``initialize`` request a future LSP client *would* send.
+        """Build the JSON-RPC ``initialize`` request a client would send.
 
-        This payload is NEVER sent — DevCouncil has no LSP client. It is provided
-        only as a reference/starter for anyone wiring up real LSP support. See the
-        ``initialize_requests`` block in :meth:`summary`, which carries the same
-        non-sent payloads under an explicit ``"_note"`` disclaimer.
+        In detection-only mode this payload is NEVER sent — it is a reference for
+        wiring. When ``mode: "client"``, :mod:`devcouncil.indexing.lsp_client`
+        sends an equivalent initialize over stdio.
         """
         return {
             "jsonrpc": "2.0",
@@ -113,23 +114,40 @@ class LspInspector:
             },
         }
 
-    # Made explicit in every summary so no consumer reads this as a live LSP feature.
     _DETECTION_ONLY_NOTE = (
         "Detection only: DevCouncil checks which language servers are installed on "
-        "PATH; it does not run an LSP client or send any requests."
+        "PATH; it does not run an LSP client or send any requests. Enable live "
+        "references via indexing.lsp_refs or `dev map --lsp-refs`."
+    )
+    _CLIENT_MODE_NOTE = (
+        "Client mode: DevCouncil may spawn detected language servers for "
+        "textDocument/references and textDocument/definition (dead-symbol "
+        "confirmation and precise MCP impact). Still opt-in per run/config."
     )
     _STARTER_PAYLOAD_NOTE = (
-        "Starter payloads only — these initialize requests are NEVER sent. They are "
-        "a reference for wiring up a real LSP client later."
+        "Starter payloads only — these initialize requests are NEVER sent in "
+        "detection-only mode. In client mode, lsp_client sends initialize live."
+    )
+    _CLIENT_PAYLOAD_NOTE = (
+        "Reference initialize shapes; the live client sends equivalent requests "
+        "when indexing.lsp_refs / --lsp-refs is enabled."
     )
 
-    def summary(self, files: list[str] | None = None) -> dict[str, Any]:
+    def summary(
+        self,
+        files: list[str] | None = None,
+        *,
+        client_enabled: bool = False,
+    ) -> dict[str, Any]:
         candidates = self.server_candidates(files)
+        mode = "client" if client_enabled else "detection-only"
+        note = self._CLIENT_MODE_NOTE if client_enabled else self._DETECTION_ONLY_NOTE
+        init_note = self._CLIENT_PAYLOAD_NOTE if client_enabled else self._STARTER_PAYLOAD_NOTE
         return {
-            "mode": "detection-only",
-            "note": self._DETECTION_ONLY_NOTE,
+            "mode": mode,
+            "note": note,
             "languages": self.detect_languages(files),
-            "detected_servers": [
+            "servers_detected": [
                 {
                     "language": candidate.language,
                     "command": candidate.command,
@@ -139,6 +157,15 @@ class LspInspector:
                 for candidate in candidates
             ],
             # Back-compat alias for "detected_servers" (older consumers/tests).
+            "detected_servers": [
+                {
+                    "language": candidate.language,
+                    "command": candidate.command,
+                    "available": candidate.available,
+                    "reason": candidate.reason,
+                }
+                for candidate in candidates
+            ],
             "servers": [
                 {
                     "language": candidate.language,
@@ -149,7 +176,7 @@ class LspInspector:
                 for candidate in candidates
             ],
             "initialize_requests": {
-                "_note": self._STARTER_PAYLOAD_NOTE,
+                "_note": init_note,
                 **{
                     language: self.starter_initialize_payload(language)
                     for language in sorted({candidate.language for candidate in candidates})
@@ -157,5 +184,10 @@ class LspInspector:
             },
         }
 
-    def summary_json(self, files: list[str] | None = None) -> str:
-        return json.dumps(self.summary(files), indent=2)
+    def summary_json(
+        self,
+        files: list[str] | None = None,
+        *,
+        client_enabled: bool = False,
+    ) -> str:
+        return json.dumps(self.summary(files, client_enabled=client_enabled), indent=2)