@supacloud/compiler 0.24.0 → 0.25.0

package/README.md

@@ -96,6 +96,24 @@ protocol migration are documented in `docs/fa-consumer-governance.md` in the
 repository. `context <module> --json` reports `routeContracts` and standalone
 command execution plans; these are declarations and obligations, not runtime proof.
 
+## Migration Assessment
+
+`migration-assess` creates a local, read-only compatibility report from the
+installed tested tuple, generated contract manifest, compiler drift checks and
+an optional OpenAPI baseline/current pair:
+
+```bash
+bunx supacloud-compiler migration-assess --json \
+  --baseline-openapi artifacts/openapi-baseline.json \
+  --current-openapi artifacts/openapi-current.json
+```
+
+The report distinguishes compatible changes, review items, breaking changes and
+evidence that is not yet proven. It records artifact hashes and never writes
+files, databases or remote environments. Rendering is explicitly independent:
+CSR/SPA, SvelteKit, Nuxt, SSR, edge and trusted-server arrangements are valid;
+SSR is never a migration prerequisite.
+
 SupaCloud 应用静态编译器：读取 `@supacloud/app` 装饰器元数据的原生 TypeScript AST，构建 ApplicationGraph，做静态校验，并生成**无反射、无容器**的工厂代码与 manifest。
 
 本包不依赖 `@supacloud/app`：AST 只按装饰器名匹配（`Module`/`Injectable`/`Inject`/`Command`/`Query`/`Controller`/`Get`/`Post`/`Put`/`Patch`/`Delete`/`defineModule`/`InjectionToken`），不校验 import 来源。

package/dist/cli.js

@@ -126,6 +126,9 @@ function buildContractManifest(graph, artifacts) {
           ...command?.permission === undefined ? {} : { permission: command.permission },
           requestSchemas: Object.fromEntries(["body", "params", "query", "headers", "cookie"].flatMap((key) => route[key] === undefined ? [] : [[key, route[key]]])),
           ...route.response === undefined ? {} : { responseSchema: route.response },
+          ...route.responses === undefined ? {} : {
+            responseSchemas: Object.fromEntries(Object.entries(route.responses).sort(([left], [right]) => left.localeCompare(right)))
+          },
           ...route.contract?.evidence === undefined ? {} : { evidence: route.contract.evidence }
         });
       }
@@ -2697,12 +2700,12 @@ var init_graphql = __esm(() => {
 });
 
 // src/database-contracts.ts
-import { createHash as createHash9 } from "node:crypto";
-import { mkdir as mkdir5, readFile as readFile11 } from "node:fs/promises";
-import { dirname as dirname10, relative as relative12, resolve as resolve15 } from "node:path";
+import { createHash as createHash10 } from "node:crypto";
+import { mkdir as mkdir5, readFile as readFile12 } from "node:fs/promises";
+import { dirname as dirname10, relative as relative12, resolve as resolve16 } from "node:path";
 import * as ts13 from "@typescript/typescript6";
 function hash2(value) {
-  return createHash9("sha256").update(value).digest("hex");
+  return createHash10("sha256").update(value).digest("hex");
 }
 function importPath(out, path) {
   const value = relative12(out, path).replaceAll("\\", "/").replace(/\.(?:d\.)?[cm]?ts$/, "");
@@ -2727,19 +2730,19 @@ function parseDatabaseContractsOptions(value, directory) {
     throw new TypeError("migrations must be an ordered list of SQL files");
   }
   return {
-    rootDir: resolve15(directory, field("rootDir")),
-    outDir: resolve15(directory, field("outDir")),
-    postgrestTypes: resolve15(directory, field("postgrestTypes")),
-    drizzleSchema: resolve15(directory, field("drizzleSchema")),
+    rootDir: resolve16(directory, field("rootDir")),
+    outDir: resolve16(directory, field("outDir")),
+    postgrestTypes: resolve16(directory, field("postgrestTypes")),
+    drizzleSchema: resolve16(directory, field("drizzleSchema")),
     role: field("role"),
-    graphql: { ...graphql, schema: resolve15(directory, graphql.schema) },
-    migrations: migrations.map((file) => resolve15(directory, file))
+    graphql: { ...graphql, schema: resolve16(directory, graphql.schema) },
+    migrations: migrations.map((file) => resolve16(directory, file))
   };
 }
 async function generateDatabaseContracts(options, check = false) {
-  const rootDir = resolve15(options.rootDir), outDir = resolve15(options.outDir);
-  const postgrestTypes = resolve15(rootDir, options.postgrestTypes), drizzleSchema = resolve15(rootDir, options.drizzleSchema);
-  const snapshot = await readFile11(postgrestTypes, "utf8");
+  const rootDir = resolve16(options.rootDir), outDir = resolve16(options.outDir);
+  const postgrestTypes = resolve16(rootDir, options.postgrestTypes), drizzleSchema = resolve16(rootDir, options.drizzleSchema);
+  const snapshot = await readFile12(postgrestTypes, "utf8");
   const syntax = ts13.createSourceFile(postgrestTypes, snapshot, ts13.ScriptTarget.Latest, true);
   const database = syntax.statements.find((node) => (ts13.isTypeAliasDeclaration(node) || ts13.isInterfaceDeclaration(node)) && node.name.text === "Database" && node.modifiers?.some((modifier) => modifier.kind === ts13.SyntaxKind.ExportKeyword));
   if (!database)
@@ -2766,8 +2769,8 @@ async function generateDatabaseContracts(options, check = false) {
   }
   const inputs = {};
   const addInput = async (path) => {
-    const absolute = resolve15(rootDir, path);
-    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile11(absolute, "utf8"));
+    const absolute = resolve16(rootDir, path);
+    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile12(absolute, "utf8"));
   };
   await addInput(postgrestTypes);
   await addInput(drizzleSchema);
@@ -2783,8 +2786,8 @@ async function generateDatabaseContracts(options, check = false) {
     if (!source.isDeclarationFile && !source.fileName.includes("/node_modules/"))
       await addInput(source.fileName);
   }
-  await addInput(resolve15(rootDir, options.graphql.schema));
-  if (new Set(options.migrations.map((path) => resolve15(rootDir, path))).size !== options.migrations.length) {
+  await addInput(resolve16(rootDir, options.graphql.schema));
+  if (new Set(options.migrations.map((path) => resolve16(rootDir, path))).size !== options.migrations.length) {
     throw new Error("Duplicate migration in database contracts configuration");
   }
   for (const path of options.migrations)
@@ -2805,17 +2808,17 @@ async function generateDatabaseContracts(options, check = false) {
     version: 1,
     role: options.role,
     inputs: Object.fromEntries(Object.entries(inputs).sort(([a], [b]) => a.localeCompare(b))),
-    migrationOrder: options.migrations.map((path) => relative12(rootDir, resolve15(rootDir, path)).replaceAll("\\", "/")),
+    migrationOrder: options.migrations.map((path) => relative12(rootDir, resolve16(rootDir, path)).replaceAll("\\", "/")),
     outputs: Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([file, text]) => [file, hash2(text)]))
   };
   files["database.manifest.json"] = JSON.stringify(manifest, null, 2) + `
 `;
   const mismatches = [];
   for (const [file, content] of Object.entries(files)) {
-    const path = resolve15(outDir, file);
+    const path = resolve16(outDir, file);
     let current;
     try {
-      current = await readFile11(path, "utf8");
+      current = await readFile12(path, "utf8");
     } catch (error) {
       if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
         throw error;
@@ -2826,13 +2829,13 @@ async function generateDatabaseContracts(options, check = false) {
   if (!check) {
     await mkdir5(outDir, { recursive: true });
     for (const [file, content] of Object.entries(files))
-      await writeFileIfChanged(resolve15(outDir, file), content);
+      await writeFileIfChanged(resolve16(outDir, file), content);
   }
   return { upToDate: mismatches.length === 0, mismatches, written: check ? [] : mismatches, manifest };
 }
 async function runDatabaseContractsFile(path, check = false) {
-  const absolute = resolve15(path);
-  const value = JSON.parse(await readFile11(absolute, "utf8"));
+  const absolute = resolve16(path);
+  const value = JSON.parse(await readFile12(absolute, "utf8"));
   return generateDatabaseContracts(parseDatabaseContractsOptions(value, dirname10(absolute)), check);
 }
 var init_database_contracts = __esm(() => {
@@ -2842,9 +2845,9 @@ var init_database_contracts = __esm(() => {
 });
 
 // src/graphql-schema.ts
-import { mkdir as mkdir6, readFile as readFile12 } from "node:fs/promises";
-import { createHash as createHash10 } from "node:crypto";
-import { dirname as dirname11, resolve as resolve16 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile13 } from "node:fs/promises";
+import { createHash as createHash11 } from "node:crypto";
+import { dirname as dirname11, resolve as resolve17 } from "node:path";
 async function pullGraphqlSchema(options) {
   assertGraphqlOptions({ schema: options.output });
   const endpoint = new URL(options.url);
@@ -2884,7 +2887,7 @@ async function pullGraphqlSchema(options) {
     throw new Error("GraphQL schema export failed. Verify caller grants and enable introspection only in the intended development environment.");
   }
   const schema = lexicographicSortSchema(buildClientSchema(data));
-  const path = resolve16(options.output);
+  const path = resolve17(options.output);
   const content = path.endsWith(".json") ? JSON.stringify(introspectionFromSchema(schema), null, 2) + `
 ` : `# GENERATED BY supacloud-compiler graphql-schema. DO NOT EDIT.
 # Database First: change database declarations, apply migrations, then re-export for the intended role.
@@ -2892,13 +2895,13 @@ async function pullGraphqlSchema(options) {
 `;
   let previous;
   try {
-    previous = await readFile12(path, "utf8");
+    previous = await readFile13(path, "utf8");
   } catch (error) {
     if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
       throw error;
   }
   const upToDate = previous === content;
-  const schemaHash = createHash10("sha256").update(content).digest("hex");
+  const schemaHash = createHash11("sha256").update(content).digest("hex");
   if (options.check)
     return { path, schemaHash, upToDate, written: false };
   await mkdir6(dirname11(path), { recursive: true });
@@ -2911,8 +2914,8 @@ var init_graphql_schema = __esm(() => {
 });
 
 // src/cli.ts
-import { resolve as resolve17 } from "node:path";
-import { readFile as readFile13 } from "node:fs/promises";
+import { resolve as resolve18 } from "node:path";
+import { readFile as readFile14 } from "node:fs/promises";
 
 // src/analyze.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -7611,6 +7614,8 @@ function optionsKeyOf(options) {
     requireRouteContracts: options.requireRouteContracts,
     detectOrphanModules: options.detectOrphanModules,
     generateClient: options.generateClient,
+    generateOpenApi: options.generateOpenApi,
+    openApi: options.openApi,
     generatePermissions: options.generatePermissions,
     typeSafety: options.typeSafety,
     treeShakeUnusedProviders: options.treeShakeUnusedProviders,
@@ -7745,6 +7750,16 @@ function findAffectedModules(previous, current, changedFiles) {
 
 // src/watch.ts
 var DEFAULT_DEBOUNCE_MS = 100;
+function isCompilerConfigurationPath(rootDir, changedPath) {
+  const relativePath = relative7(rootDir, changedPath).split(sep7).join("/");
+  return [
+    "supacloud.config.ts",
+    "supacloud.config.mts",
+    "supacloud.config.js",
+    "supacloud.config.mjs",
+    "tsconfig.json"
+  ].includes(relativePath) || /^tsconfig\.[^/]+\.json$/.test(relativePath);
+}
 function watchProject(options) {
   const rootDir = resolve6(options.rootDir);
   const outDir = resolve6(options.outDir);
@@ -7837,7 +7852,7 @@ function watchProject(options) {
       const relativePath = relative7(outDir, changedPath);
       if (!relativePath.startsWith("..") && relativePath !== "")
         return;
-      if (/\.(tsx?|mts|cts)$/.test(changedPath) || options.graphql && (/\.(graphql|gql)$/.test(changedPath) || changedPath === schemaPath)) {
+      if (/\.(tsx?|mts|cts)$/.test(changedPath) || isCompilerConfigurationPath(rootDir, changedPath) || options.graphql && (/\.(graphql|gql)$/.test(changedPath) || changedPath === schemaPath)) {
         schedule(relative7(rootDir, changedPath));
       }
     });
@@ -12716,6 +12731,11 @@ async function migrateProject(options) {
   };
 }
 
+// src/migration-assess.ts
+import { createHash as createHash9 } from "node:crypto";
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join9, resolve as resolve15 } from "node:path";
+
 // src/openapi-tools.ts
 import { mkdir as mkdir4, readFile as readFile10, rename as rename6, unlink as unlink3, writeFile as writeFile5 } from "node:fs/promises";
 import { dirname as dirname9, resolve as resolve14 } from "node:path";
@@ -13221,10 +13241,199 @@ function formatOpenApiDiff(result) {
 `);
 }
 
+// src/migration-assess.ts
+var STATUS_PRIORITY = {
+  compatible: 0,
+  "needs-review": 1,
+  "not-proven": 2,
+  unsupported: 3,
+  breaking: 4
+};
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function arrayLength(value) {
+  return Array.isArray(value) ? value.length : undefined;
+}
+async function sha256(path) {
+  return createHash9("sha256").update(await readFile11(path)).digest("hex");
+}
+function overallStatus(findings) {
+  return findings.reduce((current, finding) => STATUS_PRIORITY[finding.status] > STATUS_PRIORITY[current] ? finding.status : current, "compatible");
+}
+async function assessMigration(options) {
+  const projectDir = resolve15(options.projectDir);
+  const compile = {
+    ...options.compile,
+    rootDir: resolve15(options.compile.rootDir),
+    outDir: resolve15(options.compile.outDir)
+  };
+  const findings = [];
+  const dependencyProblems = await checkMigrationDependencies(projectDir);
+  if (dependencyProblems.length > 0) {
+    findings.push({
+      code: "migration-dependency-tuple-not-proven",
+      status: "not-proven",
+      message: "The installed compiler migration dependency tuple is not the exact tested tuple.",
+      evidence: dependencyProblems.join("; "),
+      remediation: "Install the exact tested package versions before applying a source migration."
+    });
+  }
+  let compiler = {
+    upToDate: false,
+    diagnostics: [],
+    mismatches: []
+  };
+  try {
+    const checked = await checkProject(compile);
+    compiler = {
+      upToDate: checked.upToDate,
+      diagnostics: checked.diagnostics,
+      mismatches: checked.mismatches
+    };
+    const errors = checked.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0) {
+      findings.push({
+        code: "compiler-governance-not-proven",
+        status: "not-proven",
+        message: `Compiler governance has ${errors.length} error(s).`,
+        remediation: "Resolve compiler diagnostics without weakening governance, then reassess."
+      });
+    }
+    if (!checked.upToDate) {
+      findings.push({
+        code: "generated-artifact-drift",
+        status: "needs-review",
+        message: "Generated artifacts do not match the current source and compiler configuration.",
+        evidence: checked.mismatches.join("; "),
+        remediation: "Regenerate candidate artifacts in isolation and review the diff before adoption."
+      });
+    }
+  } catch {
+    findings.push({
+      code: "compiler-check-unavailable",
+      status: "not-proven",
+      message: "The local compiler check could not complete.",
+      remediation: "Verify the project source, configuration and installed dependencies, then reassess."
+    });
+  }
+  const contractsManifestPath = join9(compile.outDir, "contracts.manifest.json");
+  let contractsManifest = {
+    path: contractsManifestPath,
+    present: false
+  };
+  try {
+    const parsed = JSON.parse(await readFile11(contractsManifestPath, "utf8"));
+    if (!isRecord2(parsed) || parsed.version !== 1)
+      throw new Error("invalid manifest");
+    contractsManifest = {
+      path: contractsManifestPath,
+      present: true,
+      sha256: await sha256(contractsManifestPath),
+      version: 1,
+      ...arrayLength(parsed.commands) === undefined ? {} : { commands: arrayLength(parsed.commands) },
+      ...arrayLength(parsed.routes) === undefined ? {} : { routes: arrayLength(parsed.routes) },
+      ...arrayLength(parsed.permissions) === undefined ? {} : { permissions: arrayLength(parsed.permissions) }
+    };
+  } catch {
+    findings.push({
+      code: "contract-manifest-not-proven",
+      status: "not-proven",
+      message: "contracts.manifest.json is missing or invalid.",
+      evidence: contractsManifestPath,
+      remediation: "Generate and review the contract manifest before migration."
+    });
+  }
+  let openApi;
+  if (options.baselineOpenApiPath && options.currentOpenApiPath) {
+    const baselinePath = resolve15(projectDir, options.baselineOpenApiPath);
+    const currentPath = resolve15(projectDir, options.currentOpenApiPath);
+    try {
+      const diff = diffOpenApiDocuments(await readOpenApiJson(baselinePath), await readOpenApiJson(currentPath));
+      openApi = {
+        baselinePath,
+        baselineSha256: await sha256(baselinePath),
+        currentPath,
+        currentSha256: await sha256(currentPath),
+        diff
+      };
+      if (!diff.ok) {
+        findings.push({
+          code: "openapi-breaking-change",
+          status: "breaking",
+          message: `OpenAPI contains ${diff.breaking.length} breaking change(s).`,
+          remediation: "Review and explicitly approve or redesign each breaking contract change."
+        });
+      } else if (diff.changes.length > 0) {
+        findings.push({
+          code: "openapi-compatible-change-review",
+          status: "needs-review",
+          message: `OpenAPI contains ${diff.changes.length} non-breaking change(s) requiring release review.`
+        });
+      }
+    } catch {
+      findings.push({
+        code: "openapi-diff-not-proven",
+        status: "not-proven",
+        message: "The OpenAPI baseline or current document could not be loaded.",
+        remediation: "Export both OpenAPI documents as JSON and rerun the assessment."
+      });
+    }
+  } else {
+    findings.push({
+      code: "openapi-baseline-not-proven",
+      status: "not-proven",
+      message: "No complete OpenAPI baseline/current pair was supplied.",
+      remediation: "Provide both --baseline-openapi and --current-openapi for compatibility evidence."
+    });
+  }
+  findings.push({
+    code: "rendering-mode-preserved",
+    status: "compatible",
+    message: "SupaCloud migration does not require SSR and does not change the existing rendering topology.",
+    evidence: `selected=${options.renderMode ?? "unspecified"}`
+  });
+  const status = overallStatus(findings);
+  return {
+    version: 1,
+    ok: status === "compatible" || status === "needs-review",
+    status,
+    readOnly: true,
+    writesPerformed: false,
+    rendering: {
+      selected: options.renderMode ?? "unspecified",
+      ssrRequired: false,
+      supportedModes: ["browser", "ssr", "edge", "trusted-server"],
+      guidance: "Keep the application's existing CSR, SPA, SSR or edge topology; use trusted adapters only for governed server operations."
+    },
+    dependencies: {
+      expected: migrationDependencies(),
+      problems: dependencyProblems
+    },
+    compiler,
+    artifacts: {
+      contractsManifest,
+      ...openApi === undefined ? {} : { openApi }
+    },
+    findings
+  };
+}
+function formatMigrationAssessment(result) {
+  return [
+    `Migration assessment: ${result.status}. Read-only; no files, databases or remote environments were changed.`,
+    `Rendering: ${result.rendering.selected}; SSR required: no.`,
+    ...result.findings.map((finding) => `${finding.status.toUpperCase()} ${finding.code}: ${finding.message}`)
+  ].join(`
+`);
+}
+
 // src/cli.ts
 function isModuleBoundaryPresetName(value) {
   return value === "modular-monolith" || value === "feature-slices" || value === "vertical-slices" || value === "angular-enterprise" || value === "angular" || value === "clean-architecture" || value === "domain-driven";
 }
+function isMigrationRenderMode(value) {
+  return value === "unspecified" || value === "browser" || value === "ssr" || value === "edge" || value === "trusted-server";
+}
 function printUsage() {
   console.log(`
 @supacloud/compiler CLI
@@ -13238,6 +13447,7 @@ Usage:
   supacloud-compiler context <module> [rootDir] [options]
   supacloud-compiler doctor  [rootDir] [options]
   supacloud-compiler migrate [rootDir] [options]
+  supacloud-compiler migration-assess [rootDir] [options]
   supacloud-compiler plan    [rootDir] [options]
   supacloud-compiler build-delivery [rootDir] [options]
   supacloud-compiler openapi-export <openapi-module> <output.json> [options]
@@ -13255,6 +13465,7 @@ Commands:
   context             Extract an AI-sized module context pack
   doctor              Run project and generated-artifact health checks
   migrate             Preview or apply versioned source migrations
+  migration-assess    Produce a read-only migration compatibility report
   plan                Preview deterministic workload targets without writing or deploying
   build-delivery      Build independent local factories and an atomic delivery manifest (Bun)
   openapi-export      Export a generated OpenAPI module to a standalone JSON document
@@ -13278,13 +13489,16 @@ Options:
   --token-env <name>  Environment variable holding the intended user's access token
   --check             graphql-schema: compare the remote schema without changing the snapshot
   --debounce <ms>     Debounce source changes in dev mode (default: 100)
-  --json              Print machine-readable output for compile/check/graph/explain/context/doctor/plan/build-delivery/openapi-export/openapi-diff
+  --json              Print machine-readable output for compile/check/graph/explain/context/doctor/migration-assess/plan/build-delivery/openapi-export/openapi-diff
   --space <n>         openapi-export: JSON indentation (0-10, default: 2)
   --delivery <file>   plan/build-delivery: validated JSON configuration (overrides config.delivery)
   --dry-run           Preview a fix without writing the target file
   --write             Apply a fix or migration to disk (preview-only by default)
   --from-version      Migration source-format checkpoint (requires --to-version)
   --to-version        Migration target checkpoint; verifies installed dependencies
+  --baseline-openapi  OpenAPI baseline JSON for migration-assess
+  --current-openapi   Current OpenAPI JSON for migration-assess
+  --render-mode       Optional browser | ssr | edge | trusted-server label; SSR is never required
   --preset, -p <name> Architecture preset ('modular-monolith' | 'angular-enterprise' | 'clean-architecture')
   --help, -h          Show this help
 `);
@@ -13308,7 +13522,7 @@ async function run() {
       process.exitCode = 1;
     return;
   }
-  if (!command || !["compile", "check", "dev", "graph", "explain", "context", "doctor", "migrate", "fix", "graphql-schema", "plan", "build-delivery", "openapi-export", "openapi-diff"].includes(command)) {
+  if (!command || !["compile", "check", "dev", "graph", "explain", "context", "doctor", "migrate", "migration-assess", "fix", "graphql-schema", "plan", "build-delivery", "openapi-export", "openapi-diff"].includes(command)) {
     console.error(`Error: unknown command "${command}"`);
     printUsage();
     process.exit(1);
@@ -13332,6 +13546,9 @@ async function run() {
   let tokenEnv;
   let checkSchema = false;
   let deliveryPath;
+  let baselineOpenApi;
+  let currentOpenApi;
+  let renderMode = "unspecified";
   const openApiDiffPaths = [];
   const openApiExportPaths = [];
   let openApiExportSpace;
@@ -13436,9 +13653,27 @@ async function run() {
     } else if (arg === "--dry-run") {
       dryRun = true;
     } else if (arg === "--write") {
-      if (command === "plan")
-        throw new Error("plan is read-only; --write is not supported");
+      if (command === "plan" || command === "migration-assess")
+        throw new Error(`${command} is read-only; --write is not supported`);
       dryRun = false;
+    } else if (arg === "--baseline-openapi" || arg === "--current-openapi") {
+      if (command !== "migration-assess")
+        throw new Error(`${arg} is only supported by migration-assess`);
+      const value = args[++i];
+      if (!value || value.startsWith("-"))
+        throw new Error(`${arg} requires a JSON file path`);
+      if (arg === "--baseline-openapi")
+        baselineOpenApi = value;
+      else
+        currentOpenApi = value;
+    } else if (arg === "--render-mode") {
+      if (command !== "migration-assess")
+        throw new Error("--render-mode is only supported by migration-assess");
+      const value = args[++i];
+      if (!isMigrationRenderMode(value)) {
+        throw new Error("--render-mode requires browser, ssr, edge or trusted-server");
+      }
+      renderMode = value;
     } else if (arg === "--from-version" || arg === "--to-version") {
       if (command !== "migrate")
         throw new Error(`${arg} is only supported by migrate`);
@@ -13479,7 +13714,7 @@ async function run() {
     const currentPath = openApiDiffPaths[1];
     if (!basePath || !currentPath)
       throw new Error("openapi-diff requires two JSON file paths");
-    const result = diffOpenApiDocuments(await readOpenApiJson(resolve17(process.cwd(), basePath)), await readOpenApiJson(resolve17(process.cwd(), currentPath)));
+    const result = diffOpenApiDocuments(await readOpenApiJson(resolve18(process.cwd(), basePath)), await readOpenApiJson(resolve18(process.cwd(), currentPath)));
     console.log(json ? JSON.stringify(result, null, 2) : formatOpenApiDiff(result));
     if (!result.ok)
       process.exitCode = 1;
@@ -13494,8 +13729,8 @@ async function run() {
     if (!modulePath || !outputPath)
       throw new Error("openapi-export requires an OpenAPI module and output path");
     const result = await exportGeneratedOpenApiJson({
-      modulePath: resolve17(process.cwd(), modulePath),
-      outputPath: resolve17(process.cwd(), outputPath),
+      modulePath: resolve18(process.cwd(), modulePath),
+      outputPath: resolve18(process.cwd(), outputPath),
       ...openApiExportSpace === undefined ? {} : { space: openApiExportSpace }
     });
     console.log(json ? JSON.stringify({ ok: true, ...result }, null, 2) : result.written ? `OpenAPI JSON written: ${result.path}` : `OpenAPI JSON matches: ${result.path}`);
@@ -13503,7 +13738,7 @@ async function run() {
   }
   if (command === "migrate") {
     const result = await migrateProject({
-      rootDir: rootDir ? resolve17(process.cwd(), rootDir) : process.cwd(),
+      rootDir: rootDir ? resolve18(process.cwd(), rootDir) : process.cwd(),
       write: !dryRun,
       ...fromVersion === undefined ? {} : { fromVersion },
       ...toVersion === undefined ? {} : { toVersion }
@@ -13531,8 +13766,8 @@ async function run() {
   if (checkSchema && command !== "graphql-schema")
     throw new Error("--check is only supported by graphql-schema");
   const defaults = resolveSupacloudConfig(loadedConfig, process.cwd());
-  const resolvedRoot = rootDir ? resolve17(process.cwd(), rootDir) : defaults.rootDir;
-  const resolvedOut = outDir ? resolve17(process.cwd(), outDir) : defaults.outDir;
+  const resolvedRoot = rootDir ? resolve18(process.cwd(), rootDir) : defaults.rootDir;
+  const resolvedOut = outDir ? resolve18(process.cwd(), outDir) : defaults.outDir;
   const configured = compileOptionsFromConfig({
     ...loadedConfig,
     root: resolvedRoot,
@@ -13551,7 +13786,7 @@ async function run() {
     let delivery = loadedConfig.delivery;
     if (deliveryPath !== undefined) {
       try {
-        delivery = JSON.parse(await readFile13(resolve17(process.cwd(), deliveryPath), "utf8"));
+        delivery = JSON.parse(await readFile14(resolve18(process.cwd(), deliveryPath), "utf8"));
       } catch {
         throw new DeliveryConfigurationError;
       }
@@ -13595,10 +13830,21 @@ ${item.suggestion ?? ""}`).join(`
     console.log(json ? JSON.stringify({ ok: result.upToDate, ...result }, null, 2) : result.written ? `GraphQL schema written: ${result.path}` : result.upToDate ? `GraphQL schema matches: ${result.path}` : `GraphQL schema drift: ${result.path}. Export the role-scoped snapshot and compile before promotion.`);
     if (!result.upToDate)
       process.exit(1);
+  } else if (command === "migration-assess") {
+    const result = await assessMigration({
+      projectDir: process.cwd(),
+      compile: compileDefaults,
+      ...baselineOpenApi === undefined ? {} : { baselineOpenApiPath: baselineOpenApi },
+      ...currentOpenApi === undefined ? {} : { currentOpenApiPath: currentOpenApi },
+      renderMode
+    });
+    console.log(json ? JSON.stringify(result, null, 2) : formatMigrationAssessment(result));
+    if (result.status === "breaking" || result.status === "unsupported")
+      process.exitCode = 1;
   } else if (command === "fix") {
     if (!query)
       throw new Error("fix requires a JSON file containing one DiagnosticFix");
-    const fix = JSON.parse(await readFile13(resolve17(process.cwd(), query), "utf8"));
+    const fix = JSON.parse(await readFile14(resolve18(process.cwd(), query), "utf8"));
     const result = await applyDiagnosticFix(fix, { rootDir: resolvedRoot, dryRun });
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
   } else if (command === "compile") {

package/dist/contract-manifest.d.ts

@@ -26,6 +26,8 @@ export interface ContractManifest {
         permission?: string;
         requestSchemas: Partial<Record<"body" | "params" | "query" | "headers" | "cookie", string>>;
         responseSchema?: string;
+        /** Status-aware response schemas; legacy responseSchema remains for compatibility. */
+        responseSchemas?: Record<string, string>;
         evidence?: string;
     }>;
     permissions: string[];

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { AppliedDiagnosticFix, ApplyDiagnosticFixOptions } from "./fixes";
 export { checkProject, compileProject } from "./compile";
 export { watchProject } from "./watch";
 export { migrateProject, SUPACLOUD_MIGRATIONS, migrateRouteResponse } from "./migrations";
+export { assessMigration, formatMigrationAssessment } from "./migration-assess";
+export type { MigrationAssessmentFinding, MigrationAssessmentOptions, MigrationAssessmentResult, MigrationAssessmentStatus, MigrationRenderMode, } from "./migration-assess";
 export { createContextPack, createExecutionPlans, doctorProject, explainGraph, formatGraph, exportGraphDot, exportGraphMermaid, } from "./inspect";
 export { createIncrementalCompiler } from "./incremental";
 export { createDependencyGraphCache } from "./incremental";