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(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.pynew file mode 100644index 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.pyindex 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 = Nonedisplay_name: str = ""category: str = "library" # populated by classifier+ io_kind: str | None = None # populated by io_kind classifier; None = untypedis_dev_dep: bool = Falseextras: 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.pyindex 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.11from .base import ExternalSystemRecordfrom .classifier import classify, display_name_for+from .io_kind import classify_io_kindfilenames: 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.pyindex 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 Pathfrom .base import ExternalSystemRecordfrom .classifier import classify, display_name_for+from .io_kind import classify_io_kindfilenames: 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.pynew file mode 100644index 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.pyindex 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 Pathfrom .base import ExternalSystemRecordfrom .classifier import classify, display_name_for+from .io_kind import classify_io_kindfilenames: 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.pyindex 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 Pathfrom .base import ExternalSystemRecordfrom .classifier import classify, display_name_for+from .io_kind import classify_io_kindfilenames: 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.pyindex 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 ETfrom .base import ExternalSystemRecordfrom .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.pyindex 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.11from .base import ExternalSystemRecordfrom .classifier import classify, display_name_for+from .io_kind import classify_io_kindfilenames: 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.pyindex 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.pyindex 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.pyindex 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.pyindex 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 | libraryecosystem: strversion: str | None = None+ io_kind: str | None = None # db | network | filesystem | subprocess | lock | nullclass C4ContainerResponse(BaseModel):diff --git a/packages/server/src/repowise/server/schemas/external_systems.py b/packages/server/src/repowise/server/schemas/external_systems.pyindex 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: strecosystem: str # npm | pypi | cargo | gomod | nuget | ...category: str # framework | service | tool | library+ io_kind: str | None = None # db | network | filesystem | subprocess | lock | nullversion: str | None = Nonedeclared_in: str # manifest path, e.g. "packages/web/package.json"is_dev_dep: bool = Falsediff --git a/packages/server/src/repowise/server/services/c4_builder/__init__.py b/packages/server/src/repowise/server/services/c4_builder/__init__.pyindex 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_iddiff --git a/packages/server/src/repowise/server/services/c4_builder/architecture.py b/packages/server/src/repowise/server/services/c4_builder/architecture.pyindex 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 viewsdiff --git a/packages/server/src/repowise/server/services/c4_builder/mermaid.py b/packages/server/src/repowise/server/services/c4_builder/mermaid.pyindex 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.pyindex 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 | libraryecosystem: strversion: 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.pyindex 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.tsindex 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.tsindex 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.tsxindex 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 (<NodeShelltone="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.tsindex 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.pyindex 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.pynew file mode 100644index 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"