codeboarding 0.15.3__tar.gz → 0.15.5__tar.gz

{codeboarding-0.15.3/codeboarding.egg-info → codeboarding-0.15.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.3
+Version: 0.15.5
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -34,6 +34,7 @@ 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: libclang==18.1.1
 Requires-Dist: markdown>=3.8
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: markitdown>=0.1
@@ -49,6 +50,8 @@ Requires-Dist: rich>=12.6
 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-cpp==0.23.4
+Requires-Dist: tree-sitter-cuda==0.21.2
 Requires-Dist: tree-sitter-go==0.25.0
 Requires-Dist: tree-sitter-java==0.23.5
 Requires-Dist: tree-sitter-javascript==0.25.0

{codeboarding-0.15.3 → codeboarding-0.15.5}/README.md

@@ -235,8 +235,9 @@ for the actual depth. Existing baseline loading behavior is unchanged: prefer
 > `.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. Static-analysis caches are versioned but not migrated; after a cache-version
-> upgrade, run a full analysis once to reindex.
+> doing a full run. Static-analysis caches are versioned but not migrated: after a cache-version
+> upgrade, `incremental` logs a warning and runs one full analysis at the baseline's depth, which
+> counts against your LLM provider like any other full run.
 
 ## Where to use it
 
@@ -247,9 +248,10 @@ for the actual depth. Existing baseline loading behavior is unchanged: prefer
 
 ## Supported stack
 
-- Languages: Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, C#.
+- Languages: Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, C#, C++ and CUDA (preview).
   - Java needs a JDK (21 recommended).
-  - Kotlin is analysed with JetBrains' [kotlin-lsp](https://github.com/Kotlin/kotlin-lsp) (about 360 MB with its own Java runtime, under the [JetBrains Free Plugin License](https://github.com/Kotlin/kotlin-lsp/blob/main/kotlin-vscode/LICENSE.txt)) and needs glibc 2.34 or newer on Linux. Kotlin calls into Java are not drawn yet.
+  - Kotlin is analysed with JetBrains' [kotlin-lsp](https://github.com/Kotlin/kotlin-lsp) (about 360 MB with its own Java runtime, under the [JetBrains Free Plugin License](https://github.com/Kotlin/kotlin-lsp/blob/main/kotlin-vscode/LICENSE.txt)) and needs glibc 2.34 or newer on Linux. JetBrains' builds expire after about 30 days, so a run that needs Kotlin reads the current build number and checksums from this repository, and keeps the build it has when it cannot. Kotlin calls into Java are not drawn yet.
+  - C++ and CUDA are analysed with [clangd](https://clangd.llvm.org/), bundled on Linux x86-64, macOS and Windows x64; other platforms need clangd 20 or newer on `PATH`. Provide `compile_commands.json`, `compile_flags.txt` or `.clangd` for full coverage, since CodeBoarding does not build the project. Incremental updates, and so PR reviews, can still miss or keep stale relations for out-of-line class members and header templates.
 - LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, OrcaRouter, Requesty, Opper, LiteLLM proxy, and more.
 
 ## Examples

{codeboarding-0.15.3 → codeboarding-0.15.5}/agents/prompts/shared.py

@@ -41,7 +41,11 @@ components this scope sits inside, and a child named after its parent overwrites
 may inspect a specific in-scope file and `getMethodCalls` may inspect one exact in-scope symbol in one direction.
 Do not inventory the scope, browse every file, or repeat a tool call. A runtime budget limits all tools to six calls.
 
-Name each editable group for one responsibility using the codebase's own vocabulary, add a concise description,
+Name each editable group for one responsibility in natural English: two to five words separated by spaces that
+tell a reader what the group does, such as "License Validation API" or "Order Checkout Flow". A directory, file,
+package, or symbol name is not a component name: never answer with snake_case, kebab-case, camelCase, or
+PascalCase identifiers, and do not re-case one either ("billing_jobs" and "Billing Jobs" both just repeat
+the directory). Add a concise description,
 and select only clearly evidenced key entities. Label known directed connections by their architectural meaning.
 You may add a missing non-static relation such as REST, queue, plugin, registry, file, or configuration wiring only
 when exact source symbols on both component sides and concrete textual evidence support it. Names alone are not
@@ -57,7 +61,7 @@ Call `ScopeAnalysisResult` with exactly this shape:
   "components": [
     {{
       "group_id": "an exact supplied group_id",
-      "name": "one responsibility",
+      "name": "natural-language name for one responsibility",
       "description": "one concise sentence",
       "key_entities": [{{"qualified_name": "exact in-scope symbol"}}]
     }}
@@ -84,6 +88,12 @@ true, repeat its existing name exactly. Relations may be returned for any pair t
 relations between two unchanged groups alone. Include one component entry per editable group. Do not invent group
 IDs, file membership, source symbols, or calls."""
 
+SCOPE_NAME_RETRY_MESSAGE = """These component names are identifiers or directory and file names, not natural text:
+{names}
+
+Call `ScopeAnalysisResult` again with the same content, giving each of these groups a natural-language name of
+two to five words separated by spaces that says what it does. Do not call any other tool."""
+
 STRICT_TREE_PLAN_SYSTEM_SUFFIX = """
 
 Follow every constraint literally. Do not explain your reasoning or emit markdown."""

{codeboarding-0.15.3 → codeboarding-0.15.5}/agents/scope_analysis_agent.py

@@ -30,12 +30,14 @@ from infra.monitoring.callbacks import MONITORING_CALLBACK
 from agents.llm_errors import ScopeContextTooLargeError, raise_if_auth_error
 from agents.llm_renderers import render_scope_context, scope_file_paths, scope_method_names
 from agents.prompts import get_scope_analysis_prompts
+from agents.prompts.shared import SCOPE_NAME_RETRY_MESSAGE
 from agents.retry import LLM_MAX_ATTEMPTS, classify_llm_error, with_retries
 from agents.tools import MethodCallsTool, ReadFileTool
 from agents.tools.base import RepoContext
 from infra.monitoring.mixin import MonitoringMixin
 from static_analyzer.analysis_result import StaticAnalysisResults
 from static_analyzer.clustering import ClusterScopeResult
+from static_analyzer.clustering.names.tokens import identifier_path_names, is_natural_name
 
 logger = logging.getLogger(__name__)
 
@@ -249,19 +251,50 @@ class ScopeAnalysisAgent(MonitoringMixin):
             enclosing_names,
             max_tokens=max(0, input_budget.max_tokens - prompt_tokens),
         )
-        try:
-            response = agent.invoke(
-                {"messages": [HumanMessage(content=self.analysis_prompt.format(scope_context=scope_context))]},
-                config={
-                    "callbacks": [MONITORING_CALLBACK, self.agent_monitoring_callback],
-                    "recursion_limit": SCOPE_RECURSION_LIMIT,
-                },
-            )
-        except Exception as error:
-            raise_if_auth_error(error)
-            raise
+
+        def invoke(messages: list) -> dict:
+            try:
+                return agent.invoke(
+                    {"messages": messages},
+                    config={
+                        "callbacks": [MONITORING_CALLBACK, self.agent_monitoring_callback],
+                        "recursion_limit": SCOPE_RECURSION_LIMIT,
+                    },
+                )
+            except Exception as error:
+                raise_if_auth_error(error)
+                raise
+
+        response = invoke([HumanMessage(content=self.analysis_prompt.format(scope_context=scope_context))])
         result = response.get("structured_response")
         if not isinstance(result, ScopeAnalysisResult):
             logger.warning("Scope %s ended without a structured answer", scope.scope_id)
             return None
+
+        # Why a second turn rather than a stricter prompt alone: the same model and prompt name a
+        # scope well on one run and answer with its directory names on the next.
+        path_names = identifier_path_names(context.scope_files)
+        unnatural = {
+            component.group_id: component.name
+            for component in result.components
+            if component.group_id in editable_group_ids
+            and component.group_id not in locked_name_ids
+            and not is_natural_name(component.name, path_names)
+        }
+        if not unnatural:
+            return result
+        logger.info("Scope %s: asking again for natural names instead of %s", scope.scope_id, unnatural)
+        names = "\n".join(f"- {group_id}: {name}" for group_id, name in unnatural.items())
+        answer = invoke(
+            [*response["messages"], HumanMessage(content=SCOPE_NAME_RETRY_MESSAGE.format(names=names))]
+        ).get("structured_response")
+        renamed = (
+            {component.group_id: component.name for component in answer.components}
+            if isinstance(answer, ScopeAnalysisResult)
+            else {}
+        )
+        for component in result.components:
+            if component.group_id in unnatural:
+                name = renamed.get(component.group_id, "")
+                component.name = name if is_natural_name(name, path_names) else ""
         return result

{codeboarding-0.15.3 → codeboarding-0.15.5/codeboarding.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.3
+Version: 0.15.5
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -34,6 +34,7 @@ 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: libclang==18.1.1
 Requires-Dist: markdown>=3.8
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: markitdown>=0.1
@@ -49,6 +50,8 @@ Requires-Dist: rich>=12.6
 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-cpp==0.23.4
+Requires-Dist: tree-sitter-cuda==0.21.2
 Requires-Dist: tree-sitter-go==0.25.0
 Requires-Dist: tree-sitter-java==0.23.5
 Requires-Dist: tree-sitter-javascript==0.25.0

{codeboarding-0.15.3 → codeboarding-0.15.5}/codeboarding.egg-info/SOURCES.txt

@@ -111,6 +111,7 @@ infra/tool_registry/__init__.py
 infra/tool_registry/grammars.py
 infra/tool_registry/installers.py
 infra/tool_registry/java.py
+infra/tool_registry/kotlin-server-1.json
 infra/tool_registry/manifest.py
 infra/tool_registry/paths.py
 infra/tool_registry/registry.py
@@ -159,6 +160,7 @@ static_analyzer/clustering/names/spec.py
 static_analyzer/clustering/names/tokens.py
 static_analyzer/engine/__init__.py
 static_analyzer/engine/call_graph_builder.py
+static_analyzer/engine/cpp_templates.py
 static_analyzer/engine/edge_build_context.py
 static_analyzer/engine/edge_builder.py
 static_analyzer/engine/hierarchy_builder.py
@@ -175,6 +177,7 @@ static_analyzer/engine/source_inspector.py
 static_analyzer/engine/symbol_table.py
 static_analyzer/engine/utils.py
 static_analyzer/engine/adapters/__init__.py
+static_analyzer/engine/adapters/cpp_adapter.py
 static_analyzer/engine/adapters/csharp_adapter.py
 static_analyzer/engine/adapters/go_adapter.py
 static_analyzer/engine/adapters/java_adapter.py

{codeboarding-0.15.3 → codeboarding-0.15.5}/codeboarding.egg-info/requires.txt

@@ -17,6 +17,7 @@ langchain-google-genai>=3.1
 langchain-ollama>=1.0
 langchain-openai>=1.1
 langgraph>=1.0
+libclang==18.1.1
 markdown>=3.8
 markdown-it-py>=3.0
 markitdown>=0.1
@@ -32,6 +33,8 @@ rich>=12.6
 tqdm>=4.67
 tree-sitter==0.25.2
 tree-sitter-c-sharp==0.23.5
+tree-sitter-cpp==0.23.4
+tree-sitter-cuda==0.21.2
 tree-sitter-go==0.25.0
 tree-sitter-java==0.23.5
 tree-sitter-javascript==0.25.0

{codeboarding-0.15.3 → codeboarding-0.15.5}/codeboarding_cli/commands/incremental_analysis.py

@@ -9,7 +9,7 @@ from agents.llm_errors import LLMAuthError, LLMQuotaError
 from diagram_analysis.exceptions import ScopeSemanticsError
 from codeboarding_cli.bootstrap import bootstrap_environment, resolve_local_run_paths
 from codeboarding_cli.view_instructions import print_view_instructions
-from codeboarding_workflows.analysis import BaselineUnavailableError, run_incremental
+from codeboarding_workflows.analysis import BaselineUnavailableError, EngineChangedError, run_full, run_incremental
 from diagram_analysis import RunContext
 from diagram_analysis.run_mode import RunMode
 from infra.utils import monitoring_enabled
@@ -48,12 +48,21 @@ def run_from_args(args: argparse.Namespace, parser: argparse.ArgumentParser) ->
         return
 
     run_context = RunContext.resolve(project_name=run_paths.project_name)
+    should_monitor = args.enable_monitoring or monitoring_enabled()
+    mode = RunMode.INCREMENTAL
 
     try:
-        analysis_path = run_incremental(
+        analysis_path = run_incremental(run_paths, run_context, monitoring_enabled=should_monitor)
+    except EngineChangedError as exc:
+        # Why: an engine release reaches CI unasked, and nobody is there to answer a prompt.
+        logger.warning("%s Running a full analysis instead.", exc)
+        mode = RunMode.FULL
+        analysis_path = run_full(
             run_paths,
             run_context,
-            monitoring_enabled=args.enable_monitoring or monitoring_enabled(),
+            depth_cap=exc.depth_cap,
+            monitoring_enabled=should_monitor,
+            force_full=True,
         )
     except BaselineUnavailableError as exc:
         # Expected: no baseline, or diff failed against the requested base ref.
@@ -61,22 +70,24 @@ def run_from_args(args: argparse.Namespace, parser: argparse.ArgumentParser) ->
         # to prompt for a full run; no stack trace needed.
         logger.info("Incremental unavailable: %s", exc)
         _emit_error(str(exc))
+        return
     except (LLMAuthError, LLMQuotaError, ScopeSemanticsError):
         # A full run would fail the same way, so don't ask for one.
         raise
     except Exception as exc:
         logger.exception("Incremental analysis failed")
         _emit_error(str(exc))
-    else:
-        _emit(
-            {
-                "mode": RunMode.INCREMENTAL,
-                "requiresFullAnalysis": False,
-                "analysis_path": str(analysis_path),
-            }
-        )
-        # Human-facing hint (logs to stderr, so the stdout JSON contract stays clean).
-        print_view_instructions(analysis_path)
+        return
+
+    _emit(
+        {
+            "mode": mode,
+            "requiresFullAnalysis": False,
+            "analysis_path": str(analysis_path),
+        }
+    )
+    # Human-facing hint (logs to stderr, so the stdout JSON contract stays clean).
+    print_view_instructions(analysis_path)
 
 
 def _emit_error(message: str) -> None:

{codeboarding-0.15.3 → codeboarding-0.15.5}/codeboarding_workflows/analysis.py

@@ -25,12 +25,24 @@ from diagram_analysis.io_utils import (
 )
 from diagram_analysis.run_context import DEFAULT_DEPTH_CAP, RunContext, RunPaths
 from infra.repo_utils.change_detector import ChangeSet
-from codeboarding_workflows.fingerprint_diff import BaselineUnavailableError, detect_changes_from_fingerprint
+from codeboarding_workflows.fingerprint_diff import (
+    BaselineUnavailableError,
+    EngineChangedError,
+    detect_changes_from_fingerprint,
+)
 from infra.monitoring.telemetry.events import track_analysis
+from static_analyzer.analysis_cache import StaticAnalysisCache
 
 logger = logging.getLogger(__name__)
 
-__all__ = ["BaselineUnavailableError", "run_full", "run_partial", "run_incremental", "run_incremental_workflow"]
+__all__ = [
+    "BaselineUnavailableError",
+    "EngineChangedError",
+    "run_full",
+    "run_partial",
+    "run_incremental",
+    "run_incremental_workflow",
+]
 
 
 def build_generator(
@@ -196,7 +208,8 @@ def run_incremental(
     passes a changed-file set or git refs — the CLI and the wrapper both just say
     "update this directory". The source-tree hash doubles as the warm-start tag.
 
-    Raises ``BaselineUnavailableError`` when no baseline analysis exists — callers
+    Raises ``BaselineUnavailableError`` when no baseline analysis exists, and its
+    subclass ``EngineChangedError`` when another engine version wrote it — callers
     should surface a "run full analysis" prompt rather than silently degrading to
     an unscoped run.
     """
@@ -208,6 +221,10 @@ def run_incremental(
         )
     depth_cap = int(metadata.get("depth_cap", metadata.get("depth_level", DEFAULT_DEPTH_CAP)))
 
+    # Why here: the analyzer refuses this pkl too, but only after servers started and a failed run was reported.
+    if StaticAnalysisCache(run_paths.output_dir, run_paths.repo_path).from_another_engine():
+        raise EngineChangedError(run_paths.output_dir, depth_cap)
+
     changes = detect_changes_from_fingerprint(run_paths.repo_path, run_paths.output_dir)
     logger.info(
         f"Running INCREMENTAL analysis workflow for project '{run_paths.project_name}' "

{codeboarding-0.15.3 → codeboarding-0.15.5}/codeboarding_workflows/fingerprint_diff.py

@@ -11,6 +11,7 @@ from pathlib import Path
 
 from agents.content_hash import hash_repo_source_files
 from diagram_analysis.io_utils import read_fingerprint
+from infra.constants import STATIC_ANALYSIS_PKL
 from infra.repo_utils.change_detector import ChangeSet
 
 logger = logging.getLogger(__name__)
@@ -31,6 +32,20 @@ class BaselineUnavailableError(RuntimeError):
     """
 
 
+class EngineChangedError(BaselineUnavailableError):
+    """Raised when the baseline's static analysis came from an engine version this build cannot read.
+
+    Carries the baseline's depth cap, so a caller that recovers rebuilds at the same depth.
+    """
+
+    def __init__(self, output_dir: Path, depth_cap: int):
+        super().__init__(
+            f"{output_dir / STATIC_ANALYSIS_PKL} was written by a different engine version "
+            "and cannot be reused for an incremental run."
+        )
+        self.depth_cap = depth_cap
+
+
 def diff_file_maps(old: FileHashMap, new: FileHashMap) -> tuple[list[str], list[str], list[str]]:
     """Return ``(added, modified, deleted)`` repo-relative paths between two maps.
 

{codeboarding-0.15.3 → codeboarding-0.15.5}/diagram_analysis/analysis_json.py

@@ -528,7 +528,10 @@ def parse_unified_analysis(
     root_analysis.files = {path: FileEntry().merge_from(entry) for path, entry in files_index.items()}
     _hydrate_component_methods_from_refs(root_analysis, methods_index)
     for sub in sub_analyses.values():
-        sub.files = {path: FileEntry().merge_from(entry) for path, entry in files_index.items()}
+        # Same shape a live scope gets from ``build_files_index``: only the files its components
+        # own. The root carries the whole index, so a save loses nothing.
+        owned = {group.file_path for component in sub.components for group in component.file_methods}
+        sub.files = {path: FileEntry().merge_from(entry) for path, entry in files_index.items() if path in owned}
         _hydrate_component_methods_from_refs(sub, methods_index)
 
     return root_analysis, sub_analyses

{codeboarding-0.15.3 → codeboarding-0.15.5}/diagram_analysis/diagram_generator.py

@@ -84,6 +84,7 @@ from static_analyzer.clustering import (
 from static_analyzer.clustering.exceptions import IncrementalCacheMissingError, PlannerUnavailableError
 from static_analyzer.clustering.names import AffinityGrouper, Grouper, KinshipGrouper, TreeSpec
 from static_analyzer.clustering.names.spec import SPEC_VERSION
+from static_analyzer.clustering.names.tokens import is_natural_name
 from static_analyzer.clustering.service import ClusteringService, hierarchy_differs
 from agents.tree_planner_agent import TreePlannerAgent
 from infra.user_config import GROUPER_ENV, GROUPERS
@@ -893,10 +894,16 @@ class DiagramGenerator:
             analysis = root_analysis if scope.scope_id == ROOT_SCOPE_ID else sub_analyses.get(scope.scope_id)
             if analysis is None:
                 continue
+            # A baseline name that is a directory or an identifier is renamed even when nothing
+            # changed: locked or carried forward, it would ship on every later run.
+            unnatural_ids = {
+                component.component_id for component in analysis.components if not is_natural_name(component.name)
+            }
             editable_ids = {
                 group.group_id
                 for group in scope.groups
                 if group.group_id in refreshed_ids
+                or group.group_id in unnatural_ids
                 or bool(self._group_files(group, scope) & changed_files)
                 or bool(group.qualified_names & self._changed_members)
             }
@@ -906,6 +913,7 @@ class DiagramGenerator:
                 group.group_id
                 for group in scope.groups
                 if group.group_id in editable_ids
+                and group.group_id not in unnatural_ids
                 and group.group_id in baseline_membership.meta_by_id
                 and self._group_member_keys(group, scope) == baseline_membership.meta_by_id[group.group_id].member_keys
             )

{codeboarding-0.15.3 → codeboarding-0.15.5}/diagram_analysis/scope_assembly.py

@@ -24,6 +24,7 @@ from static_analyzer import StaticAnalysisFatalError
 from static_analyzer.cfg import Edge
 from infra.repo_utils.path_utils import normalize_repo_path
 from static_analyzer.clustering import ClusterGroup, ClusterScopeResult, GroupConnection
+from static_analyzer.clustering.names.tokens import is_natural_name
 from diagram_analysis.reference_resolver import StaticReferenceResolver
 
 logger = logging.getLogger(__name__)
@@ -119,10 +120,26 @@ class ScopeAssembler:
             for group_id in ordered_ids
             if group_id in semantics_by_id
             and group_id not in locked_name_ids
-            and semantics_by_id[group_id].name.strip()
+            and is_natural_name(semantics_by_id[group_id].name.strip())
+        }
+        # A directory or identifier name is not kept just because the model gave no better one:
+        # it is replaced by the rule name written as words.
+        fallbacks = {
+            group_id
+            for group_id in ordered_ids
+            if group_id not in proposals
+            and group_id not in locked_name_ids
+            and group_id in components
+            and not is_natural_name(components[group_id].name)
+        }
+        taken = {
+            component.name
+            for group_id, component in components.items()
+            if group_id not in proposals and group_id not in fallbacks
         }
-        taken = {component.name for group_id, component in components.items() if group_id not in proposals}
         taken.update(reserved_names)
+        for group_id in fallbacks:
+            components[group_id].name = groups_by_id[group_id].unique_name(taken)
         named: set[str] = set()
         for group_id in ordered_ids:
             component = components.get(group_id)