codeboarding 0.13.2__tar.gz → 0.13.3__tar.gz

{codeboarding-0.13.2/codeboarding.egg-info → codeboarding-0.13.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.13.2
+Version: 0.13.3
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -153,7 +153,7 @@ generator = DiagramGenerator(
     temp_folder=output_dir,
     repo_name="my-project",
     output_dir=output_dir,
-    depth_level=1,
+    depth_level=3,  # safety-valve cap; a component that outgrows the leaf ceiling is flagged expandable and can be expanded on demand
 )
 [analysis_path] = generator.generate_analysis()
 
@@ -211,7 +211,7 @@ codeboarding partial --local PATH --component-id ID   # update one component
 | Option | Description |
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
-| `--depth-level INT` | Diagram depth (default: 1) |
+| `--depth-level INT` | Safety-valve depth cap (default: 3) on how deep auto-expansion goes; a component that outgrows the leaf ceiling is flagged expandable regardless, and can be expanded on demand |
 | `--force` | (full only) Force full reanalysis, skip cached static analysis |
 | `--base-ref REF` / `--target-ref REF` | (incremental only) Git refs to diff |
 | `--component-id ID` | (partial only) ID of the component to update |

{codeboarding-0.13.2 → codeboarding-0.13.3}/PYPI.md

@@ -81,7 +81,7 @@ generator = DiagramGenerator(
     temp_folder=output_dir,
     repo_name="my-project",
     output_dir=output_dir,
-    depth_level=1,
+    depth_level=3,  # safety-valve cap; a component that outgrows the leaf ceiling is flagged expandable and can be expanded on demand
 )
 [analysis_path] = generator.generate_analysis()
 
@@ -139,7 +139,7 @@ codeboarding partial --local PATH --component-id ID   # update one component
 | Option | Description |
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
-| `--depth-level INT` | Diagram depth (default: 1) |
+| `--depth-level INT` | Safety-valve depth cap (default: 3) on how deep auto-expansion goes; a component that outgrows the leaf ceiling is flagged expandable regardless, and can be expanded on demand |
 | `--force` | (full only) Force full reanalysis, skip cached static analysis |
 | `--base-ref REF` / `--target-ref REF` | (incremental only) Git refs to diff |
 | `--component-id ID` | (partial only) ID of the component to update |

{codeboarding-0.13.2 → codeboarding-0.13.3}/README.md

@@ -124,8 +124,10 @@ Shell environment variables such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOG
 # Analyze a local repository
 python main.py full --local ./my-project
 
-# Increase diagram depth
-python main.py full --local ./my-project --depth-level 2
+# Raise the depth ceiling to auto-expand deeper (rarely needed — a component that
+# outgrows the leaf ceiling is flagged expandable at whatever depth the run stops
+# and can be expanded on demand; --depth-level is a safety-valve cap, default 3)
+python main.py full --local ./my-project --depth-level 5
 
 # Re-analyze only changed parts when possible
 python main.py incremental --local ./my-project

{codeboarding-0.13.2 → codeboarding-0.13.3}/agents/abstraction_agent.py

@@ -17,7 +17,6 @@ from agents.agent_responses import (
 )
 from agents.cluster_methods_mixin import ClusterMethodsMixin
 from agents.prompts import (
-    get_cluster_grouping_message,
     get_final_analysis_message,
     get_api_surfaces_message,
     get_relation_analysis_message,
@@ -28,17 +27,15 @@ from agents.relation_edges import index_relation_endpoints
 from agents.repair import ComponentRepairContext, repair_component_group_names, repair_key_entities
 from agents.validation import (
     ValidationContext,
-    validate_cluster_coverage,
     validate_group_name_coverage,
     validate_key_entities,
     validate_relations,
 )
 from monitoring import trace
+from static_analyzer import StaticAnalysisFatalError
 from static_analyzer.analysis_result import StaticAnalysisResults
-from static_analyzer.cluster_helpers import (
-    build_all_cluster_results,
-    get_all_cluster_ids,
-)
+from static_analyzer.cluster_helpers import build_all_cluster_results
+from static_analyzer.constants import Language
 from static_analyzer.graph import ClusterResult
 
 logger = logging.getLogger(__name__)
@@ -61,10 +58,6 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
         self.meta_context = meta_context
 
         self.prompts = {
-            "group_clusters": PromptTemplate(
-                template=get_cluster_grouping_message(),
-                input_variables=["cfg_clusters"],
-            ),
             "final_analysis": PromptTemplate(
                 template=get_final_analysis_message(),
                 input_variables=["cluster_analysis"],
@@ -88,37 +81,18 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
     @trace
     def step_clusters_grouping(self, cluster_results: dict[str, ClusterResult]) -> ClusterAnalysis:
-        logger.info(f"[AbstractionAgent] Grouping CFG clusters for: {self.project_name}")
-
-        programming_langs = self.static_analysis.get_languages()
-
-        # Measure everything that wraps cfg_clusters (system message + rendered
-        # template with an empty slot) so the skip planner can back it out of
-        # the input window before budgeting the cluster string.
-        overhead_chars = len(str(self.system_message.content)) + len(
-            self.prompts["group_clusters"].format(
-                cfg_clusters="",
-            )
-        )
-        cluster_str = self._build_cluster_string(
-            programming_langs, cluster_results, prompt_overhead_chars=overhead_chars
-        )
-
-        prompt = self.prompts["group_clusters"].format(
-            cfg_clusters=cluster_str,
-        )
-
-        cluster_analysis = self._invoke_validate(
-            prompt,
-            ClusterAnalysis,
-            validators=[validate_cluster_coverage],
-            validation_context=ValidationContext(
-                cluster_results=cluster_results,
-                expected_cluster_ids=get_all_cluster_ids(cluster_results),
-            ),
-            max_validation_attempts=3,
-        )
-        return cluster_analysis
+        """Deterministically partition leaf clusters into the top-level component groups.
+
+        Resolution-tuned Leiden picks both the count (modularity peak over
+        ``[5, 8]``) and the membership, so the top-level structure is stable across
+        re-runs — the LLM no longer decides it; it only names them in the
+        final-analysis step.
+        """
+        logger.info(f"[AbstractionAgent] Super-clustering leaf clusters for: {self.project_name}")
+        cfg_graphs = {
+            lang: self.static_analysis.get_cfg(Language(lang)).clustering_networkx() for lang in cluster_results
+        }
+        return self.deterministic_cluster_grouping(cluster_results, cfg_graphs)
 
     @trace
     def step_final_analysis(
@@ -162,6 +136,7 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
             validation_context=context,
             max_validation_attempts=3,
         )
+        self.assemble_one_component_per_group(architecture, llm_cluster_analysis, cluster_results)
         return AnalysisInsights(
             description=architecture.description,
             components=architecture.components,
@@ -219,10 +194,18 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
         # Build full cluster results dict for all languages ONCE
         cluster_results = build_all_cluster_results(self.static_analysis)
 
-        # Step 1: Group related clusters together into logical components
+        # Step 1: Deterministically partition leaf clusters into the top-level groups (Leiden, modularity-peak N)
         cluster_analysis = self.step_clusters_grouping(cluster_results)
+        if not cluster_analysis.cluster_components:
+            # No leaf clusters means the repo has no callable structure to abstract
+            # (unsupported/empty/no-code). Fail loudly instead of emptying the
+            # architecture and crashing downstream in populate_file_methods.
+            raise StaticAnalysisFatalError(
+                f"No component groups found for {self.project_name}: the static analysis produced "
+                "no callable structure to build an architecture from."
+            )
 
-        # Step 2: Generate abstract components from grouped clusters
+        # Step 2: Name and describe each fixed group into a component (LLM, one component per group)
         analysis = self.step_final_analysis(cluster_analysis, cluster_results)
         # Step 3: Assign hierarchical component IDs ("1", "2", "3", ...)
         assign_component_ids(analysis)

{codeboarding-0.13.2 → codeboarding-0.13.3}/agents/agent.py

@@ -7,7 +7,7 @@ from typing import Protocol, TypeVar
 from google.api_core.exceptions import ResourceExhausted
 from langchain_core.exceptions import OutputParserException
 from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import SystemMessage, HumanMessage, AIMessage, ToolMessage
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
 from langchain_core.output_parsers import PydanticOutputParser
 from langchain_core.prompts import PromptTemplate
 from langchain.agents import create_agent

{codeboarding-0.13.2 → codeboarding-0.13.3}/agents/agent_responses.py

@@ -6,13 +6,13 @@ from abc import abstractmethod
 from collections.abc import Hashable
 from enum import StrEnum
 from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, get_origin, Optional
+from typing import TYPE_CHECKING, get_origin
 
 from pydantic import BaseModel, Field
 from pydantic.fields import FieldInfo
 
 from agents.cluster_ids import CodeBoardingClusterId, GraphClusterId
-from agents.file_index_models import FileEntry, FileMethodGroup, MethodEntry
+from agents.file_index_models import FileEntry, FileMethodGroup
 from agents.scope_ids import ROOT_SCOPE_ID
 
 logger = logging.getLogger(__name__)
@@ -644,7 +644,14 @@ def assign_component_ids(analysis: AnalysisInsights, parent_id: str = "", only_n
 
 
 def assign_relation_ids(analysis: AnalysisInsights) -> None:
-    """Assign relation component IDs by looking up component names."""
+    """Assign relation component IDs by name, dropping any relation whose endpoint
+    does not name a component in this scope.
+
+    Relation generation can emit an endpoint that is not a sibling — a name from a
+    neighbouring scope, or one the wording invented. Such a relation has no valid id and
+    would render as a dangling edge (``relations.endpoints_resolve``), so it is removed
+    rather than kept with an empty endpoint id.
+    """
     name_to_id: dict[str, str] = {}
     for c in analysis.components:
         if c.name in name_to_id:
@@ -654,9 +661,17 @@ def assign_relation_ids(analysis: AnalysisInsights) -> None:
             )
         else:
             name_to_id[c.name] = c.component_id
+    resolved: list[Relation] = []
     for relation in analysis.components_relations:
-        relation.src_id = name_to_id.get(relation.src_name, "")
-        relation.dst_id = name_to_id.get(relation.dst_name, "")
+        src_id = name_to_id.get(relation.src_name, "")
+        dst_id = name_to_id.get(relation.dst_name, "")
+        if not src_id or not dst_id:
+            logger.info(f"Dropping relation with unresolved endpoint: '{relation.src_name}' -> '{relation.dst_name}'")
+            continue
+        relation.src_id = src_id
+        relation.dst_id = dst_id
+        resolved.append(relation)
+    analysis.components_relations = resolved
 
 
 def iter_components(
@@ -805,17 +820,6 @@ class ComponentFiles(LLMBaseModel):
         return title + body
 
 
-class ScopeRelations(LLMBaseModel):
-    """Relations between components within a single scope."""
-
-    components_relations: list[Relation] = Field(description="Inter-component relationships within this scope.")
-
-    def llm_str(self):
-        if not self.components_relations:
-            return "No relations found."
-        return "\n".join(r.llm_str() for r in self.components_relations)
-
-
 class ScopeOperationAction(StrEnum):
     CREATE_COMPONENT = "create_component"
     UPDATE_COMPONENT = "update_component"