ekklesiaandClaude Opus 5
44e676f0df
Two gaps stood between the module UI contract and a host that could use
it. ADR 0023 recorded the first honestly but never diagnosed it: a module
UI file compiled with `"types": []` could still typecheck `process.env`.
The second was simply missing — nothing imported a compiled artifact,
checked its identity, mounted it, or tore it down.
The leak was one type-only import, bisected against the real type graph
rather than guessed. `@ekklesia/module-ui-sdk` imported
`type { EkklesiaPrincipal } from "@ekklesia/contracts"`. Importing
contracts/identity alone is clean and importing Zod alone is clean, but
contracts exposes a single barrel entry, so that one import reached
module-database, whose Drizzle types re-introduce Node's globals. The
runtime was never affected — the import was erased and host-context.js is
`export {}` — but a type-graph leak is still a real boundary failure,
because it silently permits code that cannot run in its target
environment.
The fix is not a narrower import path. The SDK now has no dependencies at
all, so there is no graph to leak through and no future contracts change
can reopen this. It owns `ModuleUiPrincipal`: the same shape ADR 0022
chose, with the Zod brand dropped. That brand encodes a server-side
parsing guarantee a browser cannot produce, and it is the same reason
`permissions.has` already took a plain string. An Ekklesia host still
passes its own `EkklesiaPrincipal` straight through — a branded string is
assignable to `string` — while a standalone host builds the literal.
Proven the way an author experiences it: two fixtures compiled under the
exact project a module uses, one supported and one deliberately reaching
for `process`, with the second required to fail on that specific name.
`@ekklesia/module-ui-host` is the generic loader, in its own package
because the SDK is bundled into every module artifact and host-only
loader code has no business shipping there. The boundary checker enforces
both directions: modules may not depend on the loader, and the loader may
depend only on the SDK plus dev-time tooling.
The distinction that shaped the design: Core resolves `entrypoints.ui` to
an absolute path on the server's disk, and a browser needs a URL. A
loader that accepted the path would test green on a server and fail in
every real host, and would quietly own asset publication. So the loader
takes a browser-loadable URL and knows nothing about how one is obtained.
Ekklesia has no route that publishes installed artifacts, so this is
precisely: loader complete, publication deferred. Nothing can mount an
installed module UI yet, and the docs say so rather than implying
otherwise.
Dynamic import is `(url) => import(url)` with a non-analyzable specifier,
kept as a runtime import so a host does not statically bundle every
installed module or need a hardcoded registry. It is injectable for
bundlers needing their own escape hatch, and deliberately not `eval` or
`new Function`, which would cost a host `unsafe-eval` in its CSP.
Identity is validated through the SDK's existing parser before `mount`
runs, so a stale or mismatched bundle never renders. Contract violations
propagate unwrapped; the loader adds only import and mount failure codes,
sanitized, with the cause attached. Unmount is idempotent, safe when a
module returned no cleanup, and marks an instance unmounted before
running cleanup so a throwing cleanup surfaces once and never re-runs. A
failed mount registers no cleanup. Each instance owns its own state, so
two mounts coexist. The loader never mutates the host's container — not
on success, failure, or unmount.
Tests prove all of it against real module URLs (`data:`, which both
browsers and Node import natively) rather than filesystem paths,
including one artifact built by the canonical Pass 2 pipeline and run
under both an Ekklesia-shaped and a standalone-shaped context. Core,
apps/api, and the contracts package are untouched; discovery remains
inert.
Co-Authored-By: Claude Opus 5 <[email protected]>
188 lines
8.7 KiB
TypeScript
188 lines
8.7 KiB
TypeScript
import path from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import { describe, expect, it } from "vitest";
|
|
import { checkBoundaries } from "../scripts/check-boundaries.js";
|
|
|
|
const testDirectory = path.dirname(fileURLToPath(import.meta.url));
|
|
const fixtures = path.join(testDirectory, "fixtures", "boundaries");
|
|
|
|
describe("repository dependency boundaries", () => {
|
|
it("accepts public contracts below Core", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "legal"));
|
|
expect(result.violations).toEqual([]);
|
|
});
|
|
|
|
it("accepts generated module composition only through the generated bootstrap boundary", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "legal-generated-bootstrap"));
|
|
expect(result.violations).toEqual([]);
|
|
});
|
|
|
|
it("honors explicit pnpm workspace exclusions", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "workspace-exclusion"));
|
|
expect(result.violations).toEqual([]);
|
|
});
|
|
|
|
it.each([
|
|
["core-imports-module", "core-is-feature-agnostic"],
|
|
["app-imports-module", "apps-are-composition-roots"],
|
|
["module-imports-core", "modules-use-public-platform-contracts"],
|
|
["module-imports-surface", "modules-use-public-platform-contracts"],
|
|
["package-boundary-direction", "modules-use-public-platform-contracts"],
|
|
["cross-module-import", "modules-do-not-import-other-modules"],
|
|
["module-schema-imports-module", "modules-do-not-import-other-modules"],
|
|
["surface-imports-module", "surfaces-use-public-contracts"],
|
|
["cross-surface-import", "surfaces-are-independent"],
|
|
["builder-imports-module", "builder-composes-contracts"],
|
|
["contracts-import-core", "contracts-do-not-depend-upward"],
|
|
["sdk-imports-core", "sdks-do-not-depend-on-implementations"],
|
|
["shared-role-order", "sdks-do-not-depend-on-implementations"],
|
|
["package-without-exports", "workspace-imports-use-public-exports"],
|
|
["private-package-import", "workspace-imports-use-public-exports"],
|
|
["non-workspace-version", "internal-dependencies-use-workspace-protocol"],
|
|
["workspace-alias", "workspace-dependency-aliases-are-forbidden"],
|
|
["undeclared-workspace-dependency", "workspace-dependencies-are-declared"],
|
|
["duplicate-package-name", "workspace-package-names-are-unique"],
|
|
["unknown-shared-role", "shared-packages-declare-known-roles"],
|
|
["workspace-unsupported-pattern", "workspace-patterns-use-supported-syntax"],
|
|
["package-cycle", "no-circular-package-dependencies"],
|
|
["module-has-ui", "modules-do-not-own-ui"],
|
|
["module-ui-framework", "modules-do-not-own-ui"],
|
|
["module-ui-aliased-framework", "modules-do-not-own-ui"],
|
|
["module-ui-imports-core", "modules-use-public-platform-contracts"],
|
|
["module-ui-bundler-plugin", "modules-do-not-own-ui"],
|
|
["module-imports-ui-host", "modules-use-public-platform-contracts"],
|
|
["module-imports-ui-package", "modules-use-public-platform-contracts"],
|
|
["cross-package-relative", "workspace-imports-use-public-exports"],
|
|
["cycle", "no-circular-source-dependencies"],
|
|
])("rejects %s", async (fixture, expectedRule) => {
|
|
const result = await checkBoundaries(path.join(fixtures, fixture));
|
|
expect(result.violations.map((violation) => violation.rule)).toContain(expectedRule);
|
|
});
|
|
|
|
it("rejects stylesheet and case-insensitive view files inside a module, but not TSX", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "module-has-ui"));
|
|
const uiViolations = result.violations.filter(
|
|
(violation) => violation.rule === "modules-do-not-own-ui",
|
|
);
|
|
|
|
expect(uiViolations).toHaveLength(2);
|
|
expect(uiViolations.map((violation) => violation.from)).toEqual(
|
|
expect.arrayContaining([
|
|
"modules/calendar/src/calendar.css",
|
|
"modules/calendar/src/view.ASTRO",
|
|
]),
|
|
);
|
|
// React is the supported module UI authoring model (ADR 0022), so a module's own `.tsx` is
|
|
// legitimate source and must no longer be reported.
|
|
expect(uiViolations.map((violation) => violation.from)).not.toContain(
|
|
"modules/calendar/src/calendar.tsx",
|
|
);
|
|
});
|
|
|
|
it("rejects unsupported UI frameworks, their imports, and view formats inside a module", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "module-ui-framework"));
|
|
const uiViolations = result.violations.filter(
|
|
(violation) => violation.rule === "modules-do-not-own-ui",
|
|
);
|
|
|
|
expect(uiViolations).toHaveLength(3);
|
|
expect(uiViolations.map((violation) => violation.message)).toEqual(
|
|
expect.arrayContaining([
|
|
"Module package depends on UI framework preact.",
|
|
"Module source imports UI framework preact.",
|
|
]),
|
|
);
|
|
// The fixture also aliases `compat` to react, which is now the supported framework and is
|
|
// therefore no longer a violation.
|
|
expect(uiViolations.map((violation) => violation.message).join(" ")).not.toContain("compat");
|
|
});
|
|
|
|
it("still rejects module UI source that reaches into Core internals", async () => {
|
|
// Allowing `.tsx` inside a module changed which *formats* a module may contain. It did not
|
|
// change which layers a module may import: module UI is subject to the identical layer rules
|
|
// as module backend source.
|
|
const result = await checkBoundaries(path.join(fixtures, "module-ui-imports-core"));
|
|
|
|
expect(result.violations).toEqual([
|
|
{
|
|
from: "modules/announcements/src/ui/editor.tsx",
|
|
message: "module code may not import core code directly.",
|
|
rule: "modules-use-public-platform-contracts",
|
|
to: "core/src/index.ts",
|
|
},
|
|
]);
|
|
});
|
|
|
|
it("accepts the canonical module UI dependency set: React, the UI SDK, and the build tool", async () => {
|
|
// Mirrors what `templates/module` actually declares (ADR 0023). The build tool is a `tooling`
|
|
// shared package, a role modules were already permitted to depend on, so the module UI build
|
|
// pipeline required no boundary relaxation at all.
|
|
const result = await checkBoundaries(path.join(fixtures, "module-owns-react-ui"));
|
|
|
|
expect(result.violations).toEqual([]);
|
|
});
|
|
|
|
it("keeps the host loader out of module packages", async () => {
|
|
// `@ekklesia/module-ui-host` is host infrastructure. A module that depended on it would bundle
|
|
// loader code into its own artifact and blur the author/host split (ADR 0024), so the
|
|
// `module-ui-host` role is deliberately absent from the roles a module may depend on.
|
|
const result = await checkBoundaries(path.join(fixtures, "module-imports-ui-host"));
|
|
|
|
expect(result.violations.map((violation) => violation.rule)).toEqual([
|
|
"modules-use-public-platform-contracts",
|
|
"modules-use-public-platform-contracts",
|
|
]);
|
|
});
|
|
|
|
it("still rejects a module reaching for a bundler plugin ecosystem", async () => {
|
|
// Module authors do not configure a bundler; `@ekklesia/module-ui-build` owns that entirely.
|
|
const result = await checkBoundaries(path.join(fixtures, "module-ui-bundler-plugin"));
|
|
|
|
expect(result.violations.map((violation) => violation.message)).toEqual([
|
|
"Module package depends on UI framework @vitejs/plugin-react.",
|
|
]);
|
|
});
|
|
|
|
it("rejects an unsupported framework aliased behind the supported one", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "module-ui-aliased-framework"));
|
|
|
|
expect(result.violations.map((violation) => violation.message)).toEqual([
|
|
"Module package depends on UI framework vue aliased as react.",
|
|
]);
|
|
});
|
|
|
|
it("requires workspace: ranges in every dependency field", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "non-workspace-version"));
|
|
expect(
|
|
result.violations.filter(
|
|
(violation) => violation.rule === "internal-dependencies-use-workspace-protocol",
|
|
),
|
|
).toHaveLength(4);
|
|
});
|
|
|
|
it("resolves forbidden workspace aliases before applying layer rules", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "workspace-alias"));
|
|
expect(
|
|
result.violations.filter(
|
|
(violation) => violation.rule === "workspace-dependency-aliases-are-forbidden",
|
|
),
|
|
).toHaveLength(2);
|
|
expect(result.violations.map((violation) => violation.rule)).toEqual(
|
|
expect.arrayContaining([
|
|
"workspace-dependency-aliases-are-forbidden",
|
|
"modules-use-public-platform-contracts",
|
|
]),
|
|
);
|
|
});
|
|
|
|
it("prevents contracts and SDKs from depending upward through shared packages", async () => {
|
|
const result = await checkBoundaries(path.join(fixtures, "shared-role-order"));
|
|
expect(result.violations.map((violation) => violation.rule)).toEqual(
|
|
expect.arrayContaining([
|
|
"contracts-do-not-depend-upward",
|
|
"sdks-do-not-depend-on-implementations",
|
|
]),
|
|
);
|
|
});
|
|
});
|