codeboarding 0.10.2__tar.gz → 0.10.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.10.2
+Version: 0.10.4
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -37,6 +37,7 @@ Requires-Dist: markdown>=3.8
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: markitdown>=0.1
 Requires-Dist: networkx>=3.4
+Requires-Dist: nodeenv>=1.10.0
 Requires-Dist: pathspec>=0.12
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2024.11

{codeboarding-0.10.2 → codeboarding-0.10.4}/README.md

@@ -16,6 +16,8 @@ Install the extension from Open VSX.
 [![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
 [![Go](https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white)](https://go.dev/)
 [![PHP](https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white)](https://www.php.net/)
+[![Rust](https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white)](https://www.rust-lang.org/)
+[![C#](https://custom-icon-badges.demolab.com/badge/C%23-512BD4.svg?style=flat-square&logo=cshrp&logoColor=white)](https://learn.microsoft.com/en-us/dotnet/csharp/)
 
 ## Few use cases:
 
@@ -91,7 +93,7 @@ codeboarding --local /path/to/repo
 
 Output is written to `/path/to/repo/.codeboarding/`.
 
-`python install.py` and `codeboarding-setup` download language server binaries to `~/.codeboarding/servers/`, shared across projects. `npm` is required for Python, TypeScript, JavaScript, and PHP language servers; if it is missing, setup can install it via `nodeenv`.
+`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
 
@@ -141,7 +143,7 @@ python main.py https://github.com/pytorch/pytorch
 
 ## Supported stack
 
-- Languages: Python, TypeScript, JavaScript, Java, Go, PHP.
+- Languages: Python, TypeScript, JavaScript, Java, Go, PHP, Rust.
 - LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, and more.
 
 ## Examples

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

@@ -70,8 +70,20 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
         programming_langs = self.static_analysis.get_languages()
 
-        # Build cluster string using the pre-computed cluster results
-        cluster_str = self._build_cluster_string(programming_langs, cluster_results)
+        # 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(
+                project_name=self.project_name,
+                cfg_clusters="",
+                meta_context=meta_context_str,
+                project_type=project_type,
+            )
+        )
+        cluster_str = self._build_cluster_string(
+            programming_langs, cluster_results, prompt_overhead_chars=overhead_chars
+        )
 
         prompt = self.prompts["group_clusters"].format(
             project_name=self.project_name,

{codeboarding-0.10.2 → codeboarding-0.10.4}/agents/agent.py

@@ -160,6 +160,11 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
                     raise
 
             except Exception as e:
+                # HTTP 404 (e.g. retired model ID) is permanent — retrying won't help.
+                if getattr(e, "status_code", None) == 404:
+                    logger.error(f"Permanent HTTP 404 — not retrying: {type(e).__name__}: {e}")
+                    raise
+
                 # Other errors (network, parsing, etc.) get standard exponential backoff
                 if attempt < max_retries - 1:
                     delay = min(10 * (2**attempt), 120)

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

@@ -1,12 +1,13 @@
+from __future__ import annotations
+
 import abc
 import logging
 from abc import abstractmethod
+from pathlib import PurePosixPath
 from typing import get_origin, Optional
 
 from pydantic import BaseModel, Field
 
-from agents.change_status import ChangeStatus
-
 logger = logging.getLogger(__name__)
 
 
@@ -141,10 +142,6 @@ class MethodEntry(BaseModel):
     start_line: int = Field(description="Starting line number in the file.")
     end_line: int = Field(description="Ending line number in the file.")
     node_type: str = Field(description="Node type name matching NodeType enum (e.g. METHOD, FUNCTION, CLASS).")
-    status: ChangeStatus = Field(
-        default=ChangeStatus.UNCHANGED,
-        description="Diff status of this method: added, modified, deleted, or unchanged.",
-    )
 
     def __hash__(self) -> int:
         return hash(self.qualified_name)
@@ -155,13 +152,12 @@ class MethodEntry(BaseModel):
         return self.qualified_name == other.qualified_name
 
     @classmethod
-    def from_method_change(cls, method_change, *, status_override: ChangeStatus | None = None) -> "MethodEntry":
+    def from_method_change(cls, method_change) -> MethodEntry:
         return cls(
             qualified_name=method_change.qualified_name,
             start_line=method_change.start_line,
             end_line=method_change.end_line,
             node_type=method_change.node_type,
-            status=status_override or method_change.change_type,
         )
 
 
@@ -169,10 +165,6 @@ class FileMethodGroup(BaseModel):
     """All methods/functions belonging to a component within a single file."""
 
     file_path: str = Field(description="Relative path to the source file.")
-    file_status: ChangeStatus = Field(
-        default=ChangeStatus.UNCHANGED,
-        description="Diff status of this file: added, modified, deleted, renamed, or unchanged.",
-    )
     methods: list[MethodEntry] = Field(
         default_factory=list,
         description="Methods and functions in this file that belong to the component, sorted by start_line.",
@@ -182,10 +174,6 @@ class FileMethodGroup(BaseModel):
 class FileEntry(BaseModel):
     """Single source of truth for methods in one file."""
 
-    file_status: ChangeStatus = Field(
-        default=ChangeStatus.UNCHANGED,
-        description="Diff status of this file: added, modified, deleted, renamed, or unchanged.",
-    )
     methods: list[MethodEntry] = Field(
         default_factory=list,
         description="Methods and functions in this file, sorted by start line.",
@@ -261,6 +249,10 @@ class AnalysisInsights(LLMBaseModel):
         relations = "\n".join(cr.llm_str() for cr in self.components_relations)
         return title + body + relations
 
+    def file_to_component(self) -> dict[str, str]:
+        """Build file path -> component_id mapping from root components."""
+        return {str(PurePosixPath(fg.file_path)): c.component_id for c in self.components for fg in c.file_methods}
+
 
 def assign_component_ids(analysis: AnalysisInsights, parent_id: str = "") -> None:
     """Assign hierarchical component IDs based on sibling index.

codeboarding-0.10.4/agents/cluster_budget.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+
+from agents.constants import ModelCapabilities
+
+OUTPUT_HEADROOM_TOKENS = 8_000
+CONTEXT_MARGIN = 0.9
+
+
+@dataclass(frozen=True)
+class ClusterPromptBudget:
+    """Character budget for the full rendered ``cfg_clusters`` prompt slot."""
+
+    input_tokens: int
+    output_headroom_tokens: int = OUTPUT_HEADROOM_TOKENS
+    chars_per_token: float = ModelCapabilities.CHARS_PER_TOKEN
+    margin: float = CONTEXT_MARGIN
+
+    def available_chars(self, prompt_overhead_chars: int) -> int:
+        prompt_overhead_tokens = prompt_overhead_chars / self.chars_per_token
+        available_tokens = (self.input_tokens - self.output_headroom_tokens - prompt_overhead_tokens) * self.margin
+        return int(available_tokens * self.chars_per_token)

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

@@ -1,7 +1,9 @@
 import logging
 import os
 from collections import defaultdict
+from dataclasses import dataclass
 from pathlib import Path
+from typing import NoReturn
 
 import networkx as nx
 
@@ -13,8 +15,11 @@ from agents.agent_responses import (
     FileMethodGroup,
     MethodEntry,
 )
+from agents.cluster_budget import ClusterPromptBudget
+from agents.llm_config import get_current_agent_context_window
 from constants import MIN_CLUSTERS_THRESHOLD
 from static_analyzer.analysis_result import StaticAnalysisResults
+from static_analyzer.cfg_skip_planner import ContextBudgetExceededError, plan_skip_set
 from static_analyzer.cluster_helpers import (
     MAX_LLM_CLUSTERS,
     enforce_cross_language_budget,
@@ -34,6 +39,13 @@ from static_analyzer.node import Node
 logger = logging.getLogger(__name__)
 
 
+@dataclass(frozen=True)
+class _RenderedClusterString:
+    text: str
+    by_language: dict[str, str]
+    cluster_ids: set[int]
+
+
 class ClusterMethodsMixin:
     """
     Mixin providing shared cluster-related functionality for agents.
@@ -61,6 +73,7 @@ class ClusterMethodsMixin:
         programming_langs: list[str],
         cluster_results: dict[str, ClusterResult],
         cluster_ids: set[int] | None = None,
+        prompt_overhead_chars: int = 0,
     ) -> str:
         """
         Build a cluster string for LLM consumption using pre-computed cluster results.
@@ -69,29 +82,59 @@ class ClusterMethodsMixin:
             programming_langs: List of languages to include
             cluster_results: Pre-computed cluster results mapping language -> ClusterResult
             cluster_ids: Optional set of cluster IDs to filter by
+            prompt_overhead_chars: Characters used by everything else in the
+                prompt (system message + rendered template with an empty
+                ``cfg_clusters`` slot). The skip planner subtracts this from
+                the model's input window before computing the char budget for
+                the cluster string.
 
         Returns:
             Formatted cluster string with headers per language
         """
-        cluster_lines = []
+        rendered = self._render_cluster_string(programming_langs, cluster_results, cluster_ids, {})
+        if cluster_ids:
+            return rendered.text
+
+        char_budget = self._cluster_prompt_budget(prompt_overhead_chars)
+        if len(rendered.text) <= char_budget:
+            return rendered.text
+
+        per_lang_skip = self._plan_skip_sets(programming_langs, cluster_results, prompt_overhead_chars)
+        rendered_with_skips = self._render_cluster_string(
+            programming_langs, cluster_results, cluster_ids, per_lang_skip
+        )
+        if len(rendered_with_skips.text) > char_budget:
+            self._raise_cluster_budget_error(char_budget, rendered_with_skips, per_lang_skip)
+
+        return rendered_with_skips.text
+
+    def _render_cluster_string(
+        self,
+        programming_langs: list[str],
+        cluster_results: dict[str, ClusterResult],
+        cluster_ids: set[int] | None,
+        skip_sets: dict[str, set[str]],
+    ) -> _RenderedClusterString:
+        cluster_lines: list[str] = []
+        by_language: dict[str, str] = {}
         all_cluster_ids: set[int] = set()
 
         for lang in programming_langs:
             cfg = self.static_analysis.get_cfg(lang)
-            # Get cluster result for this language
             cluster_result = cluster_results.get(lang)
-            cluster_str = cfg.to_cluster_string(cluster_ids, cluster_result)
+            cluster_str = cfg.to_cluster_string(
+                cluster_ids or set(), cluster_result, skip_nodes=skip_sets.get(lang, set())
+            )
 
             if cluster_str.strip() and cluster_str not in ("empty", "none", "No clusters found."):
                 header = "Component CFG" if cluster_ids else "Clusters"
-                cluster_lines.append(f"\n## {lang.capitalize()} - {header}\n")
-                cluster_lines.append(cluster_str)
-                cluster_lines.append("\n")
+                lang_text = f"\n## {lang.capitalize()} - {header}\n{cluster_str}\n"
+                cluster_lines.append(lang_text)
+                by_language[lang] = lang_text
                 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(
@@ -99,7 +142,117 @@ class ClusterMethodsMixin:
                 f"Every one of these IDs: {sorted_cluster_ids} must appear in exactly one group."
             )
 
-        return "".join(cluster_lines)
+        return _RenderedClusterString(text="".join(cluster_lines), by_language=by_language, cluster_ids=all_cluster_ids)
+
+    def _plan_skip_sets(
+        self,
+        programming_langs: list[str],
+        cluster_results: dict[str, ClusterResult],
+        prompt_overhead_chars: int,
+    ) -> dict[str, set[str]]:
+        """Compute per-language skip sets so the final combined cluster string fits."""
+        char_budget = self._cluster_prompt_budget(prompt_overhead_chars)
+        if char_budget <= 0:
+            ctx = get_current_agent_context_window()
+            msg = (
+                f"Prompt overhead ({prompt_overhead_chars} chars) consumes the entire agent input "
+                f"window ({ctx.input_tokens} tokens); no room for cluster renderings."
+            )
+            logger.error("[CFG skip planner] %s", msg)
+            raise ContextBudgetExceededError(msg)
+
+        langs_with_clusters = [l for l in programming_langs if cluster_results.get(l)]
+        if not langs_with_clusters:
+            return {}
+
+        skip_sets: dict[str, set[str]] = {}
+        rendered = self._render_cluster_string(programming_langs, cluster_results, None, skip_sets)
+        if len(rendered.text) <= char_budget:
+            return skip_sets
+
+        max_iterations = max(1, len(langs_with_clusters) * 5)
+        for _ in range(max_iterations):
+            deficit = len(rendered.text) - char_budget
+            ordered_langs = sorted(
+                langs_with_clusters,
+                key=lambda lang: len(rendered.by_language.get(lang, "")),
+                reverse=True,
+            )
+            progressed = False
+
+            for lang in ordered_langs:
+                lang_text = rendered.by_language.get(lang, "")
+                current_len = len(lang_text)
+                if current_len == 0:
+                    continue
+
+                for target in self._language_budget_targets(current_len, deficit):
+                    try:
+                        skip = plan_skip_set(self.static_analysis.get_cfg(lang), cluster_results[lang], target)
+                    except ContextBudgetExceededError:
+                        continue
+
+                    if skip == skip_sets.get(lang, set()):
+                        continue
+
+                    trial_skip_sets = dict(skip_sets)
+                    if skip:
+                        trial_skip_sets[lang] = skip
+                    else:
+                        trial_skip_sets.pop(lang, None)
+
+                    trial_rendered = self._render_cluster_string(
+                        programming_langs, cluster_results, None, trial_skip_sets
+                    )
+                    if len(trial_rendered.text) >= len(rendered.text):
+                        continue
+
+                    skip_sets = trial_skip_sets
+                    rendered = trial_rendered
+                    progressed = True
+                    break
+
+                if progressed:
+                    break
+
+            if len(rendered.text) <= char_budget:
+                return skip_sets
+            if not progressed:
+                break
+
+        self._raise_cluster_budget_error(char_budget, rendered, skip_sets)
+
+    @staticmethod
+    def _language_budget_targets(current_len: int, deficit: int) -> list[int]:
+        exact_target = max(0, current_len - deficit)
+        targets = {
+            exact_target,
+            int(current_len * 0.9),
+            int(current_len * 0.75),
+            int(current_len * 0.5),
+            0,
+        }
+        return sorted((target for target in targets if target < current_len), reverse=True)
+
+    @staticmethod
+    def _raise_cluster_budget_error(
+        char_budget: int,
+        rendered: _RenderedClusterString,
+        skip_sets: dict[str, set[str]],
+    ) -> NoReturn:
+        per_lang_sizes = {lang: len(text) for lang, text in rendered.by_language.items()}
+        skipped_counts = {lang: len(skip) for lang, skip in skip_sets.items() if skip}
+        msg = (
+            f"Cluster render {len(rendered.text)} chars exceeds budget {char_budget}. "
+            f"Per-language sizes: {per_lang_sizes}; skipped nodes: {skipped_counts}."
+        )
+        logger.error("[CFG skip planner] %s", msg)
+        raise ContextBudgetExceededError(msg)
+
+    @staticmethod
+    def _cluster_prompt_budget(prompt_overhead_chars: int) -> int:
+        ctx = get_current_agent_context_window()
+        return ClusterPromptBudget(input_tokens=ctx.input_tokens).available_chars(prompt_overhead_chars)
 
     def _ensure_unique_key_entities(self, analysis: AnalysisInsights):
         """
@@ -247,11 +400,11 @@ class ClusterMethodsMixin:
             logger.warning(f"Component {component.name} has no assigned files")
             return "No assigned files found for this component.", {}, {}
 
-        # Convert files to absolute paths for comparison
-        assigned_file_set = set()
-        for f in component_files:
-            abs_path = os.path.join(self.repo_dir, f) if not os.path.isabs(f) else f
-            assigned_file_set.add(abs_path)
+        # Collect qualified names for method-level filtering
+        assigned_qnames: set[str] = set()
+        for group in component.file_methods:
+            for method in group.methods:
+                assigned_qnames.add(method.qualified_name)
 
         cluster_results: dict[str, ClusterResult] = {}
         subgraph_cfgs: dict[str, CallGraph] = {}
@@ -259,8 +412,8 @@ class ClusterMethodsMixin:
         for lang in self.static_analysis.get_languages():
             cfg = self.static_analysis.get_cfg(lang)
 
-            # Use strict filtering logic
-            sub_cfg = cfg.filter_by_files(assigned_file_set)
+            # Filter by exact method set to prevent scope leakage
+            sub_cfg = cfg.filter_by_nodes(assigned_qnames)
 
             if sub_cfg.nodes:
                 subgraph_cfgs[lang] = sub_cfg
@@ -299,7 +452,7 @@ class ClusterMethodsMixin:
         result = "".join(result_parts)
 
         if not result.strip():
-            logger.warning(f"No CFG found for component {component.name} with {len(component_files)} files")
+            logger.warning(f"No CFG found for component {component.name} with {len(assigned_qnames)} methods")
             return "No relevant CFG clusters found for this component.", cluster_results, subgraph_cfgs
 
         return result, cluster_results, subgraph_cfgs
@@ -556,7 +709,7 @@ class ClusterMethodsMixin:
             for fmg in component.file_methods:
                 entry = files.get(fmg.file_path)
                 if entry is None:
-                    entry = FileEntry(file_status=fmg.file_status, methods=[])
+                    entry = FileEntry(methods=[])
                     files[fmg.file_path] = entry
 
                 methods_by_qname = {m.qualified_name: m for m in entry.methods}

codeboarding-0.10.4/agents/constants.py

@@ -0,0 +1,38 @@
+"""Constants for the agents module."""
+
+
+class LLMDefaults:
+    DEFAULT_AGENT_TEMPERATURE = 0
+    DEFAULT_PARSING_TEMPERATURE = 0
+    AWS_MAX_TOKENS = 4096
+
+
+class FileStructureConfig:
+    MAX_LINES = 500
+    DEFAULT_MAX_DEPTH = 10
+    FALLBACK_MAX_LINES = 50000
+
+
+class ModelCapabilities:
+    FALLBACK_INPUT = 256_000
+    FALLBACK_OUTPUT = 64_000
+    CACHE_TTL_SECONDS = 24 * 3600
+    CHARS_PER_TOKEN = 3.5  # community consensus conversion is around 3 or 4 chars/token.
+
+    SOURCES = {
+        "litellm": "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
+        "modelsdev": "https://models.dev/api.json",
+        "openrouter": "https://openrouter.ai/api/v1/models",
+    }
+
+    # models.dev uses slugs that diverge from our internal provider names.
+    MODELSDEV_SLUG = {
+        "aws": "amazon-bedrock",
+        "kimi": "moonshotai",
+        "glm": "zai",
+    }
+
+    OPENROUTER_PREFIX = {
+        "kimi": "moonshotai",
+        "glm": "z-ai",
+    }

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

@@ -84,8 +84,18 @@ class DetailsAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
         programming_langs = self.static_analysis.get_languages()
 
-        # Build cluster string using the pre-computed cluster results (same as AbstractionAgent)
-        cluster_str = self._build_cluster_string(programming_langs, subgraph_cluster_results)
+        overhead_chars = len(str(self.system_message.content)) + len(
+            self.prompts["group_clusters"].format(
+                project_name=self.project_name,
+                cfg_clusters="",
+                component=component.llm_str(),
+                meta_context=meta_context_str,
+                project_type=project_type,
+            )
+        )
+        cluster_str = self._build_cluster_string(
+            programming_langs, subgraph_cluster_results, prompt_overhead_chars=overhead_chars
+        )
 
         prompt = self.prompts["group_clusters"].format(
             project_name=self.project_name,