codeboarding 0.13.8__tar.gz → 0.13.11__tar.gz

{codeboarding-0.13.8/codeboarding.egg-info → codeboarding-0.13.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.13.8
+Version: 0.13.11
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -10,10 +10,9 @@ Keywords: code-understanding,code-visualization,code-analysis,diagrams,documenta
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Software Development :: Code Generators
-Requires-Python: <3.14,>=3.12
+Requires-Python: <3.13,>=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: docker>=7.1
@@ -23,6 +22,7 @@ Requires-Dist: fastapi>=0.115
 Requires-Dist: filelock>=3.12
 Requires-Dist: gitpython>=3.1
 Requires-Dist: google-api-core>=2.10
+Requires-Dist: igraph>=1.0
 Requires-Dist: jsonpatch>=1.33
 Requires-Dist: jsonschema>=4.25
 Requires-Dist: langchain>=1.2
@@ -30,9 +30,11 @@ Requires-Dist: langchain-anthropic>=1.3
 Requires-Dist: langchain-aws>=1.1
 Requires-Dist: langchain-cerebras>=0.8
 Requires-Dist: langchain-community>=0.4
+Requires-Dist: langchain-core>=1.2
 Requires-Dist: langchain-google-genai>=3.1
 Requires-Dist: langchain-ollama>=1.0
 Requires-Dist: langchain-openai>=1.1
+Requires-Dist: langgraph>=1.0
 Requires-Dist: leidenalg>=0.10
 Requires-Dist: markdown>=3.8
 Requires-Dist: markdown-it-py>=3.0
@@ -44,7 +46,10 @@ Requires-Dist: posthog>=3.7
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2024.11
+Requires-Dist: requests>=2.32
 Requires-Dist: rich>=12.6
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: tqdm>=4.67
 Requires-Dist: tree-sitter==0.25.2
 Requires-Dist: tree-sitter-c-sharp==0.23.5
 Requires-Dist: tree-sitter-go==0.25.0
@@ -191,10 +196,13 @@ LLM provider keys and model overrides are stored in `~/.codeboarding/config.toml
 # google_api_key    = "AIza..."
 # ollama_base_url   = "http://localhost:11434"
 
+# Optional Anthropic endpoint override; requires anthropic_api_key above
+# anthropic_base_url = "https://resource.services.ai.azure.com/anthropic"
+
 [llm]
 # Optional: override the default model for your active provider
-# agent_model   = "gemini-3-flash"
-# parsing_model = "gemini-3-flash"
+# agent_model   = "gemini-3.7-flash"
+# parsing_model = "gemini-3.1-flash-lite"
 ```
 
 Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always take precedence over the config file, so CI/CD pipelines need no changes. For private repositories, set `GITHUB_TOKEN` in your environment.
@@ -208,13 +216,16 @@ Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always
 ```
 codeboarding full [REPO_URL ...]           # remote: clone + analyze
 codeboarding full --local PATH             # local: analyze in-place
+codeboarding full --local PATH --render FORMAT # render md/html/mdx/rst after analysis
 codeboarding incremental --local PATH      # re-analyze only changed parts
 codeboarding partial --local PATH --component-id ID   # update one component
+codeboarding-render PATH/analysis.json --format FORMAT # render an existing analysis
 ```
 
 | Option | Description |
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
+| `--render {md,html,mdx,rst}` | Render overview and component files from the local `analysis.json` for full, incremental, or partial commands |
 | `--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 |

{codeboarding-0.13.8 → codeboarding-0.13.11}/PYPI.md

@@ -119,10 +119,13 @@ LLM provider keys and model overrides are stored in `~/.codeboarding/config.toml
 # google_api_key    = "AIza..."
 # ollama_base_url   = "http://localhost:11434"
 
+# Optional Anthropic endpoint override; requires anthropic_api_key above
+# anthropic_base_url = "https://resource.services.ai.azure.com/anthropic"
+
 [llm]
 # Optional: override the default model for your active provider
-# agent_model   = "gemini-3-flash"
-# parsing_model = "gemini-3-flash"
+# agent_model   = "gemini-3.7-flash"
+# parsing_model = "gemini-3.1-flash-lite"
 ```
 
 Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always take precedence over the config file, so CI/CD pipelines need no changes. For private repositories, set `GITHUB_TOKEN` in your environment.
@@ -136,13 +139,16 @@ Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always
 ```
 codeboarding full [REPO_URL ...]           # remote: clone + analyze
 codeboarding full --local PATH             # local: analyze in-place
+codeboarding full --local PATH --render FORMAT # render md/html/mdx/rst after analysis
 codeboarding incremental --local PATH      # re-analyze only changed parts
 codeboarding partial --local PATH --component-id ID   # update one component
+codeboarding-render PATH/analysis.json --format FORMAT # render an existing analysis
 ```
 
 | Option | Description |
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
+| `--render {md,html,mdx,rst}` | Render overview and component files from the local `analysis.json` for full, incremental, or partial commands |
 | `--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 |

{codeboarding-0.13.8 → codeboarding-0.13.11}/README.md

@@ -95,6 +95,27 @@ Output is written to `/path/to/repo/.codeboarding/`. To explore it interactively
 [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.)
 
+To also generate `overview` and one file per expanded component, pass `--render` with one of
+`md`, `html`, `mdx`, or `rst`. Rendering is available after full, incremental, and partial local analyses;
+previously generated files for the selected format are reconciled from a renderer-owned manifest:
+
+```bash
+codeboarding full --local /path/to/repo --render md
+codeboarding incremental --local /path/to/repo --render html
+codeboarding partial --local /path/to/repo --component-id "1.2" --render rst
+```
+
+You can render an existing analysis without rerunning analysis or configuring an LLM:
+
+```bash
+codeboarding-render /path/to/repo/.codeboarding/analysis.json
+# Select a format or output directory:
+codeboarding-render /path/to/analysis.json --format mdx --output-dir /path/to/docs
+
+# From a source checkout in development:
+python codeboarding_cli/render.py ../../demo/markitdown/.codeboarding/analysis.json --format md
+```
+
 `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.
 
 ## Configuration
@@ -106,21 +127,25 @@ On first run, CodeBoarding creates `~/.codeboarding/config.toml`. Set one provid
 # openai_api_key            = "sk-..."
 # openai_base_url           = "https://api.example.com/v1"  # any OpenAI-compatible gateway
 # anthropic_api_key         = "sk-ant-..."
+# anthropic_base_url        = "https://resource.services.ai.azure.com/anthropic"  # Azure Foundry
 # google_api_key            = "AIza..."
 # vercel_api_key            = "vck_..."
 # aws_bearer_token_bedrock  = "..."
 # ollama_base_url           = "http://localhost:11434"
 # openrouter_api_key        = "sk-..."
+# orcarouter_api_key        = "sk-orca-..."   # model routing gateway (https://www.orcarouter.ai)
 # litellm_base_url          = "http://localhost:4000"  # LiteLLM proxy server URL (required)
 # litellm_api_key           = "sk-..."           # LiteLLM proxy server key (optional)
 
 [llm]
-# agent_model   = "gemini-3-flash"
-# parsing_model = "gemini-3-flash"
+# agent_model   = "gemini-3.7-flash"
+# parsing_model = "gemini-3.1-flash-lite"
 ```
 
 `openai_base_url` points CodeBoarding at any OpenAI-compatible gateway. Set the gateway API key as `openai_api_key`, then choose its model IDs with `agent_model` and `parsing_model`. The equivalent shell variables are `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `AGENT_MODEL`, and `PARSING_MODEL`.
 
+`anthropic_base_url` points the Anthropic client at a compatible Messages API, including Azure Foundry Claude deployments. Set the deployment key as `anthropic_api_key` and use canonical Anthropic model IDs such as `claude-sonnet-5` for `agent_model` and `parsing_model` so CodeBoarding selects the correct model capabilities and prompts.
+
 Shell environment variables such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, and `OLLAMA_BASE_URL` take precedence over the config file. For private repositories, set `GITHUB_TOKEN` in your environment.
 
 ## Common commands
@@ -150,7 +175,8 @@ python main.py full https://github.com/pytorch/pytorch
 > `.codeboarding/` only if you want the baseline to travel with the branch (so a teammate or a
 > fresh checkout can run incremental too). With no baseline at all — or one that predates content
 > versioning — `incremental` fails fast with "run a full analysis first" rather than silently
-> doing a full run.
+> doing a full run. Static-analysis caches are versioned but not migrated; after a cache-version
+> upgrade, run a full analysis once to reindex.
 
 ## Where to use it
 
@@ -162,7 +188,7 @@ python main.py full https://github.com/pytorch/pytorch
 ## Supported stack
 
 - Languages: Python, TypeScript, JavaScript, Java, Go, PHP, Rust, C#.
-- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, LiteLLM proxy, and more.
+- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, OrcaRouter, LiteLLM proxy, and more.
 
 ## Examples
 

{codeboarding-0.13.8 → codeboarding-0.13.11}/agents/abstraction_agent.py

@@ -10,12 +10,16 @@ from agents.agent_responses import (
     ComponentApiSurfaces,
     ComponentArchitecture,
     ComponentRelations,
-    ClusterAnalysis,
     MetaAnalysisInsights,
-    assign_component_ids,
     assign_relation_ids,
 )
-from agents.cluster_methods_mixin import ClusterMethodsMixin
+from agents.component_ownership import group_ids_by_name
+from agents.llm_renderers import (
+    cluster_group_descriptions,
+    cluster_group_ids,
+    render_cluster_groups,
+    render_scope_connections,
+)
 from agents.prompts import (
     get_final_analysis_message,
     get_api_surfaces_message,
@@ -24,7 +28,13 @@ from agents.prompts import (
     format_project_system_message,
 )
 from agents.relation_edges import index_relation_endpoints
-from agents.repair import ComponentRepairContext, repair_component_group_names, repair_key_entities
+from agents.repair import (
+    ComponentRepairContext,
+    ensure_unique_key_entities,
+    repair_component_group_names,
+    repair_key_entities,
+)
+from agents.static_analysis_enricher_mixin import StaticAnalysisEnricherMixin
 from agents.validation import (
     ValidationContext,
     validate_group_name_coverage,
@@ -34,14 +44,12 @@ from agents.validation import (
 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
-from static_analyzer.constants import Language
-from static_analyzer.graph import ClusterResult
+from static_analyzer.clustering import ClusterResult, ClusterScopeResult
 
 logger = logging.getLogger(__name__)
 
 
-class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
+class AbstractionAgent(StaticAnalysisEnricherMixin, CodeBoardingAgent):
     def __init__(
         self,
         repo_dir: Path,
@@ -79,33 +87,40 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
             ),
         }
 
-    @trace
-    def step_clusters_grouping(self, cluster_results: dict[str, ClusterResult]) -> ClusterAnalysis:
-        """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)
+    def run(self, scope: ClusterScopeResult) -> AnalysisInsights:
+        if not scope.groups:
+            # 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."
+            )
 
-    @trace
-    def step_final_analysis(
-        self, llm_cluster_analysis: ClusterAnalysis, cluster_results: dict[str, ClusterResult]
-    ) -> AnalysisInsights:
-        logger.info(f"[AbstractionAgent] Generating final component analysis for: {self.project_name}")
+        analysis = self._step_llm_analysis(scope)
+        self.populate_file_methods(analysis, scope)
+
+        api_surfaces = self._step_api_surfaces(analysis, scope)
+        self._step_relation_analysis(analysis, api_surfaces, scope)
+
+        analysis = self.reference_resolver.fix_source_code_reference_lines(analysis)
+        index_relation_endpoints(analysis, self.repo_dir)
+        ensure_unique_key_entities(analysis)
 
-        cluster_str = llm_cluster_analysis.llm_str() if llm_cluster_analysis else "No cluster analysis available."
+        return analysis
 
-        group_names = [cc.name for cc in llm_cluster_analysis.cluster_components] if llm_cluster_analysis else []
+    @trace
+    def _step_llm_analysis(self, scope: ClusterScopeResult) -> AnalysisInsights:
+        logger.info(f"[AbstractionAgent] Generating final component analysis for: {self.project_name}")
+        cluster_results = scope.leaf_clusters_by_language
+        group_ids = cluster_group_ids(scope.groups)
+        group_names = list(group_ids)
 
         prompt = self.prompts["final_analysis"].format(
-            cluster_analysis=cluster_str,
+            cluster_analysis=render_cluster_groups(
+                group_ids,
+                cluster_group_descriptions(scope),
+            ),
         )
 
         if group_names:
@@ -117,7 +132,7 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
         context = ValidationContext(
             cluster_results=cluster_results,
             static_analysis=self.static_analysis,
-            llm_cluster_analysis=llm_cluster_analysis,
+            group_ids=group_ids,
         )
 
         architecture = self._invoke_repair_validate(
@@ -131,12 +146,12 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
             repair_context=ComponentRepairContext(
                 reference_resolver=self.reference_resolver,
                 cluster_results=cluster_results,
-                llm_cluster_analysis=llm_cluster_analysis,
+                group_ids=group_ids,
             ),
             validation_context=context,
             max_validation_attempts=3,
         )
-        self.assemble_one_component_per_group(architecture, llm_cluster_analysis, cluster_results)
+        self.assemble_one_component_per_group(architecture, scope)
         return AnalysisInsights(
             description=architecture.description,
             components=architecture.components,
@@ -144,9 +159,16 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
         )
 
     @trace
-    def step_api_surfaces(self, analysis: AnalysisInsights) -> ComponentApiSurfaces:
+    def _step_api_surfaces(
+        self,
+        analysis: AnalysisInsights,
+        scope: ClusterScopeResult,
+    ) -> ComponentApiSurfaces:
         logger.info(f"[AbstractionAgent] Analyzing component API surfaces for: {self.project_name}")
-        static_call_evidence = self.build_scope_cfg_string(analysis)
+        static_call_evidence = render_scope_connections(
+            scope,
+            {component.component_id: component.name for component in analysis.components},
+        )
         prompt = self.prompts["api_surfaces"].format(
             component_summaries=analysis.llm_str(),
             static_call_evidence=static_call_evidence,
@@ -154,17 +176,23 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
         return self._parse_invoke(prompt, ComponentApiSurfaces)
 
     @trace
-    def step_relation_analysis(
+    def _step_relation_analysis(
         self,
         analysis: AnalysisInsights,
         api_surfaces: ComponentApiSurfaces,
-        cluster_analysis: ClusterAnalysis,
-        cluster_results: dict[str, ClusterResult],
+        scope: ClusterScopeResult,
     ) -> None:
         logger.info(f"[AbstractionAgent] Discovering component relations for: {self.project_name}")
-        static_call_evidence = self.build_scope_cfg_string(analysis)
-        cfg_graphs = self.static_analysis.available_cfgs()
-        self.toolkit.context.cluster_analysis = cluster_analysis
+        cluster_results = scope.leaf_clusters_by_language
+        static_call_evidence = render_scope_connections(
+            scope,
+            {component.component_id: component.name for component in analysis.components},
+        )
+        cfg_graphs = scope.graphs_by_language
+        self.toolkit.context.clustering = scope
+        self.toolkit.context.group_ids_by_name = group_ids_by_name(
+            analysis.components, {group.group_id for group in scope.groups}
+        )
         self.toolkit.context.cluster_results = cluster_results
         self.toolkit.context.cfg_graphs = cfg_graphs
         prompt = self.prompts["relation_analysis"].format(
@@ -181,50 +209,10 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
                 cfg_graphs=cfg_graphs,
                 repo_dir=str(self.repo_dir),
                 static_analysis=self.static_analysis,
-                llm_cluster_analysis=cluster_analysis,
                 components=analysis.components,
             ),
             max_validation_attempts=3,
         )
         analysis.components_relations = relation_result.components_relations
         assign_relation_ids(analysis)
-        self.build_static_relations(analysis)
-
-    def run(self):
-        # Build full cluster results dict for all languages ONCE
-        cluster_results = build_all_cluster_results(self.static_analysis)
-
-        # 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: 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)
-        # Step 4: Resolve cluster IDs deterministically from group names
-        self._resolve_cluster_ids_from_groups(analysis, cluster_analysis)
-        # Step 5: Populate file_methods deterministically from cluster results + orphan assignment
-        self.populate_file_methods(analysis, cluster_results)
-
-        # Step 6: Analyze component API surfaces
-        api_surfaces = self.step_api_surfaces(analysis)
-
-        # Step 7: Discover relations from API surfaces and attach deterministic all_edges
-        self.step_relation_analysis(analysis, api_surfaces, cluster_analysis, cluster_results)
-
-        # Step 8: Fix source code reference lines (resolves reference_file paths for key_entities and key_edges)
-        analysis = self.reference_resolver.fix_source_code_reference_lines(analysis)
-        # Step 9: Index relation endpoints after reference resolution
-        index_relation_endpoints(analysis, self.repo_dir)
-        # Step 10: Ensure unique key entities across components
-        self._ensure_unique_key_entities(analysis)
-
-        return analysis, cluster_results
+        self.merge_scope_relations(analysis, scope)

{codeboarding-0.13.8 → codeboarding-0.13.11}/agents/agent_responses.py

@@ -5,20 +5,17 @@ import logging
 from abc import abstractmethod
 from collections.abc import Hashable
 from enum import StrEnum
-from typing import TYPE_CHECKING, get_origin
+from typing import 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
+from clustering_ids import ComponentId
+from agents.file_index_models import FileEntry, FileMethodGroup, MethodIndexEntry
 from agents.scope_ids import ROOT_SCOPE_ID
 
 logger = logging.getLogger(__name__)
 
-if TYPE_CHECKING:
-    from diagram_analysis.analysis_json import MethodIndexEntry
-
 
 class LLMBaseModel(BaseModel, abc.ABC):
     """Base model for LLM-parseable response types."""
@@ -317,7 +314,7 @@ class Relation(LLMBaseModel):
             src_id=src_id,
             dst_id=dst_id,
             is_static=is_static,
-            all_edges=cls._unique_edges(edges),
+            all_edges=cls.unique_edges(edges),
         )
 
     def llm_str(self) -> str:
@@ -356,12 +353,12 @@ class Relation(LLMBaseModel):
     def _merge_edges(
         key_edges: list[RelationEdge], all_edges: list[RelationEdge]
     ) -> tuple[list[RelationEdge], list[RelationEdge]]:
-        merged_key_edges = Relation._unique_edges(key_edges)
-        merged_all_edges = Relation._unique_edges([*all_edges, *merged_key_edges])
+        merged_key_edges = Relation.unique_edges(key_edges)
+        merged_all_edges = Relation.unique_edges([*all_edges, *merged_key_edges])
         return merged_key_edges, merged_all_edges
 
     @staticmethod
-    def _unique_edges(edges: list[RelationEdge]) -> list[RelationEdge]:
+    def unique_edges(edges: list[RelationEdge]) -> list[RelationEdge]:
         unique_edges: list[RelationEdge] = []
         seen: set[Hashable] = set()
         for edge in edges:
@@ -377,72 +374,6 @@ class Relation(LLMBaseModel):
         return len(self.all_edges)
 
 
-class ClustersComponent(LLMBaseModel):
-    """A grouped component from cluster analysis - may contain multiple clusters."""
-
-    name: str = Field(
-        description="Short, descriptive name for this cluster group (e.g., 'Authentication', 'Data Pipeline', 'Request Handling')"
-    )
-    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(
-        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)"
-    )
-    existing_component_id: str | None = Field(
-        default=None,
-        description=(
-            "Incremental routing: the exact component_id of the existing component "
-            "this entry is routing clusters into (e.g. '1.3'). Set to null to create "
-            "a brand-new component. Identity is by ID, not name — leaving this null "
-            "while reusing an existing component's name forks a duplicate component. "
-            "Ignored by the full-analysis flow."
-        ),
-        json_schema_extra={"hidden": True},
-    )
-    parent_id: str | None = Field(
-        default=None,
-        description=(
-            "Incremental routing: when ``existing_component_id`` is null (brand-new "
-            "component), the existing component_id under which the new component "
-            "should attach (or null to attach at root). Ignored when "
-            "``existing_component_id`` is set, and ignored by the full-analysis flow."
-        ),
-        json_schema_extra={"hidden": True},
-    )
-    redetail_needed: bool = Field(
-        default=True,
-        description=(
-            "Incremental routing only: when routing clusters into an existing component "
-            "(``existing_component_id`` is set), set False if the cluster delta is "
-            "cosmetic (refactor, internal rename, small bug fix) and the component's "
-            "high-level purpose is unchanged — the existing description stays. Default "
-            "True forces a full redetail. Ignored for brand-new components (always "
-            "redetailed) and by the full-analysis flow."
-        ),
-        json_schema_extra={"hidden": True},
-    )
-
-    def llm_str(self):
-        ids_str = ", ".join(str(cid) for cid in self.cluster_ids)
-        return f"**{self.name}** (cluster_ids: [{ids_str}])\n   {self.description}"
-
-
-class ClusterAnalysis(LLMBaseModel):
-    """Analysis results containing grouped cluster components."""
-
-    cluster_components: list[ClustersComponent] = Field(
-        description="Grouped clusters into logical components. Multiple cluster IDs can be grouped together if they work as a cohesive unit."
-    )
-
-    def llm_str(self):
-        if not self.cluster_components:
-            return "No clusters analyzed."
-        title = "# Grouped Cluster Components\n"
-        body = "\n".join(cc.llm_str() for cc in self.cluster_components)
-        return title + body
-
-
 class Component(LLMBaseModel):
     """A software component with name, description, and key entities."""
 
@@ -459,7 +390,7 @@ class Component(LLMBaseModel):
         default_factory=list,
     )
 
-    source_cluster_ids: list[CodeBoardingClusterId] = Field(
+    source_cluster_ids: list[ComponentId] = Field(
         description="List of cluster IDs from CFG analysis that this component encompasses (populated deterministically from source_group_names).",
         default_factory=list,
         exclude=True,
@@ -512,6 +443,23 @@ class AnalysisInsights(LLMBaseModel):
     components: list[Component] = Field(description="List of the components identified in the project.")
     components_relations: list[Relation] = Field(description="List of relations among the components.")
 
+    def component_by_id(self, component_id: str) -> Component | None:
+        """Return the component with this stable ID."""
+        return next((component for component in self.components if component.component_id == component_id), None)
+
+    def component_by_name(self, name: str) -> Component | None:
+        """Return the first component with this displayed name."""
+        return next((component for component in self.components if component.name == name), None)
+
+    def node_owners(self) -> dict[str, str]:
+        """Map each indexed symbol to its owning component ID."""
+        return {
+            method.qualified_name: component.component_id
+            for component in self.components
+            for file_methods in component.file_methods
+            for method in file_methods.methods
+        }
+
     def llm_str(self):
         if not self.components:
             return "No abstract components found."

codeboarding-0.13.11/agents/component_ownership.py

@@ -0,0 +1,56 @@
+"""Derived component ownership data used to resolve relation endpoints."""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from dataclasses import dataclass
+
+from agents.agent_responses import AnalysisInsights, Component, SourceCodeReference
+
+
+def group_ids_by_name(components: list[Component], valid_group_ids: Collection[str]) -> dict[str, str]:
+    """Map component source-group names to their authoritative live group IDs."""
+    valid_ids = set(valid_group_ids)
+    return {
+        name: component.component_id
+        for component in components
+        if component.component_id in valid_ids
+        for name in component.source_group_names
+    }
+
+
+@dataclass(frozen=True)
+class ComponentOwnershipIndex:
+    """Resolve source references to their unique owning component."""
+
+    candidates_by_leaf: dict[str, list[tuple[str, str]]]
+
+    @classmethod
+    def from_analysis(cls, analysis: AnalysisInsights) -> ComponentOwnershipIndex:
+        candidates_by_leaf: dict[str, list[tuple[str, str]]] = {}
+        for component in analysis.components:
+            for file_methods in component.file_methods:
+                for method in file_methods.methods:
+                    candidates_by_leaf.setdefault(method.qualified_name.rsplit(".", 1)[-1], []).append(
+                        (method.qualified_name, component.component_id)
+                    )
+        return cls(candidates_by_leaf)
+
+    @classmethod
+    def from_node_owners(cls, node_owners: dict[str, str]) -> ComponentOwnershipIndex:
+        candidates_by_leaf: dict[str, list[tuple[str, str]]] = {}
+        for qualified_name, component_id in node_owners.items():
+            candidates_by_leaf.setdefault(qualified_name.rsplit(".", 1)[-1], []).append((qualified_name, component_id))
+        return cls(candidates_by_leaf)
+
+    def owner_of(self, reference: SourceCodeReference) -> str:
+        """Return the unique owner of a canonical or suffix-qualified reference."""
+        qualified_name = reference.qualified_name.replace(":", ".")
+        owners = {
+            component_id
+            for candidate, component_id in self.candidates_by_leaf.get(qualified_name.rsplit(".", 1)[-1], ())
+            if qualified_name == candidate.replace(":", ".")
+            or qualified_name.endswith(f".{candidate.replace(':', '.')}")
+            or candidate.replace(":", ".").endswith(f".{qualified_name}")
+        }
+        return owners.pop() if len(owners) == 1 else ""

{codeboarding-0.13.8 → codeboarding-0.13.11}/agents/content_hash.py

@@ -1,10 +1,8 @@
 """Content fingerprinting helpers — a leaf module with no analysis imports.
 
-Standalone (no heavy analysis imports) so clustering, the JSON layer, and the
-wrapper can all import it without an ``analysis_json`` <-> ``cluster_methods_mixin``
-cycle. ``splitlines()`` folds line-ending-only edits — accepted for change
-detection. Decode/encode both use ``surrogateescape`` so invalid UTF-8 bytes stay
-distinct (``replace`` would collapse them to U+FFFD and mask real changes).
+Standalone (no heavy analysis imports) so clustering, static enrichment, and the
+JSON layer can import it without cycles. ``splitlines()`` folds line-ending-only
+edits. Decode/encode use ``surrogateescape`` so invalid UTF-8 bytes stay distinct.
 """
 
 import hashlib