489 lines
16 KiB
TypeScript
489 lines
16 KiB
TypeScript
import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
|
|
import { tmpdir } from "node:os";
|
|
import path from "node:path";
|
|
import { afterEach, describe, expect, it } from "vitest";
|
|
import {
|
|
discoverModules,
|
|
ModuleDiscoveryError,
|
|
type ModuleDiscoveryIssueCode,
|
|
} from "../src/modules/index.js";
|
|
|
|
interface ModuleFixtureOptions {
|
|
directory?: string;
|
|
manifest?: Record<string, unknown>;
|
|
packageJson?: Record<string, unknown>;
|
|
serverSource?: string;
|
|
}
|
|
|
|
const temporaryDirectories: string[] = [];
|
|
|
|
afterEach(async () => {
|
|
await Promise.all(
|
|
temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true })),
|
|
);
|
|
});
|
|
|
|
async function createModulesDirectory(): Promise<string> {
|
|
const directory = await mkdtemp(path.join(tmpdir(), "ekklesia-modules-"));
|
|
temporaryDirectories.push(directory);
|
|
return directory;
|
|
}
|
|
|
|
function manifestFor(id: string): Record<string, unknown> {
|
|
return {
|
|
manifestVersion: 2,
|
|
id,
|
|
name: `${id} module`,
|
|
version: "0.1.0",
|
|
compatibility: {
|
|
platform: "^0.1.0",
|
|
moduleSdk: "^0.1.0",
|
|
},
|
|
capabilities: [{ id: `${id}.records`, version: "1.0.0" }],
|
|
permissions: [`${id}.records.read`],
|
|
entrypoints: {
|
|
server: "./dist/server/index.js",
|
|
},
|
|
};
|
|
}
|
|
|
|
async function createModule(
|
|
modulesDirectory: string,
|
|
id: string,
|
|
options: ModuleFixtureOptions = {},
|
|
): Promise<void> {
|
|
const directoryName = options.directory ?? id;
|
|
const moduleDirectory = path.join(modulesDirectory, directoryName);
|
|
const manifest = options.manifest ?? manifestFor(id);
|
|
const packageJson = options.packageJson ?? {
|
|
name: `@test/module-${id}`,
|
|
version: "0.1.0",
|
|
type: "module",
|
|
ekklesia: { layer: "module" },
|
|
};
|
|
|
|
await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
|
|
await Promise.all([
|
|
writeFile(path.join(moduleDirectory, "package.json"), JSON.stringify(packageJson)),
|
|
writeFile(path.join(moduleDirectory, "ekklesia.module.json"), JSON.stringify(manifest)),
|
|
writeFile(
|
|
path.join(moduleDirectory, "dist/server/index.js"),
|
|
options.serverSource ?? `export default { id: ${JSON.stringify(id)}, version: "0.1.0" };`,
|
|
),
|
|
]);
|
|
}
|
|
|
|
async function discoveryError(
|
|
modulesDirectory: string,
|
|
versions: { moduleSdkVersion?: string; platformVersion?: string } = {},
|
|
): Promise<ModuleDiscoveryError> {
|
|
try {
|
|
await discoverModules({
|
|
moduleSdkVersion: versions.moduleSdkVersion ?? "0.1.0",
|
|
modulesDirectory,
|
|
platformVersion: versions.platformVersion ?? "0.1.0",
|
|
});
|
|
} catch (error) {
|
|
if (error instanceof ModuleDiscoveryError) {
|
|
return error;
|
|
}
|
|
throw error;
|
|
}
|
|
throw new Error("Expected module discovery to fail.");
|
|
}
|
|
|
|
function issueCodes(error: ModuleDiscoveryError): ModuleDiscoveryIssueCode[] {
|
|
return error.issues.map((issue) => issue.code);
|
|
}
|
|
|
|
describe("module discovery", () => {
|
|
it("treats a missing or empty modules directory as zero installed modules", async () => {
|
|
const parent = await createModulesDirectory();
|
|
const missing = path.join(parent, "missing");
|
|
|
|
await expect(
|
|
discoverModules({
|
|
moduleSdkVersion: "0.1.0",
|
|
modulesDirectory: missing,
|
|
platformVersion: "0.1.0",
|
|
}),
|
|
).resolves.toEqual([]);
|
|
await expect(
|
|
discoverModules({
|
|
moduleSdkVersion: "0.1.0",
|
|
modulesDirectory: parent,
|
|
platformVersion: "0.1.0",
|
|
}),
|
|
).resolves.toEqual([]);
|
|
});
|
|
|
|
it("discovers static manifests and orders dependencies deterministically", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "calendar", {
|
|
manifest: {
|
|
...manifestFor("calendar"),
|
|
dependencies: {
|
|
modules: { required: { people: "^0.1.0" } },
|
|
capabilities: { required: { "people.records": "^2.0.0" } },
|
|
},
|
|
storage: { buckets: [{ id: "assets" }, { id: "exports" }] },
|
|
},
|
|
serverSource: 'throw new Error("discovery must never execute server code");',
|
|
});
|
|
await createModule(modulesDirectory, "people", {
|
|
manifest: {
|
|
...manifestFor("people"),
|
|
capabilities: [{ id: "people.records", version: "2.1.0" }],
|
|
},
|
|
});
|
|
|
|
const modules = await discoverModules({
|
|
moduleSdkVersion: "0.1.0",
|
|
modulesDirectory,
|
|
platformVersion: "0.1.0",
|
|
});
|
|
|
|
expect(modules.map((module) => module.manifest.id)).toEqual(["people", "calendar"]);
|
|
expect(modules[1]?.manifest.storage.buckets.map((bucket) => bucket.id)).toEqual([
|
|
"assets",
|
|
"exports",
|
|
]);
|
|
expect(Object.isFrozen(modules[1]?.manifest)).toBe(true);
|
|
const mutableBuckets = modules[1]?.manifest.storage.buckets as unknown as Array<{ id: string }>;
|
|
expect(() => mutableBuckets.push({ id: "tampered" })).toThrow(TypeError);
|
|
});
|
|
|
|
it("aggregates malformed packages and manifests without partial discovery", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await mkdir(path.join(modulesDirectory, "missing"));
|
|
await createModule(modulesDirectory, "invalid", {
|
|
manifest: { ...manifestFor("invalid"), renderers: ["not-allowed"] },
|
|
packageJson: {
|
|
name: "@test/module-invalid",
|
|
version: "not-semver",
|
|
type: "commonjs",
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
|
|
expect(issueCodes(error)).toEqual(
|
|
expect.arrayContaining([
|
|
"MODULE_MANIFEST_INVALID",
|
|
"MODULE_MANIFEST_MISSING",
|
|
"MODULE_PACKAGE_INVALID",
|
|
"MODULE_PACKAGE_MISSING",
|
|
]),
|
|
);
|
|
});
|
|
|
|
it("aggregates malformed JSON without exposing machine-specific paths", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
const moduleDirectory = path.join(modulesDirectory, "broken-json");
|
|
await mkdir(moduleDirectory);
|
|
await Promise.all([
|
|
writeFile(path.join(moduleDirectory, "package.json"), "{"),
|
|
writeFile(path.join(moduleDirectory, "ekklesia.module.json"), "["),
|
|
]);
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toEqual(
|
|
expect.arrayContaining(["MODULE_MANIFEST_INVALID", "MODULE_PACKAGE_INVALID"]),
|
|
);
|
|
expect(error.issues.every((issue) => !issue.message.includes(modulesDirectory))).toBe(true);
|
|
});
|
|
|
|
it("requires package and manifest versions to match", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "mismatch", {
|
|
packageJson: {
|
|
name: "@test/module-mismatch",
|
|
version: "0.2.0",
|
|
type: "module",
|
|
ekklesia: { layer: "module" },
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_VERSION_MISMATCH");
|
|
});
|
|
|
|
it("rejects duplicate module IDs and package names", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "one", {
|
|
manifest: {
|
|
...manifestFor("one"),
|
|
id: "shared",
|
|
capabilities: [{ id: "shared.records", version: "1.0.0" }],
|
|
permissions: ["shared.records.read"],
|
|
},
|
|
packageJson: {
|
|
name: "@test/duplicate",
|
|
version: "0.1.0",
|
|
type: "module",
|
|
ekklesia: { layer: "module" },
|
|
},
|
|
});
|
|
await createModule(modulesDirectory, "two", {
|
|
manifest: {
|
|
...manifestFor("two"),
|
|
id: "shared",
|
|
capabilities: [{ id: "shared.records", version: "1.0.0" }],
|
|
permissions: ["shared.records.read"],
|
|
},
|
|
packageJson: {
|
|
name: "@test/duplicate",
|
|
version: "0.1.0",
|
|
type: "module",
|
|
ekklesia: { layer: "module" },
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
|
|
expect(issueCodes(error)).toEqual(
|
|
expect.arrayContaining(["MODULE_ID_DUPLICATE", "MODULE_PACKAGE_NAME_DUPLICATE"]),
|
|
);
|
|
});
|
|
|
|
it("enforces platform and Module SDK compatibility", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "future", {
|
|
manifest: {
|
|
...manifestFor("future"),
|
|
compatibility: { platform: ">=1.0.0", moduleSdk: ">=2.0.0" },
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
|
|
expect(issueCodes(error)).toEqual(
|
|
expect.arrayContaining(["MODULE_PLATFORM_INCOMPATIBLE", "MODULE_SDK_INCOMPATIBLE"]),
|
|
);
|
|
});
|
|
|
|
it("allows missing optional dependencies but rejects missing required dependencies", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "optional-consumer", {
|
|
manifest: {
|
|
...manifestFor("optional-consumer"),
|
|
dependencies: { modules: { optional: { absent: "^1.0.0" } } },
|
|
},
|
|
});
|
|
|
|
await expect(
|
|
discoverModules({
|
|
moduleSdkVersion: "0.1.0",
|
|
modulesDirectory,
|
|
platformVersion: "0.1.0",
|
|
}),
|
|
).resolves.toHaveLength(1);
|
|
|
|
await createModule(modulesDirectory, "required-consumer", {
|
|
manifest: {
|
|
...manifestFor("required-consumer"),
|
|
dependencies: { modules: { required: { absent: "^1.0.0" } } },
|
|
},
|
|
});
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_DEPENDENCY_MISSING");
|
|
});
|
|
|
|
it("rejects installed dependencies with incompatible versions", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "people");
|
|
await createModule(modulesDirectory, "calendar", {
|
|
manifest: {
|
|
...manifestFor("calendar"),
|
|
dependencies: { modules: { optional: { people: "^2.0.0" } } },
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_DEPENDENCY_INCOMPATIBLE");
|
|
});
|
|
|
|
it("allows absent optional capabilities but rejects missing required capabilities", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "optional-consumer", {
|
|
manifest: {
|
|
...manifestFor("optional-consumer"),
|
|
dependencies: { capabilities: { optional: { "people.records": "^1.0.0" } } },
|
|
},
|
|
});
|
|
await expect(
|
|
discoverModules({
|
|
moduleSdkVersion: "0.1.0",
|
|
modulesDirectory,
|
|
platformVersion: "0.1.0",
|
|
}),
|
|
).resolves.toHaveLength(1);
|
|
|
|
await createModule(modulesDirectory, "consumer", {
|
|
manifest: {
|
|
...manifestFor("consumer"),
|
|
dependencies: { capabilities: { required: { "people.records": "^1.0.0" } } },
|
|
},
|
|
});
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_CAPABILITY_MISSING");
|
|
});
|
|
|
|
it("rejects incompatible installed required and optional capabilities", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "people");
|
|
await createModule(modulesDirectory, "required-consumer", {
|
|
manifest: {
|
|
...manifestFor("required-consumer"),
|
|
dependencies: { capabilities: { required: { "people.records": "^2.0.0" } } },
|
|
},
|
|
});
|
|
await createModule(modulesDirectory, "optional-consumer", {
|
|
manifest: {
|
|
...manifestFor("optional-consumer"),
|
|
dependencies: { capabilities: { optional: { "people.records": "^3.0.0" } } },
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
const incompatibilities = error.issues.filter(
|
|
(issue) => issue.code === "MODULE_CAPABILITY_INCOMPATIBLE",
|
|
);
|
|
expect(incompatibilities).toHaveLength(2);
|
|
expect(incompatibilities).toEqual(
|
|
expect.arrayContaining([
|
|
expect.objectContaining({
|
|
message: "Capability people.records 1.0.0 does not satisfy ^2.0.0.",
|
|
path: "dependencies.capabilities.required.people.records",
|
|
}),
|
|
expect.objectContaining({
|
|
message: "Capability people.records 1.0.0 does not satisfy ^3.0.0.",
|
|
path: "dependencies.capabilities.optional.people.records",
|
|
}),
|
|
]),
|
|
);
|
|
});
|
|
|
|
it("detects dependency cycles", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "one", {
|
|
manifest: {
|
|
...manifestFor("one"),
|
|
dependencies: { modules: { required: { two: "^0.1.0" } } },
|
|
},
|
|
});
|
|
await createModule(modulesDirectory, "two", {
|
|
manifest: {
|
|
...manifestFor("two"),
|
|
dependencies: { modules: { required: { one: "^0.1.0" } } },
|
|
},
|
|
});
|
|
await createModule(modulesDirectory, "three", {
|
|
manifest: {
|
|
...manifestFor("three"),
|
|
dependencies: { modules: { required: { two: "^0.1.0" } } },
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_DEPENDENCY_CYCLE");
|
|
expect(error.issues.find((issue) => issue.code === "MODULE_DEPENDENCY_CYCLE")?.message).toBe(
|
|
"Module dependency cycle contains: one, two.",
|
|
);
|
|
});
|
|
|
|
it("rejects missing entrypoint targets and invalid caller versions", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "missing-server", {
|
|
manifest: {
|
|
...manifestFor("missing-server"),
|
|
entrypoints: { server: "./dist/server/missing.js" },
|
|
},
|
|
});
|
|
|
|
let error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_ENTRYPOINT_MISSING");
|
|
|
|
error = await discoveryError(modulesDirectory, { platformVersion: "invalid" });
|
|
expect(issueCodes(error)).toContain("DISCOVERY_CONFIGURATION_INVALID");
|
|
});
|
|
|
|
it("rejects source TypeScript server entrypoints", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "source-server", {
|
|
manifest: {
|
|
...manifestFor("source-server"),
|
|
entrypoints: { server: "./src/server/index.ts" },
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(error.issues).toContainEqual(
|
|
expect.objectContaining({
|
|
code: "MODULE_ENTRYPOINT_INVALID",
|
|
message: "server must reference compiled ESM JavaScript with a .js or .mjs extension.",
|
|
path: "entrypoints.server",
|
|
}),
|
|
);
|
|
});
|
|
|
|
it("requires executable entrypoints to be files and migrations to be a directory", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "wrong-entrypoint-kind", {
|
|
manifest: {
|
|
...manifestFor("wrong-entrypoint-kind"),
|
|
entrypoints: {
|
|
server: "./dist/server",
|
|
migrations: "./dist/server/index.js",
|
|
},
|
|
},
|
|
});
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(error.issues.filter((issue) => issue.code === "MODULE_ENTRYPOINT_INVALID")).toHaveLength(
|
|
2,
|
|
);
|
|
});
|
|
|
|
it("rejects package metadata links that escape the module directory", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
await createModule(modulesDirectory, "linked");
|
|
const externalManifest = path.join(modulesDirectory, "external-manifest.json");
|
|
const linkedManifest = path.join(modulesDirectory, "linked", "ekklesia.module.json");
|
|
await writeFile(externalManifest, JSON.stringify(manifestFor("linked")));
|
|
await rm(linkedManifest);
|
|
await symlink("../external-manifest.json", linkedManifest);
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_MANIFEST_INVALID");
|
|
});
|
|
|
|
it("rejects symbolic links masquerading as installed module directories", async () => {
|
|
const modulesDirectory = await createModulesDirectory();
|
|
const externalModules = await createModulesDirectory();
|
|
await createModule(externalModules, "outside");
|
|
await symlink(
|
|
path.join(externalModules, "outside"),
|
|
path.join(modulesDirectory, "linked-module"),
|
|
"dir",
|
|
);
|
|
|
|
const error = await discoveryError(modulesDirectory);
|
|
expect(issueCodes(error)).toContain("MODULE_DIRECTORY_INVALID");
|
|
});
|
|
|
|
it("produces stable diagnostics independent of the absolute modules path", async () => {
|
|
const firstModulesDirectory = await createModulesDirectory();
|
|
const secondModulesDirectory = await createModulesDirectory();
|
|
await mkdir(path.join(firstModulesDirectory, "broken"));
|
|
await mkdir(path.join(secondModulesDirectory, "broken"));
|
|
|
|
const [firstError, secondError] = await Promise.all([
|
|
discoveryError(firstModulesDirectory),
|
|
discoveryError(secondModulesDirectory),
|
|
]);
|
|
|
|
expect(firstError.issues).toEqual(secondError.issues);
|
|
});
|
|
});
|