codeboarding 0.12.3__tar.gz → 0.12.5__tar.gz

{codeboarding-0.12.3/codeboarding.egg-info → codeboarding-0.12.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.12.3
+Version: 0.12.5
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT

{codeboarding-0.12.3 → codeboarding-0.12.5}/agents/agent_responses.py

@@ -3,12 +3,16 @@ from __future__ import annotations
 import abc
 import logging
 from abc import abstractmethod
+from enum import StrEnum
 from pathlib import PurePosixPath
 from typing import get_origin, Optional
 
 from pydantic import BaseModel, Field
 from pydantic.fields import FieldInfo
 
+from agents.cluster_ids import CodeBoardingClusterId, GraphClusterId
+from agents.scope_ids import ROOT_SCOPE_ID
+
 logger = logging.getLogger(__name__)
 
 
@@ -183,7 +187,7 @@ class ClustersComponent(LLMBaseModel):
     name: str = Field(
         description="Short, descriptive name for this cluster group (e.g., 'Authentication', 'Data Pipeline', 'Request Handling')"
     )
-    cluster_ids: list[int] = Field(
+    cluster_ids: list[GraphClusterId] = Field(
         description="List of cluster IDs from the CFG analysis that are grouped together (e.g., [1, 3, 5])"
     )
     description: str = Field(
@@ -305,7 +309,7 @@ class Component(LLMBaseModel):
         default_factory=list,
     )
 
-    source_cluster_ids: list[int] = Field(
+    source_cluster_ids: list[CodeBoardingClusterId] = Field(
         description="List of cluster IDs from CFG analysis that this component encompasses (populated deterministically from source_group_names).",
         default_factory=list,
         exclude=True,
@@ -570,6 +574,59 @@ class ScopeRelations(LLMBaseModel):
         return "\n".join(r.llm_str() for r in self.components_relations)
 
 
+class ScopeOperationAction(StrEnum):
+    CREATE_COMPONENT = "create_component"
+    UPDATE_COMPONENT = "update_component"
+    DELETE_COMPONENT = "delete_component"
+    NOOP = "noop"
+    REGENERATE_SCOPE = "regenerate_scope"
+
+
+class ScopedClusterRef(LLMBaseModel):
+    """A cluster reference scoped by component depth and language."""
+
+    scope_id: str = Field(description="Component scope id; use 'root' for the top-level scope.")
+    language: str = Field(description="Programming language for this cluster.")
+    cluster_id: int = Field(description="Cluster id within the scope/language cluster result.")
+
+    def llm_str(self):
+        scope_id = self.scope_id or ROOT_SCOPE_ID
+        return f"{scope_id}:{self.language}:{self.cluster_id}"
+
+
+class ScopeOperation(LLMBaseModel):
+    """One diagram update operation for a single scope."""
+
+    action: ScopeOperationAction = Field(description="Operation to apply in this scope.")
+    cluster_refs: list[ScopedClusterRef] = Field(description="New-side clusters this operation accounts for.")
+    component_id: str | None = Field(
+        default=None,
+        description="Existing component id for update/delete/noop; null when creating a component.",
+    )
+    name: str | None = Field(default=None, description="Component name for create/update operations.")
+    description: str | None = Field(default=None, description="Component description for create/update operations.")
+    recurse: bool = Field(
+        default=False, description="Whether this component should be considered for child-scope update."
+    )
+    rationale: str = Field(description="Short reason for the operation, especially for ambiguous reshapes.")
+
+    def llm_str(self):
+        refs = ", ".join(ref.llm_str() for ref in self.cluster_refs) or "no clusters"
+        target = self.component_id or self.name or "new component"
+        return f"{self.action}: {refs} -> {target}; recurse={self.recurse}; {self.rationale}"
+
+
+class ScopeUpdateDecision(LLMBaseModel):
+    """LLM-selected operations for one incremental scope update."""
+
+    operations: list[ScopeOperation] = Field(description="Operations to apply to the current scope.")
+
+    def llm_str(self):
+        if not self.operations:
+            return "No scope operations."
+        return "\n".join(operation.llm_str() for operation in self.operations)
+
+
 class FilePath(LLMBaseModel):
     """File path with optional line range reference."""
 

codeboarding-0.12.5/agents/cluster_ids.py

@@ -0,0 +1,42 @@
+type GraphClusterId = int
+type CodeBoardingClusterId = str
+
+
+class GraphClusterIds:
+    @classmethod
+    def sort(cls, cluster_ids: set[GraphClusterId]) -> list[GraphClusterId]:
+        return sorted(cluster_ids)
+
+
+class CodeBoardingClusterIds:
+    @classmethod
+    def sort(cls, cluster_ids: set[CodeBoardingClusterId]) -> list[CodeBoardingClusterId]:
+        # Sort by depth first, then naturally within a level: ["1", "2", "10", "2.1", "3.4"].
+        return sorted(cluster_ids, key=_cluster_id_sort_key)
+
+    @classmethod
+    def from_graph_id(cls, cluster_id: GraphClusterId) -> CodeBoardingClusterId:
+        return str(cluster_id)
+
+    @classmethod
+    def from_graph_ids(cls, cluster_ids: set[GraphClusterId]) -> list[CodeBoardingClusterId]:
+        return [cls.from_graph_id(cluster_id) for cluster_id in GraphClusterIds.sort(cluster_ids)]
+
+    @classmethod
+    def qualify_local_id(
+        cls, local_cluster_id: CodeBoardingClusterId, source_cluster_id_prefix: str = ""
+    ) -> CodeBoardingClusterId:
+        if not source_cluster_id_prefix:
+            return local_cluster_id
+        return f"{source_cluster_id_prefix}.{local_cluster_id}"
+
+    @classmethod
+    def qualify_local_ids(
+        cls, local_cluster_ids: list[CodeBoardingClusterId], source_cluster_id_prefix: str = ""
+    ) -> list[CodeBoardingClusterId]:
+        return [cls.qualify_local_id(cluster_id, source_cluster_id_prefix) for cluster_id in local_cluster_ids]
+
+
+def _cluster_id_sort_key(cluster_id: CodeBoardingClusterId) -> tuple[tuple[int, int | str], ...]:
+    parts = tuple((0, int(part)) if part.isdigit() else (1, part) for part in cluster_id.split("."))
+    return ((0, len(parts)), *parts)

{codeboarding-0.12.3 → codeboarding-0.12.5}/agents/cluster_methods_mixin.py

@@ -16,9 +16,12 @@ from agents.agent_responses import (
     MethodEntry,
 )
 from agents.cluster_budget import ClusterPromptBudget
+from agents.cluster_ids import CodeBoardingClusterId, CodeBoardingClusterIds, GraphClusterId
 from agents.llm_config import get_current_agent_context_window, get_current_agent_model_ref
 from agents.model_capabilities import ContextWindow
 from constants import MIN_CLUSTERS_THRESHOLD
+from diagram_analysis.cluster_delta import _delta_for_language
+from diagram_analysis.cluster_snapshot import ClusterSnapshotEntry
 from static_analyzer.analysis_result import StaticAnalysisResults
 from static_analyzer.cfg_skip_planner import ContextBudgetExceededError, plan_skip_set
 from static_analyzer.cluster_helpers import (
@@ -44,7 +47,31 @@ logger = logging.getLogger(__name__)
 class _RenderedClusterString:
     text: str
     by_language: dict[str, str]
-    cluster_ids: set[int]
+    cluster_ids: set[GraphClusterId]
+
+
+def scoped_snapshot_from_lineage(cfg: CallGraph, scope_id: str) -> dict[int, ClusterSnapshotEntry]:
+    """Build a scoped snapshot from each method's recorded cluster ancestry/path."""
+    if not scope_id:
+        return {}
+    prefix = f"{scope_id}."
+    entries: dict[int, ClusterSnapshotEntry] = {}
+    for qname, cluster_ids in cfg.method_cluster_paths_snapshot():
+        if qname not in cfg.nodes:
+            continue
+        for cluster_id in cluster_ids:
+            if not cluster_id.startswith(prefix):
+                continue
+            local_id = cluster_id.removeprefix(prefix)
+            if not local_id.isdigit():
+                continue
+            entry = entries.setdefault(int(local_id), ClusterSnapshotEntry())
+            entry.members.add(qname)
+            file_path = cfg.nodes[qname].file_path
+            if file_path:
+                entry.files.add(file_path)
+                entry.member_files[qname] = file_path
+    return entries
 
 
 def _describe_window(ctx: ContextWindow) -> str:
@@ -327,7 +354,7 @@ class ClusterMethodsMixin:
 
     def _resolve_cluster_ids_from_groups(self, analysis: AnalysisInsights, cluster_analysis: ClusterAnalysis) -> None:
         """Resolve source_cluster_ids deterministically from source_group_names via case-insensitive lookup."""
-        group_name_to_ids: dict[str, list[int]] = {
+        group_name_to_ids: dict[str, list[GraphClusterId]] = {
             cc.name.lower(): cc.cluster_ids for cc in cluster_analysis.cluster_components
         }
 
@@ -340,7 +367,7 @@ class ClusterMethodsMixin:
                 logger.warning(
                     f"[{self.__class__.__name__}] Unresolved group name '{gname}' for component '{component.name}'"
                 )
-            component.source_cluster_ids = sorted(set(resolved_ids))
+            component.source_cluster_ids = CodeBoardingClusterIds.from_graph_ids(set(resolved_ids))
 
     def _expand_to_method_level_clusters(self, cfg: CallGraph, cluster_result: ClusterResult) -> ClusterResult:
         """
@@ -399,7 +426,9 @@ class ClusterMethodsMixin:
         )
 
     def _create_strict_component_subgraph(
-        self, component: Component
+        self,
+        component: Component,
+        source_cluster_id_prefix: str = "",
     ) -> tuple[str, dict[str, ClusterResult], dict[str, CallGraph]]:
         """
         Create a strict subgraph containing ONLY nodes from the component's file_methods.
@@ -440,8 +469,17 @@ class ClusterMethodsMixin:
             if sub_cfg.nodes:
                 subgraph_cfgs[lang] = sub_cfg
 
-                # Calculate clusters for the subgraph
-                sub_cluster_result = sub_cfg.cluster()
+                seeded_snapshot = scoped_snapshot_from_lineage(sub_cfg, source_cluster_id_prefix)
+                if seeded_snapshot:
+                    scoped_delta = _delta_for_language(
+                        str(lang),
+                        sub_cfg.to_networkx(),
+                        seeded_snapshot,
+                    )
+                    sub_cluster_result = scoped_delta.cluster_results
+                else:
+                    # Calculate clusters for the subgraph
+                    sub_cluster_result = sub_cfg.cluster()
 
                 # Merge into super-clusters if too many (same limit as AbstractionAgent)
                 if len(sub_cluster_result.clusters) > MAX_LLM_CLUSTERS:
@@ -461,6 +499,12 @@ class ClusterMethodsMixin:
             cfg_nx = {lang: subgraph_cfgs[lang].to_networkx() for lang in cluster_results}
             enforce_cross_language_budget(cluster_results, cfg_nx)
 
+        if source_cluster_id_prefix:
+            for lang, cluster_result in cluster_results.items():
+                self.static_analysis.get_cfg(Language(lang)).record_cluster_paths(
+                    cluster_result, source_cluster_id_prefix
+                )
+
         result_parts = []
         for lang in self.static_analysis.get_languages():
             if lang not in cluster_results:
@@ -609,26 +653,33 @@ class ClusterMethodsMixin:
             groups.append(FileMethodGroup(file_path=file_path, methods=methods))
         return groups
 
-    def _build_cluster_to_component_map(self, analysis: AnalysisInsights) -> dict[int, Component]:
+    def _build_cluster_to_component_map(self, analysis: AnalysisInsights) -> dict[CodeBoardingClusterId, Component]:
         """Build cluster_id -> Component mapping from source_cluster_ids."""
-        cluster_to_component: dict[int, Component] = {}
+        cluster_to_component: dict[CodeBoardingClusterId, Component] = {}
         for comp in analysis.components:
             for cid in comp.source_cluster_ids:
                 cluster_to_component[cid] = comp
         return cluster_to_component
 
-    def _build_node_to_cluster_map(self, cluster_results: dict[str, ClusterResult]) -> tuple[dict[str, int], set[int]]:
+    def _build_node_to_cluster_map(
+        self, cluster_results: dict[str, ClusterResult], source_cluster_id_prefix: str = ""
+    ) -> tuple[dict[str, CodeBoardingClusterId], set[CodeBoardingClusterId]]:
         """Build node_name (qualified name) -> cluster_id mapping and collect all cluster IDs."""
-        all_cluster_ids: set[int] = set()
-        node_to_cluster: dict[str, int] = {}
+        all_cluster_ids: set[CodeBoardingClusterId] = set()
+        node_to_cluster: dict[str, CodeBoardingClusterId] = {}
         for cr in cluster_results.values():
             for cid, members in cr.clusters.items():
-                all_cluster_ids.add(cid)
+                cluster_id = CodeBoardingClusterIds.qualify_local_id(
+                    CodeBoardingClusterIds.from_graph_id(cid), source_cluster_id_prefix
+                )
+                all_cluster_ids.add(cluster_id)
                 for name in members:
-                    node_to_cluster[name] = cid
+                    node_to_cluster[name] = cluster_id
         return node_to_cluster, all_cluster_ids
 
-    def _validate_cluster_coverage(self, cluster_to_component: dict[int, Component], all_cluster_ids: set[int]) -> None:
+    def _validate_cluster_coverage(
+        self, cluster_to_component: dict[CodeBoardingClusterId, Component], all_cluster_ids: set[CodeBoardingClusterId]
+    ) -> None:
         """Log an error if any cluster IDs are not mapped to a component."""
         unmapped_cluster_ids = sorted(all_cluster_ids - set(cluster_to_component.keys()))
         if unmapped_cluster_ids:
@@ -642,7 +693,8 @@ class ClusterMethodsMixin:
         self,
         node: Node,
         cluster_results: dict[str, ClusterResult],
-        cluster_to_component: dict[int, Component],
+        cluster_to_component: dict[str, Component],
+        source_cluster_id_prefix: str = "",
     ) -> Component | None:
         """Try to assign a node to a component based on its file already belonging to a cluster."""
         file_path = node.file_path
@@ -651,7 +703,10 @@ class ClusterMethodsMixin:
         for cr in cluster_results.values():
             cluster_ids = cr.get_clusters_for_file(file_path)
             for cid in cluster_ids:
-                comp = cluster_to_component.get(cid)
+                cluster_id = CodeBoardingClusterIds.qualify_local_id(
+                    CodeBoardingClusterIds.from_graph_id(cid), source_cluster_id_prefix
+                )
+                comp = cluster_to_component.get(cluster_id)
                 if comp is not None:
                     return comp
         return None
@@ -659,11 +714,12 @@ class ClusterMethodsMixin:
     def _assign_nodes_to_components(
         self,
         all_nodes: dict[str, Node],
-        node_to_cluster: dict[str, int],
-        cluster_to_component: dict[int, Component],
+        node_to_cluster: dict[str, str],
+        cluster_to_component: dict[str, Component],
         cluster_results: dict[str, ClusterResult],
         fallback_component: Component,
         cfg_graphs: dict[str, CallGraph] | None = None,
+        source_cluster_id_prefix: str = "",
     ) -> dict[str, list[Node]]:
         """Assign every node to a component via its cluster, file co-location, graph distance, or fallback."""
         component_nodes: dict[str, list[Node]] = defaultdict(list)
@@ -691,7 +747,7 @@ class ClusterMethodsMixin:
             node = all_nodes[qname]
 
             # 1. Try file co-location: if the node's file already belongs to a cluster/component
-            comp = self._find_component_by_file(node, cluster_results, cluster_to_component)
+            comp = self._find_component_by_file(node, cluster_results, cluster_to_component, source_cluster_id_prefix)
             if comp is not None:
                 assigned_by_file += 1
                 component_nodes[comp.component_id].append(node)
@@ -699,8 +755,15 @@ class ClusterMethodsMixin:
 
             # 2. Try graph distance: find the nearest cluster in the call graph
             nearest_cid = self._find_nearest_cluster(qname, cluster_results, undirected_graphs)
-            if nearest_cid is not None and nearest_cid in cluster_to_component:
-                comp = cluster_to_component[nearest_cid]
+            nearest_cluster_id = (
+                CodeBoardingClusterIds.qualify_local_id(
+                    CodeBoardingClusterIds.from_graph_id(nearest_cid), source_cluster_id_prefix
+                )
+                if nearest_cid is not None
+                else ""
+            )
+            if nearest_cluster_id in cluster_to_component:
+                comp = cluster_to_component[nearest_cluster_id]
                 assigned_by_graph += 1
                 component_nodes[comp.component_id].append(node)
                 continue
@@ -716,7 +779,7 @@ class ClusterMethodsMixin:
                 f"{assigned_by_graph} by graph distance, {assigned_by_fallback} to fallback"
             )
         if assigned_by_fallback:
-            logger.warning(
+            logger.error(
                 f"{assigned_by_fallback} node(s) fell back to '{fallback_component.name}' "
                 f"— files: {sorted(fallback_files)}"
             )
@@ -754,6 +817,7 @@ class ClusterMethodsMixin:
         analysis: AnalysisInsights,
         cluster_results: dict[str, ClusterResult],
         cfg_graphs: dict[str, CallGraph] | None = None,
+        source_cluster_id_prefix: str = "",
     ) -> None:
         """Deterministically populate ``file_methods`` on every component.
 
@@ -777,11 +841,17 @@ class ClusterMethodsMixin:
         # per-component subgraph in DetailsAgent, which runs in parallel).
         all_nodes = self._collect_all_cfg_nodes(cluster_results, cfg_graphs)
         cluster_to_component = self._build_cluster_to_component_map(analysis)
-        node_to_cluster, all_cluster_ids = self._build_node_to_cluster_map(cluster_results)
+        node_to_cluster, all_cluster_ids = self._build_node_to_cluster_map(cluster_results, source_cluster_id_prefix)
         self._validate_cluster_coverage(cluster_to_component, all_cluster_ids)
 
         component_nodes = self._assign_nodes_to_components(
-            all_nodes, node_to_cluster, cluster_to_component, cluster_results, analysis.components[0], cfg_graphs
+            all_nodes,
+            node_to_cluster,
+            cluster_to_component,
+            cluster_results,
+            analysis.components[0],
+            cfg_graphs,
+            source_cluster_id_prefix,
         )
 
         for comp in analysis.components:
@@ -795,6 +865,7 @@ class ClusterMethodsMixin:
         self,
         analysis: AnalysisInsights,
         cfg_graphs: dict[str, CallGraph] | None = None,
+        source_cluster_id_prefix: str = "",
     ) -> None:
         """Build inter-component relations from CFG edges and merge with LLM relations.
 
@@ -810,6 +881,14 @@ class ClusterMethodsMixin:
         node_to_component = build_node_to_component_map(analysis)
         static_relations = build_component_relations(node_to_component, cfg_graphs)
         analysis.components_relations = merge_relations(analysis.components_relations, static_relations, analysis)
+        self._prefix_local_cluster_ids(analysis, source_cluster_id_prefix)
+
+    def _prefix_local_cluster_ids(self, analysis: AnalysisInsights, prefix: str) -> None:
+        """Prefix detail-subgraph cluster ids with their owning component scope."""
+        for component in analysis.components:
+            component.source_cluster_ids = CodeBoardingClusterIds.qualify_local_ids(
+                component.source_cluster_ids, prefix
+            )
 
     def build_scope_cfg_string(self, analysis: AnalysisInsights) -> str:
         """Render cross-component communication edges as a human-readable string for the LLM.

{codeboarding-0.12.3 → codeboarding-0.12.5}/agents/details_agent.py

@@ -217,7 +217,9 @@ class DetailsAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
         # Step 1: Create subgraph from component's assigned files using strict filtering
         # If subgraph has < MIN_CLUSTERS_THRESHOLD clusters, auto-expands to method-level
-        _subgraph_str, subgraph_cluster_results, subgraph_cfgs = self._create_strict_component_subgraph(component)
+        _subgraph_str, subgraph_cluster_results, subgraph_cfgs = self._create_strict_component_subgraph(
+            component, source_cluster_id_prefix=component.component_id
+        )
 
         # Step 2: Group clusters within the subgraph
         cluster_analysis = self.step_clusters_grouping(component, subgraph_cluster_results)
@@ -238,7 +240,7 @@ class DetailsAgent(ClusterMethodsMixin, CodeBoardingAgent):
         self.populate_file_methods(analysis, subgraph_cluster_results, subgraph_cfgs)
 
         # Step 7: Build static inter-component relations from subgraph CFG edges
-        self.build_static_relations(analysis, subgraph_cfgs)
+        self.build_static_relations(analysis, subgraph_cfgs, source_cluster_id_prefix=component.component_id)
 
         # Step 8: Fix source code reference lines (resolves reference_file paths)
         analysis = self.fix_source_code_reference_lines(analysis)