codeboarding 0.15.5__tar.gz → 0.15.6__tar.gz

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

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

{codeboarding-0.15.5 → codeboarding-0.15.6}/agents/agent_responses.py

@@ -9,7 +9,7 @@ from enum import StrEnum
 from pydantic import BaseModel, Field
 
 from infra.clustering_ids import ComponentId
-from agents.file_index_models import FileEntry, FileMethodGroup, MethodIndexEntry
+from agents.file_index_models import FileEntry, FileMethodGroup
 from agents.scope_ids import ROOT_SCOPE_ID
 
 logger = logging.getLogger(__name__)
@@ -89,20 +89,6 @@ class RelationEdge(LLMBaseModel):
         exclude=True,
     )
 
-    @classmethod
-    def from_dict(cls, edge: dict, methods_index: dict[str, MethodIndexEntry]) -> RelationEdge:
-        source_key = edge.get("source")
-        target_key = edge.get("target")
-        if not isinstance(source_key, str) or not isinstance(target_key, str):
-            raise ValueError("Relation edge endpoints must be method-index keys")
-        call_sites = edge.get("call_sites") or []
-        return cls(
-            source=_relation_endpoint_from_key(source_key, methods_index),
-            target=_relation_endpoint_from_key(target_key, methods_index),
-            description=edge.get("description", ""),
-            call_sites=[RelationCallSite.model_validate(site) for site in call_sites],
-        )
-
     @classmethod
     def from_edge(cls, edge) -> RelationEdge:
         return cls(
@@ -138,28 +124,6 @@ class RelationEdge(LLMBaseModel):
         )
 
 
-def _relation_endpoint_from_key(
-    key: str,
-    methods_index: dict[str, MethodIndexEntry],
-) -> SourceCodeReference:
-    indexed = methods_index.get(key)
-    if indexed is not None:
-        return SourceCodeReference(
-            qualified_name=indexed.qualified_name,
-            reference_file=indexed.file_path or None,
-            reference_start_line=indexed.start_line,
-            reference_end_line=indexed.end_line,
-        )
-
-    file_path, separator, qualified_name = key.partition("|")
-    if not separator or not qualified_name:
-        raise ValueError(f"Malformed relation edge endpoint key: {key!r}")
-    return SourceCodeReference(
-        qualified_name=qualified_name,
-        reference_file=file_path or None,
-    )
-
-
 class Relation(LLMBaseModel):
     """A relationship between two components."""
 

{codeboarding-0.15.5 → codeboarding-0.15.6}/agents/file_index_models.py

@@ -42,20 +42,6 @@ class MethodEntry(BaseModel):
         )
 
 
-class MethodIndexEntry(BaseModel):
-    """Serialized method metadata referenced by relation edges."""
-
-    file_path: str = Field(description="Relative path to the source file.")
-    qualified_name: str = Field(description="Fully qualified method/function name.")
-    start_line: int = Field(description="Starting line number in the file.")
-    end_line: int = Field(description="Ending line number in the file.")
-    type: str = Field(description="Node type name (METHOD, FUNCTION, CLASS, ...).")
-    content_hash: str = Field(
-        default="",
-        description="Truncated SHA-256 of the method's source lines; '' when unknown.",
-    )
-
-
 class FileMethodGroup(BaseModel):
     """All methods/functions belonging to a component within a single file."""
 

{codeboarding-0.15.5 → codeboarding-0.15.6}/agents/relation_edges.py

@@ -133,89 +133,53 @@ def edge_crosses_components(
     src_id: str,
     dst_id: str,
 ) -> bool:
-    """Return whether an edge's owned endpoints match its declared component pair."""
+    """Return whether each endpoint has an owner within its side of the declared component pair.
+
+    Why an unowned endpoint fails: no component holds it, so analysis.json, which cites only
+    component members, could not record the edge.
+    """
     for reference, component_id in ((edge.source, src_id), (edge.target, dst_id)):
         owner = owner_of(reference)
-        if owner and component_id and not is_self_or_descendant(owner, component_id):
+        if component_id and not (owner and is_self_or_descendant(owner, component_id)):
             return False
     return True
 
 
-def drop_misattributed_edges(
-    relations: list[Relation],
-    owner_of: Callable[[SourceCodeReference], str],
-) -> list[Relation]:
-    """Drop edges whose owning component contradicts the relation's declared pair.
-
-    Why: the per-scope ownership index sees only that scope's own components, so an
-    out-of-scope endpoint resolves to nothing and the edge survives its own gate. A
-    frontier-wide owner map resolves it and rejects the mismatch. A relation stripped of
-    every edge is kept: it still stands on its evidence prose, the ordinary shape of an
-    inferred relation.
-    """
-    filtered: list[Relation] = []
-    for relation in relations:
-        all_edges = [
-            edge
-            for edge in relation.all_edges
-            if edge_crosses_components(edge, owner_of, relation.src_id, relation.dst_id)
-        ]
-        if len(all_edges) == len(relation.all_edges):
-            filtered.append(relation)
-            continue
-        surviving = {edge.identity() for edge in all_edges}
-        filtered.append(
-            relation.model_copy(
-                update={
-                    "all_edges": all_edges,
-                    "key_edges": [edge for edge in relation.key_edges if edge.identity() in surviving],
-                }
-            )
-        )
-    return filtered
-
-
 def prune_ungrounded_edges(
     relations: list[Relation],
     owner_of: Callable[[SourceCodeReference], str],
     keep_edge: Callable[[RelationEdge], bool],
     changed_members: set[str] | None = None,
 ) -> list[Relation]:
-    """Re-apply edge filters after baseline preservation, moving misfiled edges when possible."""
+    """Re-apply edge filters after baseline preservation, moving each misfiled edge to the pair its owners join.
+
+    Why never left where it was: analysis.json files an edge under the pair its owners join, so a
+    misfiled one cannot be saved; one whose pair no relation holds is dropped.
+    """
     by_pair: dict[tuple[str, str], Relation] = {(relation.src_id, relation.dst_id): relation for relation in relations}
     additions: dict[tuple[str, str], list[RelationEdge]] = {}
 
-    def find_relation_pair_for_edge(edge: RelationEdge) -> tuple[tuple[str, str] | None, bool]:
+    def find_relation_pair_for_edge(edge: RelationEdge) -> tuple[str, str] | None:
         source = owner_of(edge.source)
         target = owner_of(edge.target)
-        if not source or not target:
-            return None, False
         if is_self_or_descendant(source, target) or is_self_or_descendant(target, source):
-            return None, True
+            return None
         for pair in by_pair:
             if is_self_or_descendant(source, pair[0]) and is_self_or_descendant(target, pair[1]):
-                return pair, False
-        return None, False
+                return pair
+        return None
 
     kept: list[Relation] = []
     for relation in relations:
-        pair = (relation.src_id, relation.dst_id)
         all_edges: list[RelationEdge] = []
         for edge in relation.all_edges:
-            if not keep_edge(edge):
+            if not keep_edge(edge) or not (owner_of(edge.source) and owner_of(edge.target)):
                 continue
             if edge_crosses_components(edge, owner_of, relation.src_id, relation.dst_id):
                 all_edges.append(edge)
                 continue
-            if changed_members is not None and edge.source.qualified_name not in changed_members:
-                all_edges.append(edge)
-                continue
-            matching_pair, is_internal = find_relation_pair_for_edge(edge)
-            if is_internal:
-                continue
-            if matching_pair is None or matching_pair == pair:
-                all_edges.append(edge)
-            else:
+            matching_pair = find_relation_pair_for_edge(edge)
+            if matching_pair is not None:
                 additions.setdefault(matching_pair, []).append(edge)
         surviving = {edge.identity() for edge in all_edges}
         key_edges = [edge for edge in relation.key_edges if edge.identity() in surviving]

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

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

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

@@ -82,6 +82,7 @@ health/plugins/plugin_loader.py
 health/plugins/protocols.py
 health/plugins/registry.py
 infra/__init__.py
+infra/analysis_format.py
 infra/clustering_ids.py
 infra/constants.py
 infra/install.py

{codeboarding-0.15.5 → codeboarding-0.15.6}/codeboarding_cli/github_action.py

@@ -5,6 +5,7 @@ from pathlib import Path
 
 from codeboarding_workflows.analysis import run_incremental_workflow
 from diagram_analysis import DEFAULT_DEPTH_CAP, DiagramGenerator, RunContext
+from diagram_analysis.exceptions import UnreadableAnalysisError
 from diagram_analysis.io_utils import load_analysis_metadata
 from output_generators.rendering import render_docs
 from infra.repo_utils import checkout_repo, clone_repository
@@ -92,7 +93,12 @@ def _resolve_depth_cap(temp_repo_folder: Path) -> int:
     env_depth = os.getenv("DIAGRAM_DEPTH_CAP")
     if env_depth is not None:
         return int(env_depth)
-    metadata = load_analysis_metadata(temp_repo_folder)
+    try:
+        metadata = load_analysis_metadata(temp_repo_folder)
+    except UnreadableAnalysisError:
+        # Why: run_incremental_workflow replaces an unreadable baseline with a full run, so it has no cap to carry.
+        logger.warning("The seeded analysis.json cannot be read; using the default depth cap.", exc_info=True)
+        return DEFAULT_DEPTH_CAP
     if metadata is not None:
         return int(metadata.get("depth_cap", DEFAULT_DEPTH_CAP))
     return DEFAULT_DEPTH_CAP

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

@@ -14,8 +14,11 @@ import logging
 from pathlib import Path
 
 from agents.content_hash import compute_source_tree_hash
+from agents.agent_responses import AnalysisInsights
 from agents.scope_ids import ROOT_SCOPE_ID
 from diagram_analysis import DiagramGenerator
+from diagram_analysis.analysis_json import require_format_version
+from diagram_analysis.exceptions import UnreadableAnalysisError
 from diagram_analysis.io_utils import (
     load_analysis_metadata,
     load_expandable_component_ids,
@@ -104,20 +107,14 @@ def run_partial(
     """Partial scope — regenerate a single component within an existing analysis.
 
     Raises ``BaselineUnavailableError`` when no ``analysis.json`` baseline
-    exists — partial updates a *component within* an existing analysis and
-    has no meaningful behavior without one.
+    this Core reads exists — partial updates a *component within* an existing
+    analysis and has no meaningful behavior without one.
     """
     logger.info(
         f"Running PARTIAL analysis workflow for project '{run_paths.project_name}', component '{component_id}'."
     )
 
-    # Prefer the configured cap; retain depth_level for legacy baselines.
-    metadata = load_analysis_metadata(run_paths.output_dir)
-    if metadata is None:
-        raise BaselineUnavailableError(
-            f"No baseline analysis.json found in '{run_paths.output_dir}'. Run a full analysis first."
-        )
-
+    metadata = _baseline_metadata(run_paths.output_dir)
     baseline_source_hash = str(metadata.get("source_tree_hash", ""))
     if not baseline_source_hash:
         raise BaselineUnavailableError(
@@ -130,16 +127,8 @@ def run_partial(
             "Partial analysis requires an up-to-date source baseline. Run incremental analysis before expanding a component."
         )
 
-    depth_cap = int(metadata.get("depth_cap", metadata.get("depth_level", DEFAULT_DEPTH_CAP)))
-    full_analysis = load_full_analysis(run_paths.output_dir)
-    if full_analysis is None:
-        # Metadata was present but the unified read failed — treat as a
-        # corrupt or partially-written baseline, same surfacing as cold start.
-        raise BaselineUnavailableError(
-            f"analysis.json in '{run_paths.output_dir}' could not be parsed as a unified analysis."
-        )
-
-    root_analysis, sub_analyses = full_analysis
+    depth_cap = int(metadata["depth_cap"])
+    root_analysis, sub_analyses = _load_baseline(run_paths.output_dir)
     preserved_expandable_ids = load_expandable_component_ids(run_paths.output_dir)
 
     component_to_analyze = None
@@ -180,10 +169,6 @@ def run_partial(
     # its subcomponents. Rebuild reads each sub's LLM relation labels, which live
     # only in memory (they aren't serialized), so it must run before the save.
     sub_analyses[component_id] = sub_analysis
-    # The baseline we loaded may predate child scopes being confined to their parent.
-    # Repair it here too: this flow only regenerates one component, so nothing else
-    # would reconcile the rest of the tree before the save asserts containment.
-    generator._rescope_child_analyses(root_analysis, sub_analyses, set())
     # Keep coverage and fingerprint artifacts unchanged; persist only the new lineage below.
     generator.finalize_and_save(
         root_analysis,
@@ -208,18 +193,13 @@ 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, 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.
+    Raises ``BaselineUnavailableError`` when no baseline analysis this Core reads
+    exists, and its subclass ``EngineChangedError`` when another engine version
+    wrote the static analysis — callers should surface a "run full analysis"
+    prompt rather than silently degrading to an unscoped run.
     """
-    # Prefer the configured cap; retain depth_level for legacy baselines.
-    metadata = load_analysis_metadata(run_paths.output_dir)
-    if metadata is None:
-        raise BaselineUnavailableError(
-            f"No baseline analysis.json found in '{run_paths.output_dir}'. Run a full analysis first."
-        )
-    depth_cap = int(metadata.get("depth_cap", metadata.get("depth_level", DEFAULT_DEPTH_CAP)))
+    metadata = _baseline_metadata(run_paths.output_dir)
+    depth_cap = int(metadata["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():
@@ -239,30 +219,65 @@ def run_incremental(
         static_analyzer=static_analyzer,
         changes=changes,
     )
-    return run_incremental_workflow(generator)
+    return _run_from_baseline(generator, _load_baseline(run_paths.output_dir))
 
 
 def run_incremental_workflow(generator: DiagramGenerator) -> Path:
     """Run incremental analysis when a baseline exists, otherwise fall back to a full run.
 
-    Public kernel used by ``github_action.py``, the desktop wrapper, and
-    ``run_incremental`` (CLI). Shape:
-    1. If no prior ``analysis.json`` is present, run full analysis.
-    2. Otherwise hand the loaded baseline to ``generate_analysis_incremental``,
-       which itself falls back to a full run when the cluster snapshot is
-       missing or the cluster delta produces nothing actionable.
+    Public kernel for unattended callers (``github_action.py``): with no prior ``analysis.json``,
+    or one this Core cannot read, it runs a full analysis. ``generate_analysis_incremental`` itself
+    falls back to a full run when the cluster snapshot is missing or the delta has nothing actionable.
     """
+    try:
+        baseline = load_full_analysis(Path(generator.output_dir))
+    except UnreadableAnalysisError:
+        # Why: nobody is there to answer a "run a full analysis" prompt.
+        logger.warning("The existing analysis.json cannot be updated; running full analysis.", exc_info=True)
+        baseline = None
+    return _run_from_baseline(generator, baseline)
+
+
+def _baseline_metadata(output_dir: Path) -> dict:
+    """The baseline's metadata; raises ``BaselineUnavailableError`` unless this Core can update the baseline."""
+    try:
+        metadata = load_analysis_metadata(output_dir)
+        if metadata is not None:
+            require_format_version(metadata)
+    except UnreadableAnalysisError as error:
+        raise BaselineUnavailableError(str(error)) from error
+    if metadata is None:
+        raise BaselineUnavailableError(f"No baseline analysis.json found in '{output_dir}'. Run a full analysis first.")
+    return metadata
+
+
+def _load_baseline(output_dir: Path) -> tuple[AnalysisInsights, dict[str, AnalysisInsights]]:
+    """The root analysis and sub-analyses of a baseline ``_baseline_metadata`` accepted.
+
+    Raises ``BaselineUnavailableError`` when its body is not one this Core can read.
+    """
+    try:
+        baseline = load_full_analysis(output_dir)
+    except UnreadableAnalysisError as error:
+        raise BaselineUnavailableError(str(error)) from error
+    if baseline is None:
+        raise BaselineUnavailableError(f"analysis.json in '{output_dir}' was removed during the run.")
+    return baseline
+
+
+def _run_from_baseline(
+    generator: DiagramGenerator, baseline: tuple[AnalysisInsights, dict[str, AnalysisInsights]] | None
+) -> Path:
+    """Update *baseline* incrementally, or run in full without one or with an empty one."""
     output_dir = Path(generator.output_dir)
     # Progress saves land mid-run, so a failed run must not leave its partial analysis.json behind.
     before = snapshot_analysis(output_dir)
     try:
-        existing = load_full_analysis(output_dir)
-        metadata = load_analysis_metadata(output_dir)
-        if existing is None or metadata is None:
-            logger.info("No existing analysis baseline; running full analysis.")
+        if baseline is None:
+            logger.info("No usable analysis baseline; running full analysis.")
             return generator.generate_analysis()
 
-        root_analysis, sub_analyses = existing
+        root_analysis, sub_analyses = baseline
 
         if not root_analysis.components:
             logger.info("Baseline analysis has no components; running full analysis.")

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

@@ -23,9 +23,9 @@ class BaselineUnavailableError(RuntimeError):
     """Raised when a workflow needs an existing analysis.json baseline but none is usable.
 
     Covers the cases where incremental/partial cannot trust its starting state: no
-    ``analysis.json`` on disk, or a baseline that predates content versioning (no
-    whole-tree fingerprint to diff against, so an "empty" change set is
-    indistinguishable from "no changes").
+    ``analysis.json`` on disk, one this Core cannot read (an older format), or a
+    baseline that predates content versioning (no whole-tree fingerprint to diff
+    against, so an "empty" change set is indistinguishable from "no changes").
 
     Callers must surface a "run full analysis" prompt rather than silently degrading
     to an unscoped run or an empty-but-successful update.