Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(architecture): add bounded external dependency summaries (#1942)
Raghav Chamadiya56b952fbf8eb
diff --git a/packages/api-client/src/external-systems.ts b/packages/api-client/src/external-systems.tsindex 2adf37d54..393fbdb46 100644--- a/packages/api-client/src/external-systems.ts+++ b/packages/api-client/src/external-systems.ts@@ -1,4 +1,8 @@-import type { ExternalSystemsRegistry } from "@repowise-dev/types/external-systems";+import type {+ ExternalSystemsRegistry,+ ExternalSystemsSummary,+ ExternalSystemsSummaryScope,+} from "@repowise-dev/types/external-systems";import { apiGet } from "./client";@@ -10,3 +14,22 @@ export async function getExternalSystems(`/api/repos/${repoId}/external-systems`,);}++/** Canonical packages with bounded declaration and persisted usage aggregates. */+export async function getExternalSystemsSummary(+ repoId: string,+ options: {+ scope?: ExternalSystemsSummaryScope;+ limit?: number;+ offset?: number;+ } = {},+): Promise<ExternalSystemsSummary> {+ const params = new URLSearchParams();+ if (options.scope) params.set("scope", options.scope);+ if (options.limit !== undefined) params.set("limit", String(options.limit));+ if (options.offset !== undefined) params.set("offset", String(options.offset));+ const query = params.size ? `?${params.toString()}` : "";+ return apiGet<ExternalSystemsSummary>(+ `/api/repos/${repoId}/external-systems/summary${query}`,+ );+}diff --git a/packages/core/src/repowise/core/persistence/_interfaces/_graph_records.py b/packages/core/src/repowise/core/persistence/_interfaces/_graph_records.pyindex 7d19b6632..555176b21 100644--- a/packages/core/src/repowise/core/persistence/_interfaces/_graph_records.py+++ b/packages/core/src/repowise/core/persistence/_interfaces/_graph_records.py@@ -93,7 +93,7 @@ class GraphRecordsIndexStore(ABC):@abstractmethodasync def link_graph_nodes_to_external_systems(- self, repository_id: str, name_to_id: dict[str, int]+ self, repository_id: str, name_to_id: dict[str, int | None]) -> int: ...@abstractmethoddiff --git a/packages/core/src/repowise/core/persistence/crud/external_systems.py b/packages/core/src/repowise/core/persistence/crud/external_systems.pyindex f69ddb355..70633984b 100644--- a/packages/core/src/repowise/core/persistence/crud/external_systems.py+++ b/packages/core/src/repowise/core/persistence/crud/external_systems.py@@ -103,13 +103,12 @@ async def replace_external_systems(async def link_graph_nodes_to_external_systems(session: AsyncSession,repository_id: str,- name_to_id: dict[str, int],+ name_to_id: dict[str, int | None],) -> int:"""Resolve ``external:{name}`` graph nodes to their ExternalSystem row.- ``name_to_id`` should be a flat map of dep name → ExternalSystem id- (collapse multi-manifest entries by picking any id — the C4 renderer- only needs ``name``/``category`` which are the same across rows).+ Bare names shared by multiple ecosystems map to ``None`` so ambiguous+ targets remain unlinked; ecosystem-qualified keys remain resolvable.Returns the number of graph_nodes updated."""@@ -125,20 +124,61 @@ async def link_graph_nodes_to_external_systems(updated = 0for node in result.scalars():suffix = node.node_id[len(prefix) :]- # Try the full suffix first, then the first segment (handles e.g.- # ``external:fastapi.responses`` → ``fastapi``).- sys_id = name_to_id.get(suffix)- if sys_id is None and "." in suffix:- sys_id = name_to_id.get(suffix.split(".", 1)[0])- if sys_id is None and "/" in suffix:- sys_id = name_to_id.get(suffix.split("/", 1)[0])- if sys_id is not None and node.external_system_id != sys_id:+ # Try exact and ecosystem-shaped package candidates in priority order.+ sys_id = next(+ (name_to_id[name] for name in _external_name_candidates(suffix) if name in name_to_id),+ None,+ )+ if node.external_system_id != sys_id:node.external_system_id = sys_idupdated += 1await session.flush()return updated+def _external_name_candidates(external_name: str) -> tuple[str, ...]:+ """Return declaration names to try, ordered from precise to broad.++ Resolver output is ecosystem-shaped (npm subpaths, Rust ``::`` paths,+ Python dotted modules). Keeping normalization in this small pure function+ makes another ecosystem a local extension without another graph traversal.+ """+ candidates = [external_name]+ if external_name.startswith("@"):+ parts = external_name.split("/")+ if len(parts) >= 2:+ candidates.append("/".join(parts[:2]))+ for separator in ("::", ".", "/"):+ if separator in external_name:+ candidates.append(external_name.split(separator, 1)[0])+ return tuple(dict.fromkeys(candidate for candidate in candidates if candidate))+++def build_external_system_link_map(+ systems: list[dict],+ id_map: dict[tuple[str, str], int],+) -> dict[str, int | None]:+ """Build exact/prefixed link keys while preserving name ambiguity."""+ links: dict[str, int | None] = {}+ name_ecosystems: dict[str, str] = {}+ for system in systems:+ name = system.get("name", "")+ declared_in = system.get("declared_in", "")+ ecosystem = system.get("ecosystem", "")+ system_id = id_map.get((name, declared_in))+ if not name or system_id is None:+ continue+ if ecosystem:+ links.setdefault(f"{ecosystem}:{name}", system_id)+ previous_ecosystem = name_ecosystems.get(name)+ if previous_ecosystem is None:+ name_ecosystems[name] = ecosystem+ links[name] = system_id+ elif previous_ecosystem != ecosystem:+ links[name] = None+ return links++async def list_external_systems(session: AsyncSession, repository_id: str) -> list[ExternalSystem]:"""List all external systems for a repository, ordered by name."""result = await session.execute(diff --git a/packages/core/src/repowise/core/persistence/stores/_sql_graph_records.py b/packages/core/src/repowise/core/persistence/stores/_sql_graph_records.pyindex 0d73782d0..93b65646e 100644--- a/packages/core/src/repowise/core/persistence/stores/_sql_graph_records.py+++ b/packages/core/src/repowise/core/persistence/stores/_sql_graph_records.py@@ -110,7 +110,7 @@ class _SqlGraphRecordsMixin(GraphRecordsIndexStore):)async def link_graph_nodes_to_external_systems(- self, repository_id: str, name_to_id: dict[str, int]+ self, repository_id: str, name_to_id: dict[str, int | None]) -> int:return await crud.link_graph_nodes_to_external_systems(self._session, repository_id, name_to_iddiff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.pyindex 94857b7d7..d7b6a6fe6 100644--- a/packages/core/src/repowise/core/pipeline/incremental.py+++ b/packages/core/src/repowise/core/pipeline/incremental.py@@ -1367,16 +1367,13 @@ async def refresh_external_systems(]from repowise.core.persistence.crud import (+ build_external_system_link_map,link_graph_nodes_to_external_systems,replace_external_systems,)id_map = await replace_external_systems(session, repo_id, systems)- # Collapse multi-manifest duplicates: any id for a given name works (the- # C4 renderer only needs name/category/ecosystem, stable across rows).- name_to_id: dict[str, int] = {}- for (name, _declared_in), sys_id in id_map.items():- name_to_id.setdefault(name, sys_id)+ name_to_id = build_external_system_link_map(systems, id_map)await link_graph_nodes_to_external_systems(session, repo_id, name_to_id)log(f"External systems refreshed: [cyan]{len(systems)}[/cyan] deps")return Truediff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.pyindex aab7975f6..f8ce2e64d 100644--- a/packages/core/src/repowise/core/pipeline/persist.py+++ b/packages/core/src/repowise/core/pipeline/persist.py@@ -1380,11 +1380,9 @@ async def persist_ingestion(result: Any, session: Any, repo_id: str) -> int:external_systems = getattr(result, "external_systems", None) or []if external_systems:id_map = await bulk_upsert_external_systems(session, repo_id, external_systems)- # Collapse multi-manifest duplicates: any id for a given name is fine- # (renderer only needs name/category/ecosystem which are stable).- name_to_id: dict[str, int] = {}- for (name, _declared_in), sys_id in id_map.items():- name_to_id.setdefault(name, sys_id)+ from repowise.core.persistence.crud import build_external_system_link_map++ name_to_id = build_external_system_link_map(external_systems, id_map)await link_graph_nodes_to_external_systems(session, repo_id, name_to_id)# ---- Symbols -------------------------------------------------------------diff --git a/packages/server/src/repowise/server/routers/external_systems.py b/packages/server/src/repowise/server/routers/external_systems.pyindex 44a6ba7e4..855517c97 100644--- a/packages/server/src/repowise/server/routers/external_systems.py+++ b/packages/server/src/repowise/server/routers/external_systems.py@@ -8,7 +8,9 @@ each dependency was declared in — for the Architecture Dependencies view.from __future__ import annotations-from fastapi import APIRouter, Depends+from typing import Literal++from fastapi import APIRouter, Depends, Queryfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession@@ -17,6 +19,11 @@ from repowise.server.deps import get_db_session, verify_api_keyfrom repowise.server.schemas.external_systems import (ExternalSystemEntry,ExternalSystemsResponse,+ ExternalSystemsSummaryResponse,+)+from repowise.server.services.external_systems import (+ MAX_SUMMARY_LIMIT,+ build_external_systems_summary,)router = APIRouter(@@ -26,6 +33,23 @@ router = APIRouter()+ "/{repo_id}/external-systems/summary",+ response_model=ExternalSystemsSummaryResponse,+)+async def summarize_external_systems(+ repo_id: str,+ scope: Literal["primary", "all"] = "primary",+ limit: int = Query(default=200, ge=1, le=MAX_SUMMARY_LIMIT),+ offset: int = Query(default=0, ge=0),+ session: AsyncSession = Depends(get_db_session),+) -> ExternalSystemsSummaryResponse:+ """Canonical packages joined to already-persisted import evidence."""+ return await build_external_systems_summary(+ session, repo_id, scope=scope, limit=limit, offset=offset+ )++@router.get("/{repo_id}/external-systems", response_model=ExternalSystemsResponse)async def list_external_systems(repo_id: str,diff --git a/packages/server/src/repowise/server/schemas/external_systems.py b/packages/server/src/repowise/server/schemas/external_systems.pyindex 838a30373..ff9c90fd2 100644--- a/packages/server/src/repowise/server/schemas/external_systems.py+++ b/packages/server/src/repowise/server/schemas/external_systems.py@@ -2,6 +2,8 @@from __future__ import annotations+from typing import Literal+from pydantic import BaseModel@@ -27,3 +29,52 @@ class ExternalSystemsResponse(BaseModel):dev_count: intecosystems: list[str]manifests: list[str]+++ExternalSystemLinkState = Literal["linked", "unlinked"]+ExternalSystemsSummaryScope = Literal["primary", "all"]+++class ExternalSystemSummaryEntry(BaseModel):+ """One canonical package with declaration and graph-usage aggregates."""++ package_key: str+ name: str+ display_name: str+ ecosystem: str+ category: str+ io_kind: str | None = None+ runtime_declared: bool+ dev_declared: bool+ declaration_count: int+ manifest_count: int+ versions: list[str]+ versions_total: int+ versions_truncated: bool+ multiple_versions: bool+ external_node_count: int+ import_edge_count: int+ importing_file_count: int+ link_state: ExternalSystemLinkState+++class ExternalSystemsSummaryResponse(BaseModel):+ """Bounded package summaries for the external-dependency scan surface."""++ items: list[ExternalSystemSummaryEntry]+ returned: int+ total_packages: int+ limit: int+ offset: int+ truncated: bool+ scope: ExternalSystemsSummaryScope+ excluded_declarations: int+ total_declarations: int+ runtime_packages: int+ dev_only_packages: int+ observed_packages: int+ linked_packages: int+ unlinked_packages: int+ linked_without_imports: int+ ecosystems: list[str]+ manifest_count: intdiff --git a/packages/server/src/repowise/server/services/external_systems.py b/packages/server/src/repowise/server/services/external_systems.pynew file mode 100644index 000000000..a03aea046--- /dev/null+++ b/packages/server/src/repowise/server/services/external_systems.py@@ -0,0 +1,297 @@+"""Bounded read models for declared packages and persisted graph usage."""++from __future__ import annotations++from collections import defaultdict+from typing import Literal++from sqlalchemy import and_, case, distinct, func, literal, not_, or_, select+from sqlalchemy.ext.asyncio import AsyncSession++from repowise.core.persistence.models import ExternalSystem, GraphEdge, GraphNode+from repowise.server.schemas.external_systems import (+ ExternalSystemsSummaryResponse,+ ExternalSystemSummaryEntry,+)++SummaryScope = Literal["primary", "all"]+DEFAULT_SUMMARY_LIMIT = 200+MAX_SUMMARY_LIMIT = 400+SUMMARY_VERSION_LIMIT = 5+PRIMARY_AUXILIARY_PREFIXES = (".claude/worktrees/", "local-stash/")+++def _primary_path_predicate(path_column):+ return not_(or_(*(path_column.like(f"{prefix}%") for prefix in PRIMARY_AUXILIARY_PREFIXES)))+++def _scope_predicate(scope: SummaryScope):+ if scope == "all":+ return literal(True)+ return _primary_path_predicate(ExternalSystem.declared_in)+++def _package_query(repository_id: str, scope: SummaryScope):+ runtime = func.max(case((ExternalSystem.is_dev_dep.is_(False), 1), else_=0))+ dev = func.max(case((ExternalSystem.is_dev_dep.is_(True), 1), else_=0))+ return (+ select(+ ExternalSystem.ecosystem.label("ecosystem"),+ ExternalSystem.name.label("name"),+ func.max(ExternalSystem.display_name).label("display_name"),+ func.min(ExternalSystem.category).label("category"),+ func.min(ExternalSystem.io_kind).label("io_kind"),+ runtime.label("runtime_declared"),+ dev.label("dev_declared"),+ func.count(ExternalSystem.id).label("declaration_count"),+ func.count(distinct(ExternalSystem.declared_in)).label("manifest_count"),+ )+ .where(+ ExternalSystem.repository_id == repository_id,+ _scope_predicate(scope),+ )+ .group_by(ExternalSystem.ecosystem, ExternalSystem.name)+ .subquery("declared_packages")+ )+++def _usage_query(repository_id: str, scope: SummaryScope):+ edge_scope = (+ literal(True) if scope == "all" else _primary_path_predicate(GraphEdge.source_node_id)+ )+ return (+ select(+ ExternalSystem.ecosystem.label("ecosystem"),+ ExternalSystem.name.label("name"),+ func.count(distinct(GraphNode.node_id)).label("external_node_count"),+ func.count(GraphEdge.id).label("import_edge_count"),+ func.count(distinct(GraphEdge.source_node_id)).label("importing_file_count"),+ )+ .select_from(GraphNode)+ .join(ExternalSystem, ExternalSystem.id == GraphNode.external_system_id)+ .outerjoin(+ GraphEdge,+ and_(+ GraphEdge.repository_id == repository_id,+ GraphEdge.target_node_id == GraphNode.node_id,+ GraphEdge.edge_type == "imports",+ edge_scope,+ ),+ )+ .where(+ GraphNode.repository_id == repository_id,+ GraphNode.external_system_id.is_not(None),+ )+ .group_by(ExternalSystem.ecosystem, ExternalSystem.name)+ .subquery("package_usage")+ )+++async def _versions_for_page(+ session: AsyncSession,+ repository_id: str,+ scope: SummaryScope,+ identities: list[tuple[str, str]],+) -> dict[tuple[str, str], tuple[list[str], int]]:+ """Fetch at most ``SUMMARY_VERSION_LIMIT`` values for each page item."""+ if not identities:+ return {}+ identity_filter = or_(+ *(+ and_(ExternalSystem.ecosystem == ecosystem, ExternalSystem.name == name)+ for ecosystem, name in identities+ )+ )+ distinct_versions = (+ select(+ ExternalSystem.ecosystem.label("ecosystem"),+ ExternalSystem.name.label("name"),+ ExternalSystem.version.label("version"),+ )+ .where(+ ExternalSystem.repository_id == repository_id,+ _scope_predicate(scope),+ ExternalSystem.version.is_not(None),+ identity_filter,+ )+ .group_by(ExternalSystem.ecosystem, ExternalSystem.name, ExternalSystem.version)+ .subquery("distinct_versions")+ )+ ranked = select(+ distinct_versions,+ func.row_number()+ .over(+ partition_by=(distinct_versions.c.ecosystem, distinct_versions.c.name),+ order_by=distinct_versions.c.version,+ )+ .label("version_rank"),+ func.count()+ .over(partition_by=(distinct_versions.c.ecosystem, distinct_versions.c.name))+ .label("versions_total"),+ ).subquery("ranked_versions")+ rows = (+ await session.execute(select(ranked).where(ranked.c.version_rank <= SUMMARY_VERSION_LIMIT))+ ).all()+ values: dict[tuple[str, str], list[str]] = defaultdict(list)+ totals: dict[tuple[str, str], int] = {}+ for row in rows:+ key = (row.ecosystem, row.name)+ values[key].append(row.version)+ totals[key] = int(row.versions_total)+ return {key: (versions, totals[key]) for key, versions in values.items()}+++async def build_external_systems_summary(+ session: AsyncSession,+ repository_id: str,+ *,+ scope: SummaryScope = "primary",+ limit: int = DEFAULT_SUMMARY_LIMIT,+ offset: int = 0,+) -> ExternalSystemsSummaryResponse:+ """Return a bounded package page in constant SQL statements, independent of N."""+ packages = _package_query(repository_id, scope)+ usage = _usage_query(repository_id, scope)+ node_count = func.coalesce(usage.c.external_node_count, 0)+ edge_count = func.coalesce(usage.c.import_edge_count, 0)+ file_count = func.coalesce(usage.c.importing_file_count, 0)+ joined = packages.outerjoin(+ usage,+ and_(+ usage.c.ecosystem == packages.c.ecosystem,+ usage.c.name == packages.c.name,+ ),+ )+ summaries = select(+ packages,+ node_count.label("external_node_count"),+ edge_count.label("import_edge_count"),+ file_count.label("importing_file_count"),+ func.count().over().label("total_packages"),+ func.sum(packages.c.declaration_count).over().label("total_declarations"),+ func.sum(packages.c.runtime_declared).over().label("runtime_packages"),+ func.sum(+ case(+ (+ and_(+ packages.c.dev_declared == 1,+ packages.c.runtime_declared == 0,+ ),+ 1,+ ),+ else_=0,+ )+ )+ .over()+ .label("dev_only_packages"),+ func.sum(case((edge_count > 0, 1), else_=0)).over().label("observed_packages"),+ func.sum(case((node_count > 0, 1), else_=0)).over().label("linked_packages"),+ func.sum(case((and_(node_count > 0, edge_count == 0), 1), else_=0))+ .over()+ .label("linked_without_imports"),+ ).select_from(joined)+ ordered_summaries = summaries.order_by(+ packages.c.runtime_declared.desc(),+ file_count.desc(),+ func.lower(packages.c.name),+ packages.c.ecosystem,+ )+ page_rows = (await session.execute(ordered_summaries.limit(limit).offset(offset))).all()+ manifest_count = (+ select(func.count(distinct(ExternalSystem.declared_in)))+ .where(+ ExternalSystem.repository_id == repository_id,+ _scope_predicate(scope),+ )+ .scalar_subquery()+ )+ excluded_declarations = (+ select(func.count(ExternalSystem.id))+ .where(+ ExternalSystem.repository_id == repository_id,+ ~_scope_predicate("primary"),+ )+ .scalar_subquery()+ )+ metadata_rows = (+ await session.execute(+ select(+ ExternalSystem.ecosystem,+ manifest_count.label("manifest_count"),+ excluded_declarations.label("excluded_declarations"),+ )+ .where(+ ExternalSystem.repository_id == repository_id,+ _scope_predicate(scope),+ )+ .group_by(ExternalSystem.ecosystem)+ )+ ).all()+ excluded = 0+ if scope == "primary" and metadata_rows:+ excluded = int(metadata_rows[0].excluded_declarations or 0)+ elif scope == "primary":+ # Grouped totals have no row when every declaration is auxiliary.+ excluded = int(+ (+ await session.execute(+ select(func.count(ExternalSystem.id)).where(+ ExternalSystem.repository_id == repository_id,+ ~_scope_predicate("primary"),+ )+ )+ ).scalar_one()+ )+ totals_row = page_rows[0] if page_rows else None+ if totals_row is None and offset:+ totals_row = (await session.execute(ordered_summaries.limit(1))).first()+ identities = [(row.ecosystem, row.name) for row in page_rows]+ versions = await _versions_for_page(session, repository_id, scope, identities)+ items: list[ExternalSystemSummaryEntry] = []+ for row in page_rows:+ package_versions, versions_total = versions.get((row.ecosystem, row.name), ([], 0))+ resolved_nodes = int(row.external_node_count or 0)+ items.append(+ ExternalSystemSummaryEntry(+ package_key=f"{row.ecosystem}:{row.name}",+ name=row.name,+ display_name=row.display_name or row.name,+ ecosystem=row.ecosystem,+ category=row.category,+ io_kind=row.io_kind,+ runtime_declared=bool(row.runtime_declared),+ dev_declared=bool(row.dev_declared),+ declaration_count=int(row.declaration_count),+ manifest_count=int(row.manifest_count),+ versions=package_versions,+ versions_total=versions_total,+ versions_truncated=versions_total > len(package_versions),+ multiple_versions=versions_total > 1,+ external_node_count=resolved_nodes,+ import_edge_count=int(row.import_edge_count or 0),+ importing_file_count=int(row.importing_file_count or 0),+ link_state="linked" if resolved_nodes else "unlinked",+ )+ )+ total_packages = int(totals_row.total_packages or 0) if totals_row else 0+ linked_packages = int(totals_row.linked_packages or 0) if totals_row else 0+ first_metadata = metadata_rows[0] if metadata_rows else None+ return ExternalSystemsSummaryResponse(+ items=items,+ returned=len(items),+ total_packages=total_packages,+ limit=limit,+ offset=offset,+ truncated=offset + len(items) < total_packages,+ scope=scope,+ excluded_declarations=excluded,+ total_declarations=int(totals_row.total_declarations or 0) if totals_row else 0,+ runtime_packages=int(totals_row.runtime_packages or 0) if totals_row else 0,+ dev_only_packages=int(totals_row.dev_only_packages or 0) if totals_row else 0,+ observed_packages=int(totals_row.observed_packages or 0) if totals_row else 0,+ linked_packages=linked_packages,+ unlinked_packages=total_packages - linked_packages,+ linked_without_imports=(int(totals_row.linked_without_imports or 0) if totals_row else 0),+ ecosystems=sorted(row.ecosystem for row in metadata_rows),+ manifest_count=(int(first_metadata.manifest_count or 0) if first_metadata else 0),+ )diff --git a/packages/types/src/external-systems.ts b/packages/types/src/external-systems.tsindex eb2a26d42..6296ca06d 100644--- a/packages/types/src/external-systems.ts+++ b/packages/types/src/external-systems.ts@@ -47,3 +47,49 @@ export interface ExternalSystemsRegistry {ecosystems: string[];manifests: string[];}++export type ExternalSystemLinkState = "linked" | "unlinked";+export type ExternalSystemsSummaryScope = "primary" | "all";++/** One canonical package with declaration and persisted graph-usage aggregates. */+export interface ExternalSystemSummaryEntry {+ package_key: string;+ name: string;+ display_name: string;+ ecosystem: string;+ category: string;+ io_kind: C4IoKind | null;+ runtime_declared: boolean;+ dev_declared: boolean;+ declaration_count: number;+ manifest_count: number;+ versions: string[];+ versions_total: number;+ versions_truncated: boolean;+ multiple_versions: boolean;+ external_node_count: number;+ import_edge_count: number;+ importing_file_count: number;+ link_state: ExternalSystemLinkState;+}++/** Bounded package summaries for the external-dependency scan surface. */+export interface ExternalSystemsSummary {+ items: ExternalSystemSummaryEntry[];+ returned: number;+ total_packages: number;+ limit: number;+ offset: number;+ truncated: boolean;+ scope: ExternalSystemsSummaryScope;+ excluded_declarations: number;+ total_declarations: number;+ runtime_packages: number;+ dev_only_packages: number;+ observed_packages: number;+ linked_packages: number;+ unlinked_packages: number;+ linked_without_imports: number;+ ecosystems: string[];+ manifest_count: number;+}diff --git a/tests/unit/server/test_external_systems.py b/tests/unit/server/test_external_systems.pyindex 13267818c..1c312f35d 100644--- a/tests/unit/server/test_external_systems.py+++ b/tests/unit/server/test_external_systems.py@@ -4,9 +4,14 @@ from __future__ import annotationsimport pytestfrom httpx import AsyncClient+from sqlalchemy import event, select+from repowise.core.persistence.crud.external_systems import (+ build_external_system_link_map,+ link_graph_nodes_to_external_systems,+)from repowise.core.persistence.database import get_session-from repowise.core.persistence.models import ExternalSystem+from repowise.core.persistence.models import ExternalSystem, GraphEdge, GraphNodefrom tests.unit.server.conftest import create_test_repo@@ -49,6 +54,178 @@ async def _seed(session_factory, repo_id: str) -> None:await session.flush()+async def _seed_summary(session_factory, repo_id: str) -> None:+ async with get_session(session_factory) as session:+ react_web = ExternalSystem(+ repository_id=repo_id,+ name="react",+ display_name="React",+ ecosystem="npm",+ category="framework",+ version="^19.0.0",+ declared_in="packages/web/package.json",+ is_dev_dep=False,+ )+ react_ui = ExternalSystem(+ repository_id=repo_id,+ name="react",+ display_name="React",+ ecosystem="npm",+ category="framework",+ version="^18.0.0",+ declared_in="packages/ui/package.json",+ is_dev_dep=True,+ )+ next_package = ExternalSystem(+ repository_id=repo_id,+ name="next",+ display_name="Next",+ ecosystem="npm",+ category="framework",+ version="~15.5.0",+ declared_in="packages/web/package.json",+ is_dev_dep=False,+ )+ vitest = ExternalSystem(+ repository_id=repo_id,+ name="vitest",+ display_name="Vitest",+ ecosystem="npm",+ category="tool",+ version="^4.1.0",+ declared_in="packages/ui/package.json",+ is_dev_dep=True,+ )+ radix = ExternalSystem(+ repository_id=repo_id,+ name="@radix-ui/react-dialog",+ display_name="Radix Dialog",+ ecosystem="npm",+ category="library",+ version="^1.0.0",+ declared_in="packages/web/package.json",+ is_dev_dep=False,+ )+ serde = ExternalSystem(+ repository_id=repo_id,+ name="serde",+ display_name="Serde",+ ecosystem="cargo",+ category="library",+ version="1",+ declared_in="crates/core/Cargo.toml",+ is_dev_dep=False,+ )+ auxiliary = ExternalSystem(+ repository_id=repo_id,+ name="aux-only",+ display_name="Aux only",+ ecosystem="npm",+ category="library",+ version="1.0.0",+ declared_in=".claude/worktrees/demo/package.json",+ is_dev_dep=False,+ )+ session.add_all([react_web, react_ui, next_package, vitest, radix, serde, auxiliary])+ await session.flush()++ session.add_all(+ [+ GraphNode(+ repository_id=repo_id,+ node_id="external:react",+ language="external",+ ),+ GraphNode(+ repository_id=repo_id,+ node_id="external:react/jsx-runtime",+ language="external",+ ),+ GraphNode(+ repository_id=repo_id,+ node_id="external:next/navigation",+ language="external",+ ),+ GraphNode(+ repository_id=repo_id,+ node_id="external:@radix-ui/react-dialog/subpath",+ language="external",+ ),+ GraphNode(+ repository_id=repo_id,+ node_id="external:serde::Deserialize",+ language="external",+ ),+ ]+ )+ session.add_all(+ [+ GraphEdge(+ repository_id=repo_id,+ source_node_id="src/a.ts",+ target_node_id="external:react",+ edge_type="imports",+ ),+ GraphEdge(+ repository_id=repo_id,+ source_node_id="src/dialog.ts",+ target_node_id="external:@radix-ui/react-dialog/subpath",+ edge_type="imports",+ ),+ GraphEdge(+ repository_id=repo_id,+ source_node_id="src/lib.rs",+ target_node_id="external:serde::Deserialize",+ edge_type="imports",+ ),+ GraphEdge(+ repository_id=repo_id,+ source_node_id="src/a.ts",+ target_node_id="external:react/jsx-runtime",+ edge_type="imports",+ ),+ GraphEdge(+ repository_id=repo_id,+ source_node_id="src/b.ts",+ target_node_id="external:react",+ edge_type="imports",+ ),+ GraphEdge(+ repository_id=repo_id,+ source_node_id=".claude/worktrees/demo/src/a.ts",+ target_node_id="external:react",+ edge_type="imports",+ ),+ GraphEdge(+ repository_id=repo_id,+ source_node_id="src/page.ts",+ target_node_id="external:next/navigation",+ edge_type="imports",+ ),+ # Non-import edges do not constitute declared-package usage.+ GraphEdge(+ repository_id=repo_id,+ source_node_id="src/call.ts",+ target_node_id="external:react",+ edge_type="calls",+ ),+ ]+ )+ await session.flush()+ linked = await link_graph_nodes_to_external_systems(+ session,+ repo_id,+ {+ "react": react_web.id,+ "next": next_package.id,+ "vitest": vitest.id,+ "@radix-ui/react-dialog": radix.id,+ "serde": serde.id,+ },+ )+ assert linked == 5++@pytest.mark.asyncioasync def test_registry_lists_all_rows(client: AsyncClient, app) -> None:repo = await create_test_repo(client)@@ -83,3 +260,259 @@ async def test_registry_empty(client: AsyncClient) -> None:data = resp.json()assert data["total"] == 0assert data["items"] == []+++async def test_linker_preserves_cross_ecosystem_ambiguity_and_prefixed_names(+ client: AsyncClient, app+) -> None:+ repo = await create_test_repo(client)+ systems = [+ {"name": "shared", "ecosystem": "npm", "declared_in": "package.json"},+ {"name": "shared", "ecosystem": "pypi", "declared_in": "pyproject.toml"},+ {+ "name": "Newtonsoft.Json",+ "ecosystem": "nuget",+ "declared_in": "app.csproj",+ },+ {"name": "http", "ecosystem": "pub", "declared_in": "pubspec.yaml"},+ ]+ async with get_session(app.state.session_factory) as session:+ rows = [+ ExternalSystem(+ repository_id=repo["id"],+ display_name=system["name"],+ category="library",+ **system,+ )+ for system in systems+ ]+ session.add_all(rows)+ await session.flush()+ id_map = {(row.name, row.declared_in): row.id for row in rows}+ links = build_external_system_link_map(systems, id_map)+ assert links["shared"] is None+ assert links["npm:shared"] == rows[0].id+ node_ids = [+ "external:shared",+ "external:npm:shared",+ "external:nuget:Newtonsoft.Json",+ "external:pub:http",+ ]+ session.add_all(+ GraphNode(+ repository_id=repo["id"],+ node_id=node_id,+ language="external",+ external_system_id=(rows[0].id if node_id == "external:shared" else None),+ )+ for node_id in node_ids+ )+ await session.flush()++ assert await link_graph_nodes_to_external_systems(session, repo["id"], links) == 4+ linked = {+ node.node_id: node.external_system_id+ for node in (+ await session.execute(+ select(GraphNode).where(GraphNode.repository_id == repo["id"])+ )+ ).scalars()+ }+ assert linked["external:shared"] is None+ assert linked["external:npm:shared"] == rows[0].id+ assert linked["external:nuget:Newtonsoft.Json"] == rows[2].id+ assert linked["external:pub:http"] == rows[3].id+++async def test_summary_joins_unique_packages_to_import_evidence(client: AsyncClient, app) -> None:+ repo = await create_test_repo(client)+ await _seed_summary(app.state.session_factory, repo["id"])++ resp = await client.get(f"/api/repos/{repo['id']}/external-systems/summary")++ assert resp.status_code == 200+ data = resp.json()+ assert data["total_packages"] == 5+ assert data["total_declarations"] == 6+ assert data["returned"] == 5+ assert data["truncated"] is False+ assert data["scope"] == "primary"+ assert data["excluded_declarations"] == 1+ assert data["linked_packages"] == 4+ assert data["unlinked_packages"] == 1+ assert data["observed_packages"] == 4+ assert data["ecosystems"] == ["cargo", "npm"]++ by_name = {item["name"]: item for item in data["items"]}+ react = by_name["react"]+ assert react["versions"] == ["^18.0.0", "^19.0.0"]+ assert react["versions_total"] == 2+ assert react["versions_truncated"] is False+ assert react["multiple_versions"] is True+ assert react["import_edge_count"] == 3+ assert react["importing_file_count"] == 2+ assert react["link_state"] == "linked"+ assert by_name["@radix-ui/react-dialog"]["import_edge_count"] == 1+ assert by_name["serde"]["import_edge_count"] == 1+ assert by_name["vitest"]["link_state"] == "unlinked"+ assert "aux-only" not in by_name++ all_data = (+ await client.get(f"/api/repos/{repo['id']}/external-systems/summary?scope=all")+ ).json()+ all_react = next(item for item in all_data["items"] if item["name"] == "react")+ assert all_react["import_edge_count"] == 4+ assert all_react["importing_file_count"] == 3+++async def test_summary_query_count_is_constant(client: AsyncClient, app, test_engine) -> None:+ repo = await create_test_repo(client)+ async with get_session(app.state.session_factory) as session:+ session.add_all(+ [+ ExternalSystem(+ repository_id=repo["id"],+ name=f"package-{index}",+ display_name=f"Package {index}",+ ecosystem="npm",+ category="library",+ version="1.0.0",+ declared_in=f"packages/p{index}/package.json",+ is_dev_dep=False,+ )+ for index in range(250)+ ]+ )+ await session.flush()++ statements: list[str] = []++ def record(*args) -> None:+ statements.append(str(args[2]))++ event.listen(test_engine.sync_engine, "before_cursor_execute", record)+ try:+ resp = await client.get(f"/api/repos/{repo['id']}/external-systems/summary")+ finally:+ event.remove(test_engine.sync_engine, "before_cursor_execute", record)++ assert resp.status_code == 200+ assert resp.json()["total_packages"] == 250+ assert resp.json()["returned"] == 200+ assert resp.json()["truncated"] is True+ selects = [statement for statement in statements if statement.lstrip().startswith("SELECT")]+ assert len(selects) == 3+++async def test_summary_bounds_pages_versions_and_can_include_auxiliary_scope(+ client: AsyncClient, app+) -> None:+ repo = await create_test_repo(client)+ async with get_session(app.state.session_factory) as session:+ session.add_all(+ [+ ExternalSystem(+ repository_id=repo["id"],+ name="many-versions",+ display_name="Many versions",+ ecosystem="npm",+ category="library",+ version=f"{version}.0.0",+ declared_in=f"packages/p{version}/package.json",+ is_dev_dep=False,+ )+ for version in range(8)+ ]+ + [+ ExternalSystem(+ repository_id=repo["id"],+ name="aux-only",+ display_name="Aux only",+ ecosystem="npm",+ category="library",+ version="1.0.0",+ declared_in="local-stash/example/package.json",+ is_dev_dep=True,+ )+ ]+ )+ await session.flush()++ primary = (await client.get(f"/api/repos/{repo['id']}/external-systems/summary?limit=1")).json()+ assert primary["returned"] == 1+ assert primary["total_packages"] == 1+ assert primary["excluded_declarations"] == 1+ item = primary["items"][0]+ assert item["versions_total"] == 8+ assert len(item["versions"]) == 5+ assert item["versions_truncated"] is True++ all_scopes = (+ await client.get(+ f"/api/repos/{repo['id']}/external-systems/summary?scope=all&limit=1&offset=1"+ )+ ).json()+ assert all_scopes["scope"] == "all"+ assert all_scopes["total_packages"] == 2+ assert all_scopes["returned"] == 1+ assert all_scopes["offset"] == 1+ assert all_scopes["excluded_declarations"] == 0++ too_large = await client.get(f"/api/repos/{repo['id']}/external-systems/summary?limit=401")+ assert too_large.status_code == 422+++async def test_summary_reports_auxiliary_only_declarations(client: AsyncClient, app) -> None:+ repo = await create_test_repo(client)+ async with get_session(app.state.session_factory) as session:+ session.add(+ ExternalSystem(+ repository_id=repo["id"],+ name="aux-only",+ display_name="Aux only",+ ecosystem="npm",+ category="library",+ version="1.0.0",+ declared_in="local-stash/example/package.json",+ is_dev_dep=True,+ )+ )+ await session.flush()++ data = (await client.get(f"/api/repos/{repo['id']}/external-systems/summary")).json()+ assert data["items"] == []+ assert data["total_packages"] == 0+ assert data["excluded_declarations"] == 1+++async def test_summary_empty(client: AsyncClient) -> None:+ repo = await create_test_repo(client)++ resp = await client.get(f"/api/repos/{repo['id']}/external-systems/summary")++ assert resp.status_code == 200+ assert resp.json() == {+ "items": [],+ "returned": 0,+ "total_packages": 0,+ "limit": 200,+ "offset": 0,+ "truncated": False,+ "scope": "primary",+ "excluded_declarations": 0,+ "total_declarations": 0,+ "runtime_packages": 0,+ "dev_only_packages": 0,+ "observed_packages": 0,+ "linked_packages": 0,+ "unlinked_packages": 0,+ "linked_without_imports": 0,+ "ecosystems": [],+ "manifest_count": 0,+ }