codeboarding 0.13.2__tar.gz → 0.13.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.13.2
+Version: 0.13.4
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -73,6 +73,7 @@ Dynamic: license-file
 # CodeBoarding
 
 [![Website](https://img.shields.io/badge/Site-CodeBoarding.org-5865F2?style=for-the-badge&logoColor=white)](https://codeboarding.org)
+[![Web platform](https://img.shields.io/badge/Web%20platform-app.codeboarding.org-2563EB?style=for-the-badge&logoColor=white)](https://app.codeboarding.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Us-5865F2?style=for-the-badge&logoColor=white)](https://discord.gg/T5zHTJYFuy)
 [![GitHub](https://img.shields.io/badge/GitHub-CodeBoarding-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/CodeBoarding/CodeBoarding)
 
@@ -130,6 +131,9 @@ codeboarding full --local /path/to/repo
 codeboarding full https://github.com/user/repo
 ```
 
+To explore the result interactively, open the [web platform](https://app.codeboarding.org) and load the
+generated `.codeboarding/analysis.json` — it is parsed in your browser, nothing is uploaded.
+
 ### Python API
 
 ```python
@@ -153,7 +157,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 +215,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.4}/PYPI.md

@@ -1,6 +1,7 @@
 # CodeBoarding
 
 [![Website](https://img.shields.io/badge/Site-CodeBoarding.org-5865F2?style=for-the-badge&logoColor=white)](https://codeboarding.org)
+[![Web platform](https://img.shields.io/badge/Web%20platform-app.codeboarding.org-2563EB?style=for-the-badge&logoColor=white)](https://app.codeboarding.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Us-5865F2?style=for-the-badge&logoColor=white)](https://discord.gg/T5zHTJYFuy)
 [![GitHub](https://img.shields.io/badge/GitHub-CodeBoarding-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/CodeBoarding/CodeBoarding)
 
@@ -58,6 +59,9 @@ codeboarding full --local /path/to/repo
 codeboarding full https://github.com/user/repo
 ```
 
+To explore the result interactively, open the [web platform](https://app.codeboarding.org) and load the
+generated `.codeboarding/analysis.json` — it is parsed in your browser, nothing is uploaded.
+
 ### Python API
 
 ```python
@@ -81,7 +85,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 +143,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.4}/README.md

@@ -4,7 +4,7 @@ See what your AI is building before it breaks.
 
 CodeBoarding gives developers and coding agents a visual map of a codebase. It combines static analysis with LLM reasoning to generate architecture diagrams, component-level documentation, and navigable outputs you can use in your IDE, CI, and docs.
 
-[Website](https://codeboarding.org) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=0855d476-b2d0-44cc-b93d-69b47504719c" width="0" height="0" /> · [Open VSX extension](https://open-vsx.org/extension/CodeBoarding/codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=ce87464c-2792-46b0-9ea2-87eefe853d7e" width="0" height="0" /> · [Explore examples](https://codeboarding.org/diagrams) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8a3d26e0-6f6b-49c0-8482-114445de56a5" width="0" height="0" /> · [GitHub Action](https://github.com/marketplace/actions/codeboarding-action) ·[Discord](https://discord.gg/T5zHTJYFuy)
+[Website](https://codeboarding.org) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=0855d476-b2d0-44cc-b93d-69b47504719c" width="0" height="0" /> · [Web platform](https://app.codeboarding.org) · [Open VSX extension](https://open-vsx.org/extension/CodeBoarding/codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=ce87464c-2792-46b0-9ea2-87eefe853d7e" width="0" height="0" /> · [Explore examples](https://codeboarding.org/diagrams) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8a3d26e0-6f6b-49c0-8482-114445de56a5" width="0" height="0" /> · [GitHub Action](https://github.com/marketplace/actions/codeboarding-action) · [Discord](https://discord.gg/T5zHTJYFuy)
 
 [![CodeBoarding demo](https://gist.githubusercontent.com/ivanmilevtues/1c4f921066613516cfd7b938014a6877/raw/611aec7711556807860ff2e1679a5dc4c0c23fed/CodeBoarding_extension_demo.gif)](https://open-vsx.org/extension/CodeBoarding/codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=ce87464c-2792-46b0-9ea2-87eefe853d7e" width="0" height="0" />
 
@@ -91,7 +91,9 @@ codeboarding-setup
 codeboarding full --local /path/to/repo
 ```
 
-Output is written to `/path/to/repo/.codeboarding/`.
+Output is written to `/path/to/repo/.codeboarding/`. To explore it interactively, open the
+[web platform](https://app.codeboarding.org) and drop in the generated `analysis.json` — it stays
+in your browser, nothing is uploaded. (The CLI prints this reminder after every successful run.)
 
 `python install.py` and `codeboarding-setup` download language server binaries to `~/.codeboarding/servers/`, shared across projects. Node.js (and its bundled `npm`) is required for the Python, TypeScript, JavaScript, and PHP language servers; if neither `node` nor `CODEBOARDING_NODE_PATH` is set, setup downloads a pinned Node.js runtime into `~/.codeboarding/servers/nodeenv/` automatically.
 
@@ -124,8 +126,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
@@ -148,6 +152,7 @@ python main.py full https://github.com/pytorch/pytorch
 ## Where to use it
 
 - [CLI](https://github.com/CodeBoarding/CodeBoarding) for local analysis, automation, and CI workflows.
+- [Web platform](https://app.codeboarding.org) to explore any analysis in the browser — open a public repo, load an `analysis.json`, or review an architecture diff on a pull request.
 - [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8a3d26e0-6f6b-49c0-8482-114445de56a5" width="0" height="0" /> for in-editor visual architecture.
 - [GitHub Action](https://github.com/marketplace/actions/codeboarding-action) to keep diagrams updated in CI.
 
@@ -161,6 +166,7 @@ python main.py full https://github.com/pytorch/pytorch
 - Visualized 800+ open-source repositories.
 - Browse generated examples in [GeneratedOnBoardings](https://github.com/CodeBoarding/GeneratedOnBoardings).
 - Try the hosted explorer at [codeboarding.org/diagrams](https://codeboarding.org/diagrams) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=0855d476-b2d0-44cc-b93d-69b47504719c" width="0" height="0" />.
+- Open any public repo that has a committed `.codeboarding/analysis.json` at [app.codeboarding.org](https://app.codeboarding.org) — no install, no login. This repo included: [app.codeboarding.org/CodeBoarding/CodeBoarding](https://app.codeboarding.org/CodeBoarding/CodeBoarding).
 
 ## Telemetry
 

{codeboarding-0.13.2 → codeboarding-0.13.4}/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.4}/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.4}/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"