codeboarding 0.10.0__tar.gz → 0.10.2__tar.gz

{codeboarding-0.10.0/codeboarding.egg-info → codeboarding-0.10.2}/PKG-INFO

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

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/abstraction_agent.py

@@ -103,6 +103,8 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
         cluster_str = llm_cluster_analysis.llm_str() if llm_cluster_analysis else "No cluster analysis available."
 
+        group_names = [cc.name for cc in llm_cluster_analysis.cluster_components] if llm_cluster_analysis else []
+
         prompt = self.prompts["final_analysis"].format(
             project_name=self.project_name,
             cluster_analysis=cluster_str,
@@ -110,6 +112,12 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
             project_type=project_type,
         )
 
+        if group_names:
+            prompt += (
+                f"\n\n## All Group Names ({len(group_names)} total)\n"
+                f"Every one of these names must appear in exactly one component's source_group_names: {group_names}\n"
+            )
+
         # Build validation context with CFG graphs for edge checking
         context = ValidationContext(
             cluster_results=cluster_results,

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/agent_responses.py

@@ -111,7 +111,7 @@ class ClustersComponent(LLMBaseModel):
         description="List of cluster IDs from the CFG analysis that are grouped together (e.g., [1, 3, 5])"
     )
     description: str = Field(
-        description="Explanation of what this component does, its main flow, WHY these clusters are grouped together, and how it interacts with other cluster groups"
+        description="Explanation of what this component does, its main flow, WHY these clusters are grouped together, how it interacts with other cluster groups, and the most important classes/methods (by their exact qualified names from the clusters)"
     )
 
     def llm_str(self):

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/cluster_methods_mixin.py

@@ -16,8 +16,11 @@ from agents.agent_responses import (
 from constants import MIN_CLUSTERS_THRESHOLD
 from static_analyzer.analysis_result import StaticAnalysisResults
 from static_analyzer.cluster_helpers import (
+    MAX_LLM_CLUSTERS,
+    enforce_cross_language_budget,
     get_all_cluster_ids,
     get_files_for_cluster_ids,
+    merge_clusters,
 )
 from static_analyzer.cluster_relations import (
     build_component_relations,
@@ -71,6 +74,7 @@ class ClusterMethodsMixin:
             Formatted cluster string with headers per language
         """
         cluster_lines = []
+        all_cluster_ids: set[int] = set()
 
         for lang in programming_langs:
             cfg = self.static_analysis.get_cfg(lang)
@@ -83,6 +87,17 @@ class ClusterMethodsMixin:
                 cluster_lines.append(f"\n## {lang.capitalize()} - {header}\n")
                 cluster_lines.append(cluster_str)
                 cluster_lines.append("\n")
+                if cluster_result:
+                    lang_ids = cluster_ids if cluster_ids else cluster_result.get_cluster_ids()
+                    all_cluster_ids.update(lang_ids)
+
+        # Add explicit ID checklist so the LLM knows exactly which IDs to assign
+        if all_cluster_ids and not cluster_ids:
+            sorted_cluster_ids = sorted(all_cluster_ids)
+            cluster_lines.append(
+                f"\n## All Cluster IDs ({len(sorted_cluster_ids)} total)\n"
+                f"Every one of these IDs: {sorted_cluster_ids} must appear in exactly one group."
+            )
 
         return "".join(cluster_lines)
 
@@ -238,7 +253,6 @@ class ClusterMethodsMixin:
             abs_path = os.path.join(self.repo_dir, f) if not os.path.isabs(f) else f
             assigned_file_set.add(abs_path)
 
-        result_parts = []
         cluster_results: dict[str, ClusterResult] = {}
         subgraph_cfgs: dict[str, CallGraph] = {}
 
@@ -254,15 +268,33 @@ class ClusterMethodsMixin:
                 # 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:
+                    n_before = len(sub_cluster_result.clusters)
+                    sub_cluster_result = merge_clusters(sub_cluster_result, sub_cfg.to_networkx(), MAX_LLM_CLUSTERS)
+                    logger.info(
+                        f"[DetailsAgent] Subgraph for '{component.name}': "
+                        f"merged {n_before} -> {len(sub_cluster_result.clusters)} super-clusters"
+                    )
+
                 # Expand to method-level if insufficient clusters
                 sub_cluster_result = self._expand_to_method_level_clusters(sub_cfg, sub_cluster_result)
                 cluster_results[lang] = sub_cluster_result
 
-                cluster_str = sub_cfg.to_cluster_string(cluster_result=sub_cluster_result)
-                if cluster_str.strip() and cluster_str not in ("empty", "none", "No clusters found."):
-                    result_parts.append(f"\n## {lang.capitalize()} - Component CFG\n")
-                    result_parts.append(cluster_str)
-                    result_parts.append("\n")
+        # Cross-language: enforce combined budget and unique IDs
+        if len(cluster_results) > 1:
+            cfg_nx = {lang: subgraph_cfgs[lang].to_networkx() for lang in cluster_results}
+            enforce_cross_language_budget(cluster_results, cfg_nx)
+
+        result_parts = []
+        for lang in self.static_analysis.get_languages():
+            if lang not in cluster_results:
+                continue
+            cluster_str = subgraph_cfgs[lang].to_cluster_string(cluster_result=cluster_results[lang])
+            if cluster_str.strip() and cluster_str not in ("empty", "none", "No clusters found."):
+                result_parts.append(f"\n## {lang.capitalize()} - Component CFG\n")
+                result_parts.append(cluster_str)
+                result_parts.append("\n")
 
         result = "".join(result_parts)
 

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/details_agent.py

@@ -138,6 +138,8 @@ class DetailsAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
         cluster_str = cluster_analysis.llm_str() if cluster_analysis else "No cluster analysis available."
 
+        group_names = [cc.name for cc in cluster_analysis.cluster_components] if cluster_analysis else []
+
         prompt = self.prompts["final_analysis"].format(
             project_name=self.project_name,
             cluster_analysis=cluster_str,
@@ -146,6 +148,12 @@ class DetailsAgent(ClusterMethodsMixin, CodeBoardingAgent):
             project_type=project_type,
         )
 
+        if group_names:
+            prompt += (
+                f"\n\n## All Group Names ({len(group_names)} total)\n"
+                f"Every one of these names: {group_names} must appear in exactly one component's source_group_names\n"
+            )
+
         # Build validation context with subgraph CFG graphs for edge checking
         context = ValidationContext(
             cluster_results=subgraph_cluster_results,

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/meta_agent.py

@@ -46,7 +46,6 @@ class MetaAgent(CodeBoardingAgent):
         )
 
         self._meta_cache = MetaCache(repo_dir=repo_dir, ignore_manager=self.ignore_manager)
-        self._cache = self._meta_cache  # Backward-compatible alias for tests/callers.
 
     @trace
     def analyze_project_metadata(self, skip_cache: bool = False) -> MetaAnalysisInsights:

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/prompts/claude_prompts.py

@@ -67,6 +67,7 @@ Instructions:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale for the grouping decision)
      * How this group interacts with other cluster groups (which groups it calls, receives data from, or depends on)
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on:
 - Creating cohesive, logical groupings that reflect the actual {project_type} architecture
@@ -294,6 +295,7 @@ Instructions:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale)
      * How this group interacts with other cluster groups
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on core subsystem functionality only. Avoid cross-cutting concerns like logging or error handling.
 

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/prompts/deepseek_prompts.py

@@ -63,6 +63,7 @@ The CFG has been pre-clustered into groups of related methods/functions. Each cl
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale for the grouping decision)
      * How this group interacts with other cluster groups (which groups it calls, receives data from, or depends on)
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 # Focus areas
 - Create cohesive, logical groupings that reflect the actual {project_type} architecture
@@ -296,6 +297,7 @@ The CFG has been pre-clustered into groups of related methods/functions. Each cl
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale)
      * How this group interacts with other cluster groups
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 # Focus
 Analyze core subsystem functionality only. Avoid cross-cutting concerns like logging or error handling.

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/prompts/gemini_flash_prompts.py

@@ -49,6 +49,10 @@ CFG Clusters:
 Your Task:
 GROUP similar clusters together into logical components based on their relationships and purpose.
 
+CRITICAL requirements:
+- Every cluster ID must be included in exactly one group — no cluster left out, no duplicates
+- Each group must represent a coherent architectural concept justified by method names, call patterns, and inter-cluster connections
+
 Instructions:
 1. Analyze the clusters shown above and identify which ones work together or are functionally related
 2. Group related clusters into meaningful components
@@ -61,6 +65,7 @@ Instructions:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale for the grouping decision)
      * How this group interacts with other cluster groups (which groups it calls, receives data from, or depends on)
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on:
 - Creating cohesive, logical groupings that reflect the actual {project_type} architecture
@@ -275,6 +280,7 @@ Instructions:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale)
      * How this group interacts with other cluster groups
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on core subsystem functionality only. Avoid cross-cutting concerns like logging or error handling.
 

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/prompts/glm_prompts.py

@@ -67,6 +67,7 @@ REQUIRED STEPS (execute in order):
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (MUST provide clear rationale)
      * How this group interacts with other cluster groups (which groups it calls, receives data from, or depends on)
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 FOCUS AREAS (prioritize):
 - Create cohesive, logical groupings that reflect the actual {project_type} architecture
@@ -313,6 +314,7 @@ REQUIRED STEPS (execute in order):
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (MUST provide clear rationale)
      * How this group interacts with other cluster groups
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 FOCUS:
 MUST analyze core subsystem functionality only. STRICTLY avoid cross-cutting concerns like logging or error handling.

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/prompts/gpt_prompts.py

@@ -69,6 +69,7 @@ Instructions:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale for the grouping decision)
      * How this group interacts with other cluster groups (which groups it calls, receives data from, or depends on)
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on:
 - Creating cohesive, logical groupings that reflect the actual {project_type} architecture
@@ -383,6 +384,7 @@ Instructions:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale)
      * How this group interacts with other cluster groups
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on core subsystem functionality only. Avoid cross-cutting concerns like logging or error handling.
 

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/prompts/kimi_prompts.py

@@ -62,6 +62,7 @@ Reason carefully, then execute:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale for the grouping decision)
      * How this group interacts with other cluster groups (which groups it calls, receives data from, or depends on)
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on creating cohesive, logical groupings that reflect the actual {project_type} architecture based on semantic meaning from method names, call patterns, and architectural context. Describe inter-group interactions based on the inter-cluster connections.
 
@@ -303,6 +304,7 @@ Reason carefully, then execute:
      * What is its main flow/purpose
      * WHY these specific clusters are grouped together (provide clear rationale)
      * How this group interacts with other cluster groups
+     * The most important classes/methods in this group — mention their exact qualified names as shown in the clusters above
 
 Focus on core subsystem functionality only. Avoid cross-cutting concerns like logging or error handling.
 

{codeboarding-0.10.0 → codeboarding-0.10.2}/agents/validation.py

@@ -322,11 +322,9 @@ def validate_group_name_coverage(result: AnalysisInsights, context: ValidationCo
 def validate_key_entities(result: AnalysisInsights, context: ValidationContext) -> ValidationResult:
     """
     Validate key_entities on every component:
-    1. Every component must have at least one key_entity.
-    2. Key entities must reference code within the component's cluster scope.
-       If cluster_results are provided, validates strictly against the scope.
-       Otherwise, validates that qualified names exist in the static analysis.
-       Uses loose matching to auto-correct shortened paths in-place.
+    1. Auto-correct qualified names via loose matching.
+    2. Silently drop invalid key entities (out of scope or not found).
+    3. Only fail if a component ends up with zero key_entities after dropping.
 
     Args:
         result: AnalysisInsights containing components with key_entities
@@ -334,26 +332,8 @@ def validate_key_entities(result: AnalysisInsights, context: ValidationContext)
                  and cluster_results for scope validation
 
     Returns:
-        ValidationResult with feedback for missing or invalid key entities
+        ValidationResult with feedback only for components left with zero key entities
     """
-    feedback_messages: list[str] = []
-
-    # Check 1: components without any key_entities
-    components_without_key_entities = [c.name for c in result.components if not c.key_entities]
-    if components_without_key_entities:
-        missing_str = ", ".join(components_without_key_entities)
-        feedback_messages.append(
-            f"The following components are missing key entities: {missing_str}. "
-            f"Every component must have at least one key entity (critical class or method) "
-            f"that represents its core functionality. Please identify and add 2-5 key entities "
-            f"for each component."
-        )
-        logger.warning(f"[Validation] Components without key entities: {missing_str}")
-
-    # Check 2: Unified scope/existence check — key entities must be valid for this component.
-    # Auto-correct via loose matching first (fixes typos in qualified names).
-    # Then validate against cluster scope (strict) or static analysis existence (fallback).
-    invalid_entities: list[str] = []
     auto_corrected = 0
 
     # Auto-correct qualified names via loose matching (always, when static_analysis available)
@@ -362,13 +342,11 @@ def validate_key_entities(result: AnalysisInsights, context: ValidationContext)
             for key_entity in component.key_entities:
                 qname = key_entity.qualified_name.replace("/", ".")
                 for lang in context.static_analysis.get_languages():
-                    # Exact / case-insensitive match
                     try:
                         context.static_analysis.get_reference(lang, qname)
                         break
                     except (ValueError, FileExistsError):
                         pass
-                    # Loose match – auto-correct the qualified name in-place
                     _text, loose_node = context.static_analysis.get_loose_reference(lang, qname)
                     if loose_node is not None:
                         logger.info(
@@ -381,7 +359,8 @@ def validate_key_entities(result: AnalysisInsights, context: ValidationContext)
         if auto_corrected:
             logger.info(f"[Validation] Auto-corrected {auto_corrected} qualified names via loose matching")
 
-    # Validate: cluster scope if available, else static analysis existence
+    # Silently drop invalid key entities
+    dropped = 0
     if context.cluster_results:
         nodes_in_scope: set[str] = set()
         for cr in context.cluster_results.values():
@@ -389,35 +368,24 @@ def validate_key_entities(result: AnalysisInsights, context: ValidationContext)
                 nodes_in_scope.update(members)
 
         for component in result.components:
+            valid = []
             for key_entity in component.key_entities:
                 qname = key_entity.qualified_name
                 in_scope = qname in nodes_in_scope
                 if not in_scope:
                     for scope_node in nodes_in_scope:
-                        if qname.startswith(scope_node + "."):
+                        if qname.startswith(scope_node + ".") or scope_node.startswith(qname + "."):
                             in_scope = True
                             break
-                    if not in_scope:
-                        for scope_node in nodes_in_scope:
-                            if scope_node.startswith(qname + "."):
-                                in_scope = True
-                                break
-                if not in_scope:
-                    invalid_entities.append(f"{component.name}: '{qname}'")
-
-        if invalid_entities:
-            invalid_str = "; ".join(invalid_entities[:10])
-            more_msg = f" and {len(invalid_entities) - 10} more" if len(invalid_entities) > 10 else ""
-            feedback_messages.append(
-                f"The following key_entities are outside the component's cluster scope: {invalid_str}{more_msg}. "
-                f"Key entities must reference code that is within the component's assigned clusters. "
-                f"Please choose key entities from the code shown in the cluster analysis."
-            )
-            logger.warning(f"[Validation] Invalid key entities (out of scope): {len(invalid_entities)} found")
+                if in_scope:
+                    valid.append(key_entity)
+                else:
+                    dropped += 1
+            component.key_entities = valid
 
     elif context.static_analysis:
-        # No cluster_results — fall back to checking if qualified names exist in static analysis
         for component in result.components:
+            valid = []
             for key_entity in component.key_entities:
                 qname = key_entity.qualified_name.replace("/", ".")
                 found = False
@@ -433,23 +401,31 @@ def validate_key_entities(result: AnalysisInsights, context: ValidationContext)
                         key_entity.qualified_name = loose_node.fully_qualified_name
                         found = True
                         break
-                if not found:
-                    invalid_entities.append(f"{component.name}: '{key_entity.qualified_name}'")
+                if found:
+                    valid.append(key_entity)
+                else:
+                    dropped += 1
+            component.key_entities = valid
 
-        if invalid_entities:
-            invalid_str = "; ".join(invalid_entities[:10])
-            more_msg = f" and {len(invalid_entities) - 10} more" if len(invalid_entities) > 10 else ""
-            feedback_messages.append(
-                f"The following qualified names do not exist in the static analysis: {invalid_str}{more_msg}. "
-                f"Please ensure all key_entities use qualified names that were found during static analysis."
-            )
-            logger.warning(f"[Validation] Invalid key entities (not found): {len(invalid_entities)} found")
+    if dropped:
+        logger.info(f"[Validation] Silently dropped {dropped} invalid key entities")
 
-    if not feedback_messages:
-        logger.info("[Validation] All key entities are valid")
-        return ValidationResult(is_valid=True)
+    # Only fail if any component ended up with zero key_entities
+    empty_components = [c.name for c in result.components if not c.key_entities]
+    if empty_components:
+        missing_str = ", ".join(empty_components)
+        logger.warning(f"[Validation] Components with no valid key entities after cleanup: {missing_str}")
+        return ValidationResult(
+            is_valid=False,
+            feedback_messages=[
+                f"The following components have no valid key entities: {missing_str}. "
+                f"Every component must have at least one key entity (critical class or method) "
+                f"that represents its core functionality. Use exact qualified names from the cluster analysis."
+            ],
+        )
 
-    return ValidationResult(is_valid=False, feedback_messages=feedback_messages)
+    logger.info("[Validation] All key entities are valid")
+    return ValidationResult(is_valid=True)
 
 
 def validate_file_classifications(result: ComponentFiles, context: ValidationContext) -> ValidationResult:

{codeboarding-0.10.0 → codeboarding-0.10.2/codeboarding.egg-info}/PKG-INFO

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

{codeboarding-0.10.0 → codeboarding-0.10.2}/diagram_analysis/analysis_json.py

@@ -80,6 +80,7 @@ def _hydrate_component_methods_from_refs(
     files_index: dict[str, FileEntry],
     methods_index: dict[str, "MethodIndexEntry"],
 ) -> None:
+    missing: list[str] = []
     for component in analysis.components:
         rebuilt: list[FileMethodGroup] = []
         for group in component.file_methods:
@@ -91,7 +92,7 @@ def _hydrate_component_methods_from_refs(
                 qname = _to_method_qualified_name(method)
                 indexed = methods_index.get(_method_key(file_path, qname))
                 if indexed is None:
-                    logger.warning(f"Missing method index entry for {file_path}|{qname}")
+                    missing.append(f"{file_path}|{qname}")
                     continue
                 methods.append(
                     MethodEntry(
@@ -108,6 +109,9 @@ def _hydrate_component_methods_from_refs(
 
         component.file_methods = rebuilt
 
+    if missing:
+        logger.warning("Missing method index entry for %d ref(s): %s", len(missing), missing)
+
 
 class RelationJson(Relation):
     """Relation subclass that includes src_id/dst_id and static analysis evidence in JSON serialization."""

{codeboarding-0.10.0 → codeboarding-0.10.2}/diagram_analysis/incremental_updater.py

@@ -10,6 +10,7 @@ NOTE: Method status assignment is delegated to repo_utils.method_diff to ensure
 consistent behavior between the main analysis pipeline and incremental updates.
 """
 
+import logging
 import time
 from pathlib import Path
 from typing import Callable
@@ -21,6 +22,8 @@ from diagram_analysis.manifest import AnalysisManifest
 from repo_utils.change_detector import ChangeSet
 from repo_utils.method_diff import get_method_statuses_for_file
 
+logger = logging.getLogger(__name__)
+
 # Callable that resolves a repo-relative file path to its current MethodEntry list.
 SymbolResolver = Callable[[str], list[MethodEntry]]
 
@@ -124,7 +127,29 @@ class IncrementalUpdater:
 
         # Modified
         prev_active = self._get_previous_active_methods(file_path)
-        current = self._get_current_methods(file_path)
+        try:
+            current = self._get_current_methods(file_path)
+        except Exception as exc:
+            logger.warning("Symbol resolution failed for %s: %s", file_path, exc)
+            current = []
+
+        if not current and prev_active:
+            logger.warning(
+                "Symbol resolution returned no methods for %s; marking all existing methods as modified",
+                file_path,
+            )
+            return (
+                FileDelta(
+                    file_path=file_path,
+                    file_status=ChangeStatus.MODIFIED,
+                    component_id=component_id,
+                    modified_methods=[
+                        self._to_method_change(file_path, m, change_type=ChangeStatus.MODIFIED)
+                        for _, m in sorted(prev_active.items())
+                    ],
+                ),
+                missing,
+            )
         current_by_name = {m.qualified_name: m for m in current}
 
         prev_keys = set(prev_active.keys())
@@ -138,7 +163,7 @@ class IncrementalUpdater:
                 file_status=ChangeStatus.MODIFIED,
                 component_id=component_id,
                 added_methods=[
-                    self._to_method_change(file_path, m)
+                    self._to_method_change(file_path, m, change_type=ChangeStatus.ADDED)
                     for m in current
                     if m.qualified_name in current_keys - prev_keys
                 ],