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(external-systems): classify dependencies by I/O boundary kind (#529)

Raghav Chamadiyaf3c573ea1dc0
diff --git a/packages/core/alembic/versions/0032_external_system_io_kind.py b/packages/core/alembic/versions/0032_external_system_io_kind.py
new file mode 100644
index 000000000..13294e46c
--- /dev/null
+++ b/packages/core/alembic/versions/0032_external_system_io_kind.py
@@ -0,0 +1,39 @@
+"""Add external_systems.io_kind: the I/O-boundary type.
+
+Tags each third-party dependency by the *kind* of side effect it performs at a
+process boundary: ``io_kind in {db, network, filesystem, subprocess, lock}``.
+Nullable and backward-compatible: a NULL ``io_kind`` means "untyped" and every
+consumer (the C4 architecture view today; a future perf / security layer)
+degrades gracefully. Populated by
+``repowise.core.ingestion.external_systems.io_kind``.
+
+Revision ID: 0032
+Revises: 0031
+Create Date: 2026-06-20
+
+NOTE: if a parallel branch lands a migration on top of 0031 before this merges,
+rebase ``down_revision`` onto that revision so the chain stays linear.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0032"
+down_revision: str | None = "0031"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ with op.batch_alter_table("external_systems") as batch_op:
+ batch_op.add_column(sa.Column("io_kind", sa.String(16), nullable=True))
+
+
+def downgrade() -> None:
+ with op.batch_alter_table("external_systems") as batch_op:
+ batch_op.drop_column("io_kind")
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/base.py b/packages/core/src/repowise/core/ingestion/external_systems/base.py
index 899fdb30a..d1243ff6d 100644
--- a/packages/core/src/repowise/core/ingestion/external_systems/base.py
+++ b/packages/core/src/repowise/core/ingestion/external_systems/base.py
@@ -25,6 +25,7 @@ class ExternalSystemRecord:
version: str | None = None
display_name: str = ""
category: str = "library" # populated by classifier
+ io_kind: str | None = None # populated by io_kind classifier; None = untyped
is_dev_dep: bool = False
extras: dict[str, str] = field(default_factory=dict)
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/cargo.py b/packages/core/src/repowise/core/ingestion/external_systems/cargo.py
index bb7948ad2..45d064f50 100644
--- a/packages/core/src/repowise/core/ingestion/external_systems/cargo.py
+++ b/packages/core/src/repowise/core/ingestion/external_systems/cargo.py
@@ -16,6 +16,7 @@ except ModuleNotFoundError: # pragma: no cover — Python <3.11
from .base import ExternalSystemRecord
from .classifier import classify, display_name_for
+from .io_kind import classify_io_kind
filenames: tuple[str, ...] = ("Cargo.toml",)
ecosystem: str = "cargo"
@@ -59,6 +60,7 @@ def parse(manifest_path: Path, repo_root: Path) -> list[ExternalSystemRecord]:
version=version,
display_name=display_name_for(name),
category=classify(name),
+ io_kind=classify_io_kind(name),
is_dev_dep=is_dev,
)
)
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/go.py b/packages/core/src/repowise/core/ingestion/external_systems/go.py
index ad49690d3..946a315c6 100644
--- a/packages/core/src/repowise/core/ingestion/external_systems/go.py
+++ b/packages/core/src/repowise/core/ingestion/external_systems/go.py
@@ -14,6 +14,7 @@ from pathlib import Path
from .base import ExternalSystemRecord
from .classifier import classify, display_name_for
+from .io_kind import classify_io_kind
filenames: tuple[str, ...] = ("go.mod",)
ecosystem: str = "go"
@@ -80,6 +81,7 @@ def parse(manifest_path: Path, repo_root: Path) -> list[ExternalSystemRecord]:
version=version,
display_name=display_name_for(name.split("/")[-1]),
category=classify(name.split("/")[-1]),
+ io_kind=classify_io_kind(name.split("/")[-1]),
is_dev_dep=indirect,
)
)
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/io_kind.py b/packages/core/src/repowise/core/ingestion/external_systems/io_kind.py
new file mode 100644
index 000000000..bde394df2
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/external_systems/io_kind.py
@@ -0,0 +1,113 @@
+"""I/O-boundary classifier: tag a dependency by the *kind* of side effect it
+performs at a process boundary.
+
+``io_kind in {db, network, filesystem, subprocess, lock}`` upgrades each entry
+in the dependency registry from "a library" to a *database* / *network API* /
+*filesystem* / *subprocess* / *lock* boundary. This is a **shared** primitive:
+the C4 architecture view types its external nodes from it today, and a future
+performance / security / conformance layer reuses the same table (resolve a
+call site to its imported origin, then classify that origin here).
+
+Design rules (mirror :mod:`.classifier`):
+ - Conservative. An unknown name returns ``None`` (not a guess) so every
+ downstream consumer degrades gracefully: a null ``io_kind`` must never
+ break rendering or analysis.
+ - The seed tables cover third-party packages *and* the stdlib modules a
+ future import-resolution pass will hand us (``subprocess``, ``socket``,
+ ``node:fs``, ``child_process``). Registry rows only ever carry declared
+ third-party deps, so the stdlib entries are dormant until that consumer
+ lands; they cost nothing and keep the classifier complete.
+ - Cross-ecosystem by name: Python and the TS/Node ecosystem share one
+ table, keyed on the lowercased dependency name.
+
+``IO_KINDS`` is the canonical set of values. It is mirrored in
+``packages/types/src/external-systems.ts`` (``C4_IO_KINDS``) and guarded by a
+cross-language parity test (``packages/types/__tests__/contracts.test.ts`` +
+``tests/unit/ingestion/test_io_kind.py``).
+"""
+
+from __future__ import annotations
+
+#: Canonical, frozen set of boundary kinds. If this changes, the TS mirror
+#: (``C4_IO_KINDS``) and both parity tests must change too.
+IO_KINDS: tuple[str, ...] = ("db", "network", "filesystem", "subprocess", "lock")
+
+# ---------------------------------------------------------------------------
+# Seed tables: name (lowercased) -> io_kind. Python + TS/Node ecosystems.
+# ---------------------------------------------------------------------------
+
+_DB_NAMES: frozenset[str] = frozenset({
+ # Python
+ "sqlalchemy", "psycopg", "psycopg2", "psycopg2-binary", "asyncpg",
+ "aiomysql", "aiosqlite", "mysqlclient", "pymysql", "mysql-connector-python",
+ "redis", "aioredis", "pymongo", "motor", "mongoengine", "cassandra-driver",
+ "elasticsearch", "neo4j", "sqlmodel", "peewee", "tortoise-orm", "databases",
+ "duckdb", "clickhouse-driver", "pyodbc",
+ # TS / Node (cassandra-driver above is published in both ecosystems)
+ "ioredis", "mongoose", "mongodb", "@prisma/client", "prisma",
+ "drizzle-orm", "knex", "pg", "mysql", "mysql2", "sequelize", "typeorm",
+ "better-sqlite3", "@elastic/elasticsearch", "@planetscale/database", "kysely",
+})
+
+_NETWORK_NAMES: frozenset[str] = frozenset({
+ # Python (socket is the canonical network boundary, not filesystem)
+ "httpx", "requests", "aiohttp", "urllib3", "websockets", "websocket-client",
+ "grpcio", "httpcore", "tornado", "treq", "niquests", "socket",
+ # TS / Node
+ "axios", "node-fetch", "got", "superagent", "undici", "ky", "needle",
+ "request", "@grpc/grpc-js", "ws", "socket.io-client", "graphql-request",
+})
+
+_FILESYSTEM_NAMES: frozenset[str] = frozenset({
+ # Python (mostly stdlib, dormant until an import-resolution consumer lands)
+ "open", "aiofiles", "watchdog", "pathlib", "shutil", "fsspec",
+ # TS / Node
+ "node:fs", "fs", "fs-extra", "graceful-fs", "chokidar", "node:path",
+})
+
+_SUBPROCESS_NAMES: frozenset[str] = frozenset({
+ # Python (stdlib + popular wrappers)
+ "subprocess", "sh", "pexpect", "plumbum", "invoke",
+ # TS / Node
+ "child_process", "node:child_process", "execa", "cross-spawn", "shelljs",
+})
+
+_LOCK_NAMES: frozenset[str] = frozenset({
+ # Python (stdlib threading/async primitives + distributed locks).
+ # ``redlock`` is published in both the Python and Node ecosystems.
+ "threading", "filelock", "fasteners", "redlock", "python-redis-lock",
+ # TS / Node
+ "async-mutex", "proper-lockfile",
+})
+
+# Name -> io_kind, built once. A name appearing in two tables would be a bug;
+# later tables do not silently win because we assert disjointness below.
+_BY_NAME: dict[str, str] = {}
+for _kind, _names in (
+ ("db", _DB_NAMES),
+ ("network", _NETWORK_NAMES),
+ ("filesystem", _FILESYSTEM_NAMES),
+ ("subprocess", _SUBPROCESS_NAMES),
+ ("lock", _LOCK_NAMES),
+):
+ for _name in _names:
+ # ``redlock`` legitimately appears under lock in both ecosystems; keep
+ # the first assignment and skip any duplicate of the *same* kind.
+ if _name in _BY_NAME and _BY_NAME[_name] != _kind:
+ raise AssertionError(
+ f"io_kind seed collision: {_name!r} is both "
+ f"{_BY_NAME[_name]!r} and {_kind!r}"
+ )
+ _BY_NAME[_name] = _kind
+
+
+def classify_io_kind(name: str) -> str | None:
+ """Return the :data:`IO_KINDS` boundary for ``name``, or ``None``.
+
+ ``name`` is a dependency / import name as it appears in a manifest or
+ import statement (e.g. ``"httpx"``, ``"@prisma/client"``, ``"node:fs"``).
+ Unknown names return ``None``; callers must treat that as "untyped".
+ """
+ if not name:
+ return None
+ return _BY_NAME.get(name.strip().lower())
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/maven.py b/packages/core/src/repowise/core/ingestion/external_systems/maven.py
index eb0958a28..7834e649b 100644
--- a/packages/core/src/repowise/core/ingestion/external_systems/maven.py
+++ b/packages/core/src/repowise/core/ingestion/external_systems/maven.py
@@ -13,6 +13,7 @@ from pathlib import Path
from .base import ExternalSystemRecord
from .classifier import classify, display_name_for
+from .io_kind import classify_io_kind
filenames: tuple[str, ...] = ("pom.xml",)
ecosystem: str = "maven"
@@ -136,6 +137,7 @@ def parse(manifest_path: Path, repo_root: Path) -> list[ExternalSystemRecord]:
version=version if version and "${" not in version else None,
display_name=display_name_for(artifact_id),
category=classify(artifact_id),
+ io_kind=classify_io_kind(artifact_id),
is_dev_dep=is_dev,
)
)
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/npm.py b/packages/core/src/repowise/core/ingestion/external_systems/npm.py
index f017fb681..a594444c4 100644
--- a/packages/core/src/repowise/core/ingestion/external_systems/npm.py
+++ b/packages/core/src/repowise/core/ingestion/external_systems/npm.py
@@ -12,6 +12,7 @@ from pathlib import Path
from .base import ExternalSystemRecord
from .classifier import classify, display_name_for
+from .io_kind import classify_io_kind
filenames: tuple[str, ...] = ("package.json",)
ecosystem: str = "npm"
@@ -55,6 +56,7 @@ def parse(manifest_path: Path, repo_root: Path) -> list[ExternalSystemRecord]:
version=version,
display_name=display_name_for(name),
category=classify(name),
+ io_kind=classify_io_kind(name),
is_dev_dep=is_dev,
)
)
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/nuget.py b/packages/core/src/repowise/core/ingestion/external_systems/nuget.py
index 9d1c3812d..1928c4964 100644
--- a/packages/core/src/repowise/core/ingestion/external_systems/nuget.py
+++ b/packages/core/src/repowise/core/ingestion/external_systems/nuget.py
@@ -13,6 +13,7 @@ from xml.etree import ElementTree as ET
from .base import ExternalSystemRecord
from .classifier import classify, display_name_for
+from .io_kind import classify_io_kind
# .csproj filenames are repo-specific; the discovery layer matches "*.csproj".
filenames: tuple[str, ...] = ()
@@ -48,6 +49,7 @@ def parse(manifest_path: Path, repo_root: Path) -> list[ExternalSystemRecord]:
version=version.strip() if version else None,
display_name=display_name_for(name.split(".")[-1]),
category=classify(name),
+ io_kind=classify_io_kind(name),
is_dev_dep=False,
)
)
diff --git a/packages/core/src/repowise/core/ingestion/external_systems/pypi.py b/packages/core/src/repowise/core/ingestion/external_systems/pypi.py
index aeec6bbf7..292c03325 100644
--- a/packages/core/src/repowise/core/ingestion/external_systems/pypi.py
+++ b/packages/core/src/repowise/core/ingestion/external_systems/pypi.py
@@ -21,6 +21,7 @@ except ModuleNotFoundError: # pragma: no cover — Python <3.11
from .base import ExternalSystemRecord
from .classifier import classify, display_name_for
+from .io_kind import classify_io_kind
filenames: tuple[str, ...] = ("pyproject.toml",)
ecosystem: str = "pypi"
@@ -151,6 +152,7 @@ def _add_simple(
version=version,
display_name=display_name_for(name),
category=classify(name),
+ io_kind=classify_io_kind(name),
is_dev_dep=is_dev,
)
)
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index b37484318..2d7f4f3e5 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -208,6 +208,10 @@ class ExternalSystem(Base):
display_name: Mapped[str] = mapped_column(String(255), nullable=False, default="")
ecosystem: Mapped[str] = mapped_column(String(32), nullable=False)
category: Mapped[str] = mapped_column(String(32), nullable=False, default="library")
+ # Boundary type in {db, network, filesystem, subprocess, lock}; nullable.
+ # NULL means "untyped" and every consumer (C4, perf, security) degrades
+ # gracefully. Populated by ingestion.external_systems.io_kind.
+ io_kind: Mapped[str | None] = mapped_column(String(16), nullable=True)
version: Mapped[str | None] = mapped_column(String(64), nullable=True)
declared_in: Mapped[str] = mapped_column(Text, nullable=False)
is_dev_dep: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 4f5b3320b..2f6e2e5f9 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -356,6 +356,7 @@ async def run_pipeline(
"display_name": r.display_name,
"ecosystem": r.ecosystem,
"category": r.category,
+ "io_kind": r.io_kind,
"version": r.version,
"declared_in": r.declared_in,
"is_dev_dep": r.is_dev_dep,
diff --git a/packages/server/src/repowise/server/routers/external_systems.py b/packages/server/src/repowise/server/routers/external_systems.py
index 0ea82d4f0..69bbc2e3a 100644
--- a/packages/server/src/repowise/server/routers/external_systems.py
+++ b/packages/server/src/repowise/server/routers/external_systems.py
@@ -54,6 +54,7 @@ async def list_external_systems(
display_name=r.display_name or r.name,
ecosystem=r.ecosystem,
category=r.category,
+ io_kind=r.io_kind,
version=r.version,
declared_in=r.declared_in,
is_dev_dep=bool(r.is_dev_dep),
diff --git a/packages/server/src/repowise/server/schemas/c4.py b/packages/server/src/repowise/server/schemas/c4.py
index 3a1065a29..64ac5a7f6 100644
--- a/packages/server/src/repowise/server/schemas/c4.py
+++ b/packages/server/src/repowise/server/schemas/c4.py
@@ -24,6 +24,7 @@ class C4ExternalSystemResponse(BaseModel):
category: str # framework | service | tool | library
ecosystem: str
version: str | None = None
+ io_kind: str | None = None # db | network | filesystem | subprocess | lock | null
class C4ContainerResponse(BaseModel):
diff --git a/packages/server/src/repowise/server/schemas/external_systems.py b/packages/server/src/repowise/server/schemas/external_systems.py
index a40754d67..838a30373 100644
--- a/packages/server/src/repowise/server/schemas/external_systems.py
+++ b/packages/server/src/repowise/server/schemas/external_systems.py
@@ -12,6 +12,7 @@ class ExternalSystemEntry(BaseModel):
display_name: str
ecosystem: str # npm | pypi | cargo | gomod | nuget | ...
category: str # framework | service | tool | library
+ io_kind: str | None = None # db | network | filesystem | subprocess | lock | null
version: str | None = None
declared_in: str # manifest path, e.g. "packages/web/package.json"
is_dev_dep: bool = False
diff --git a/packages/server/src/repowise/server/services/c4_builder/__init__.py b/packages/server/src/repowise/server/services/c4_builder/__init__.py
index 61a34c972..d1b31d748 100644
--- a/packages/server/src/repowise/server/services/c4_builder/__init__.py
+++ b/packages/server/src/repowise/server/services/c4_builder/__init__.py
@@ -94,6 +94,7 @@ async def _external_views(
category=row.category,
ecosystem=row.ecosystem,
version=row.version,
+ io_kind=row.io_kind,
)
)
name_to_id[name] = view_id
diff --git a/packages/server/src/repowise/server/services/c4_builder/architecture.py b/packages/server/src/repowise/server/services/c4_builder/architecture.py
index bd3576955..4eb147cfa 100644
--- a/packages/server/src/repowise/server/services/c4_builder/architecture.py
+++ b/packages/server/src/repowise/server/services/c4_builder/architecture.py
@@ -110,6 +110,7 @@ async def _external_views(
category=row.category,
ecosystem=row.ecosystem,
version=row.version,
+ io_kind=row.io_kind,
)
)
return views
diff --git a/packages/server/src/repowise/server/services/c4_builder/mermaid.py b/packages/server/src/repowise/server/services/c4_builder/mermaid.py
index 49b34dad9..5c720b4c9 100644
--- a/packages/server/src/repowise/server/services/c4_builder/mermaid.py
+++ b/packages/server/src/repowise/server/services/c4_builder/mermaid.py
@@ -38,8 +38,27 @@ def _q(text: str) -> str:
return text.replace('"', "'")
-def _ext_kind(cat: str) -> str:
- """Map our category to a Mermaid C4 element type."""
+# Boundary type to Mermaid C4 element. ``SystemDb_Ext`` renders with the
+# cylinder glyph so a db dependency reads as a database rather than a generic
+# box; the other kinds fall back to standard external boxes.
+_IO_KIND_ELEMENT: dict[str, str] = {
+ "db": "SystemDb_Ext",
+ "network": "System_Ext",
+ "filesystem": "Container_Ext",
+ "subprocess": "Container_Ext",
+ "lock": "Container_Ext",
+}
+
+
+def _ext_kind(cat: str, io_kind: str | None = None) -> str:
+ """Map a dependency to a Mermaid C4 element type.
+
+ Prefer the I/O boundary type when known (a db dep renders as a database
+ cylinder); fall back to the coarse category when ``io_kind`` is None so
+ untyped dependencies keep today's behaviour.
+ """
+ if io_kind is not None and io_kind in _IO_KIND_ELEMENT:
+ return _IO_KIND_ELEMENT[io_kind]
if cat == "service":
return "System_Ext"
return "Container_Ext"
@@ -146,7 +165,7 @@ def _emit_externals(externals: list[ExternalSystemView]) -> list[str]:
def _external_line(ext: ExternalSystemView) -> str:
- kind = _ext_kind(ext.category)
+ kind = _ext_kind(ext.category, ext.io_kind)
version = f" {ext.version}" if ext.version else ""
return (
f' {kind}({_sid(ext.id)}, "{_q(ext.display_name)}", '
diff --git a/packages/server/src/repowise/server/services/c4_builder/models.py b/packages/server/src/repowise/server/services/c4_builder/models.py
index b4a52b0aa..bcecd833f 100644
--- a/packages/server/src/repowise/server/services/c4_builder/models.py
+++ b/packages/server/src/repowise/server/services/c4_builder/models.py
@@ -37,6 +37,9 @@ class ExternalSystemView:
category: str # framework | service | tool | library
ecosystem: str
version: str | None = None
+ # Boundary type in {db, network, filesystem, subprocess, lock}; None when
+ # the dependency isn't in the io_kind seed table (renders untyped).
+ io_kind: str | None = None
@dataclass(frozen=True)
diff --git a/packages/server/src/repowise/server/services/c4_builder/serialize.py b/packages/server/src/repowise/server/services/c4_builder/serialize.py
index 7be1e133b..6f6c05a72 100644
--- a/packages/server/src/repowise/server/services/c4_builder/serialize.py
+++ b/packages/server/src/repowise/server/services/c4_builder/serialize.py
@@ -38,6 +38,7 @@ def external_system_response(e: ExternalSystemView) -> C4ExternalSystemResponse:
category=e.category,
ecosystem=e.ecosystem,
version=e.version,
+ io_kind=e.io_kind,
)
diff --git a/packages/types/__tests__/contracts.test.ts b/packages/types/__tests__/contracts.test.ts
index c9925969a..508beca3b 100644
--- a/packages/types/__tests__/contracts.test.ts
+++ b/packages/types/__tests__/contracts.test.ts
@@ -15,7 +15,7 @@
* raw entries with a `path` key must adapt before assignment.
*/
-import { describe, expectTypeOf, it } from "vitest";
+import { describe, expect, expectTypeOf, it } from "vitest";
import type {
ChatArtifact,
KnownChatArtifact,
@@ -34,6 +34,11 @@ import type {
SymbolHeritage,
} from "../src/symbols.js";
import type { SecurityFinding, SecuritySeverity } from "../src/security.js";
+import {
+ C4_IO_KINDS,
+ type C4IoKind,
+ type ExternalSystemEntry,
+} from "../src/external-systems.js";
describe("ChatArtifact discriminated union", () => {
it("narrows on .type to the per-variant data shape", () => {
@@ -176,3 +181,40 @@ describe("Canonical Hotspot key shape", () => {
expectTypeOf<RawPathHotspot>().not.toMatchTypeOf<Hotspot>();
});
});
+
+describe("C4 io_kind parity", () => {
+ // Cross-language guard: these five values are the canonical IO_KINDS in the
+ // Python classifier (ingestion/external_systems/io_kind.py). The Python half
+ // (tests/unit/ingestion/test_io_kind.py) asserts the same membership; if one
+ // side adds/removes/renames a kind without the other, one snapshot fails CI.
+ it("freezes the boundary-kind set", () => {
+ expect([...C4_IO_KINDS]).toEqual([
+ "db",
+ "network",
+ "filesystem",
+ "subprocess",
+ "lock",
+ ]);
+ });
+
+ it("derives C4IoKind from the runtime tuple", () => {
+ expectTypeOf<C4IoKind>().toEqualTypeOf<
+ "db" | "network" | "filesystem" | "subprocess" | "lock"
+ >();
+ });
+
+ it("keeps io_kind nullable on the registry entry", () => {
+ // A row with a null io_kind (untyped dep) must still satisfy the contract.
+ const untyped: ExternalSystemEntry = {
+ name: "left-pad",
+ display_name: "Left Pad",
+ ecosystem: "npm",
+ category: "library",
+ io_kind: null,
+ version: "1.0.0",
+ declared_in: "package.json",
+ is_dev_dep: false,
+ };
+ expect(untyped.io_kind).toBeNull();
+ });
+});
diff --git a/packages/types/src/external-systems.ts b/packages/types/src/external-systems.ts
index abc865afc..eb2a26d42 100644
--- a/packages/types/src/external-systems.ts
+++ b/packages/types/src/external-systems.ts
@@ -4,6 +4,24 @@
* `/api/repos/{id}/external-systems`.
*/
+/**
+ * Canonical I/O-boundary kinds. Mirrors `IO_KINDS` in the Python classifier
+ * (`packages/core/.../ingestion/external_systems/io_kind.py`). The cross-
+ * language parity guard lives in `__tests__/contracts.test.ts` (TS half) and
+ * `tests/unit/ingestion/test_io_kind.py` (Python half). Change one, change
+ * all three.
+ */
+export const C4_IO_KINDS = [
+ "db",
+ "network",
+ "filesystem",
+ "subprocess",
+ "lock",
+] as const;
+
+/** A dependency's I/O-boundary type, or null when it isn't typed. */
+export type C4IoKind = (typeof C4_IO_KINDS)[number];
+
/** One declared third-party dependency. */
export interface ExternalSystemEntry {
name: string;
@@ -12,6 +30,8 @@ export interface ExternalSystemEntry {
ecosystem: string;
/** framework | service | tool | library */
category: string;
+ /** db | network | filesystem | subprocess | lock, or null when untyped. */
+ io_kind: C4IoKind | null;
version: string | null;
/** Manifest path the dependency was declared in, e.g. "packages/web/package.json". */
declared_in: string;
diff --git a/packages/ui/src/c4/nodes/ExternalSystemNode.tsx b/packages/ui/src/c4/nodes/ExternalSystemNode.tsx
index da8d2a51e..374df1d96 100644
--- a/packages/ui/src/c4/nodes/ExternalSystemNode.tsx
+++ b/packages/ui/src/c4/nodes/ExternalSystemNode.tsx
@@ -1,7 +1,16 @@
"use client";
import { memo } from "react";
-import { Box, Cloud, Wrench, Library } from "lucide-react";
+import {
+ Box,
+ Cloud,
+ Database,
+ FolderOpen,
+ Library,
+ Lock,
+ Terminal,
+ Wrench,
+} from "lucide-react";
import type { NodeProps } from "@xyflow/react";
import { NodeShell } from "./node-shell";
import type { C4ExternalSystem } from "../types";
@@ -10,6 +19,32 @@ export interface ExternalSystemNodeProps {
external: C4ExternalSystem;
}
+/** Human label for the typed boundary, shown in place of the coarse category. */
+const IO_KIND_LABEL: Record<string, string> = {
+ db: "Database",
+ network: "External API",
+ filesystem: "Filesystem",
+ subprocess: "Subprocess",
+ lock: "Lock",
+};
+
+function ioKindIcon(ioKind: string) {
+ switch (ioKind) {
+ case "db":
+ return Database;
+ case "network":
+ return Cloud;
+ case "filesystem":
+ return FolderOpen;
+ case "subprocess":
+ return Terminal;
+ case "lock":
+ return Lock;
+ default:
+ return Library;
+ }
+}
+
function categoryIcon(category: string) {
switch (category) {
case "service":
@@ -26,12 +61,15 @@ function categoryIcon(category: string) {
function ExternalSystemNodeImpl(props: NodeProps) {
const { data, selected } = props as NodeProps & { data: ExternalSystemNodeProps };
const { external } = data;
- const Icon = categoryIcon(external.category);
+ // Prefer the typed boundary; fall back to the coarse category when untyped.
+ const ioKind = external.io_kind ?? null;
+ const Icon = ioKind ? ioKindIcon(ioKind) : categoryIcon(external.category);
+ const kindLabel = (ioKind && IO_KIND_LABEL[ioKind]) || external.category || "external";
const version = external.version ? `v${external.version.replace(/^[\^~]/, "")}` : null;
return (
<NodeShell
tone="external"
- kindLabel={external.category || "external"}
+ kindLabel={kindLabel}
title={external.display_name || external.name}
subtitle={external.ecosystem}
selected={selected}
diff --git a/packages/ui/src/c4/types.ts b/packages/ui/src/c4/types.ts
index 41a222ee7..88b434538 100644
--- a/packages/ui/src/c4/types.ts
+++ b/packages/ui/src/c4/types.ts
@@ -8,6 +8,9 @@ export type C4Level = 1 | 2 | 3;
export type C4Category = "framework" | "service" | "tool" | "library";
+/** I/O-boundary type of an external dependency (mirrors backend `io_kind`). */
+export type C4IoKind = "db" | "network" | "filesystem" | "subprocess" | "lock";
+
export interface C4Person {
id: string;
name: string;
@@ -27,6 +30,8 @@ export interface C4ExternalSystem {
category: C4Category | string;
ecosystem: string;
version: string | null;
+ /** Boundary type, or null when the dependency isn't in the io_kind table. */
+ io_kind?: C4IoKind | string | null;
}
export interface C4Container {
diff --git a/tests/unit/ingestion/external_systems/test_npm.py b/tests/unit/ingestion/external_systems/test_npm.py
index 577075ab3..85d36a4e6 100644
--- a/tests/unit/ingestion/external_systems/test_npm.py
+++ b/tests/unit/ingestion/external_systems/test_npm.py
@@ -42,6 +42,25 @@ def test_parses_dependencies_and_dev_dependencies(tmp_path):
assert vitest.category == "tool"
+def test_io_kind_is_wired_through_the_parser(tmp_path):
+ manifest = _write(
+ tmp_path,
+ "package.json",
+ {
+ "dependencies": {
+ "axios": "^1.0.0",
+ "@prisma/client": "^5.0.0",
+ "react": "^18.0.0",
+ },
+ },
+ )
+ records = {r.name: r for r in npm.parse(manifest, tmp_path)}
+ assert records["axios"].io_kind == "network"
+ assert records["@prisma/client"].io_kind == "db"
+ # An untyped dependency carries None, not a guess.
+ assert records["react"].io_kind is None
+
+
def test_handles_malformed_json_without_raising(tmp_path):
p = tmp_path / "package.json"
p.write_text("{ not valid", encoding="utf-8")
diff --git a/tests/unit/ingestion/test_io_kind.py b/tests/unit/ingestion/test_io_kind.py
new file mode 100644
index 000000000..47de85cca
--- /dev/null
+++ b/tests/unit/ingestion/test_io_kind.py
@@ -0,0 +1,74 @@
+"""Unit tests for the shared I/O-boundary classifier.
+
+The classifier is a shared primitive (C4 today; perf / security later), so the
+contract is narrow and explicit: a curated name maps to its boundary kind, an
+unknown name maps to ``None`` (never a guess), and the value set is frozen and
+mirrored in TypeScript.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.ingestion.external_systems.io_kind import (
+ IO_KINDS,
+ classify_io_kind,
+)
+
+
+def test_io_kinds_are_the_frozen_canonical_set() -> None:
+ # Cross-language parity guard: the TS mirror (C4_IO_KINDS) and
+ # packages/types/__tests__/contracts.test.ts assert the same membership.
+ assert IO_KINDS == ("db", "network", "filesystem", "subprocess", "lock")
+
+
+ ("name", "expected"),
+ [
+ # Python network
+ ("httpx", "network"),
+ ("requests", "network"),
+ ("aiohttp", "network"),
+ ("socket", "network"),
+ # Python db
+ ("sqlalchemy", "db"),
+ ("psycopg", "db"),
+ ("asyncpg", "db"),
+ ("redis", "db"),
+ ("pymongo", "db"),
+ # Python subprocess / filesystem / lock (stdlib-ish)
+ ("subprocess", "subprocess"),
+ ("open", "filesystem"),
+ ("filelock", "lock"),
+ # TS / Node network
+ ("axios", "network"),
+ ("node-fetch", "network"),
+ # TS / Node db
+ ("@prisma/client", "db"),
+ ("drizzle-orm", "db"),
+ ("knex", "db"),
+ ("pg", "db"),
+ ("mongoose", "db"),
+ # TS / Node filesystem / subprocess
+ ("node:fs", "filesystem"),
+ ("child_process", "subprocess"),
+ ],
+)
+def test_known_libs_map_to_expected_io_kind(name: str, expected: str) -> None:
+ assert classify_io_kind(name) == expected
+ # Every produced value must be a member of the canonical set.
+ assert classify_io_kind(name) in IO_KINDS
+
+
+ "name",
+ ["", "left-pad", "lodash", "numpy", "pytest", "react", "some-unknown-pkg"],
+)
+def test_unknown_or_non_io_libs_return_none(name: str) -> None:
+ assert classify_io_kind(name) is None
+
+
+def test_classification_is_case_and_whitespace_insensitive() -> None:
+ assert classify_io_kind("HTTPX") == "network"
+ assert classify_io_kind(" SQLAlchemy ") == "db"
+ assert classify_io_kind("@Prisma/Client") == "db"