feat: add module migration contracts and validation

core/src/cli/migration-report.ts

@@ -0,0 +1,28 @@
+import type { ModuleMigrationAggregate } from "../modules/index.js";
+
+function plural(count: number, singular: string): string {
+  return count === 1 ? singular : `${singular}s`;
+}
+
+export function formatMigrationValidationReport(
+  aggregate: ModuleMigrationAggregate,
+): readonly string[] {
+  const moduleCount = aggregate.modules.length;
+  const migrationCount = aggregate.migrations.length;
+  const header = `Migration validation passed (${moduleCount} ${plural(moduleCount, "module")}, ${migrationCount} ${plural(migrationCount, "migration")})${moduleCount === 0 ? "." : ":"}`;
+  const lines = [header];
+
+  for (const module of aggregate.modules) {
+    if (module.migrations.length === 0) {
+      lines.push(`- ${module.moduleId} (no migrations)`);
+      continue;
+    }
+    for (const migration of module.migrations) {
+      lines.push(
+        `- ${migration.identity} sha256=${migration.checksum} destructive=${migration.destructive.mode}`,
+      );
+    }
+  }
+
+  return Object.freeze(lines);
+}

core/src/cli/validate-migrations.ts

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { formatMigrationValidationReport } from "./migration-report.js";
+import {
+  discoverModuleMigrations,
+  ModuleDiscoveryError,
+  ModuleMigrationDiscoveryError,
+} from "../modules/index.js";
+
+interface PackageVersion {
+  version?: unknown;
+}
+
+async function readPackageVersion(packagePath: string): Promise<string> {
+  const packageData = JSON.parse(await readFile(packagePath, "utf8")) as PackageVersion;
+  if (typeof packageData.version !== "string") {
+    throw new TypeError("A required workspace package does not declare a version.");
+  }
+  return packageData.version;
+}
+
+async function main(): Promise<void> {
+  const repositoryRoot = process.cwd();
+  const [platformVersion, moduleSdkVersion] = await Promise.all([
+    readPackageVersion(path.join(repositoryRoot, "package.json")),
+    readPackageVersion(path.join(repositoryRoot, "packages/module-sdk/package.json")),
+  ]);
+  const aggregate = await discoverModuleMigrations({
+    moduleSdkVersion,
+    modulesDirectory: path.join(repositoryRoot, "modules"),
+    platformVersion,
+  });
+
+  for (const line of formatMigrationValidationReport(aggregate)) {
+    console.log(line);
+  }
+}
+
+main().catch((error: unknown) => {
+  if (error instanceof ModuleDiscoveryError) {
+    console.error(error.message);
+    for (const issue of error.issues) {
+      const issuePath = issue.path ? ` (${issue.path})` : "";
+      console.error(`[${issue.code}] ${issue.moduleDirectory}${issuePath}: ${issue.message}`);
+    }
+  } else if (error instanceof ModuleMigrationDiscoveryError) {
+    console.error(error.message);
+    for (const issue of error.issues) {
+      const issuePath = issue.path ? ` (${issue.path})` : "";
+      console.error(`[${issue.code}] ${issue.moduleId}${issuePath}: ${issue.message}`);
+    }
+  } else {
+    console.error("Migration validation failed unexpectedly.");
+  }
+  process.exitCode = 1;
+});