Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.ts
index 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.py
index 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):
@abstractmethod
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: ...
@abstractmethod
diff --git a/packages/core/src/repowise/core/persistence/crud/external_systems.py b/packages/core/src/repowise/core/persistence/crud/external_systems.py
index 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 = 0
for 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_id
updated += 1
await 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.py
index 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_id
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 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 True
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 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.py
index 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, Query
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
@@ -17,6 +19,11 @@ from repowise.server.deps import get_db_session, verify_api_key
from 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.py
index 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: int
ecosystems: 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: int
diff --git a/packages/server/src/repowise/server/services/external_systems.py b/packages/server/src/repowise/server/services/external_systems.py
new file mode 100644
index 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.ts
index 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.py
index 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 annotations
import pytest
from 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, GraphNode
from 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.asyncio
async 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"] == 0
assert 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,
+ }