@supacloud/compiler 0.23.0 → 0.25.0

package/dist/index.js

@@ -77,6 +77,86 @@ function findClosestMatch(target, candidates) {
 }
 var REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context", JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
 
+// src/contract-manifest.ts
+function buildContractManifest(graph, artifacts) {
+  const commands = [];
+  const queries = [];
+  const routes = [];
+  const permissions = new Set;
+  const rpc = [];
+  const events = [];
+  const fixtures = new Set;
+  for (const module of graph.modules) {
+    for (const command of module.commands) {
+      if (command.permission)
+        permissions.add(command.permission);
+      if (command.rpc)
+        rpc.push({ command: command.name, adapter: command.rpc });
+      if (command.audit)
+        events.push({ name: command.audit, source: "command.audit", command: command.name });
+      commands.push({
+        name: command.name,
+        className: command.className,
+        module: module.name,
+        ...command.permission === undefined ? {} : { permission: command.permission },
+        ...command.rpc === undefined ? {} : { rpc: command.rpc },
+        transaction: command.transaction,
+        idempotency: command.idempotency,
+        ...command.audit === undefined ? {} : { auditEvent: command.audit }
+      });
+    }
+    for (const query of module.queries) {
+      queries.push({ name: query.name, className: query.className, module: module.name });
+    }
+    for (const controller of module.controllers) {
+      for (const route of controller.routes) {
+        const command = route.command ? module.commands.find((candidate) => candidate.className === route.command) : undefined;
+        if (command?.permission)
+          permissions.add(command.permission);
+        if (route.contract?.evidence)
+          fixtures.add(route.contract.evidence);
+        routes.push({
+          method: route.method,
+          path: joinRoutePaths(controller.path, route.path),
+          module: module.name,
+          controller: controller.className,
+          handler: route.handler,
+          ...route.command === undefined ? {} : { command: route.command },
+          ...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 }
+        });
+      }
+    }
+  }
+  commands.sort((left, right) => left.name.localeCompare(right.name));
+  queries.sort((left, right) => left.name.localeCompare(right.name));
+  routes.sort((left, right) => `${left.method} ${left.path}`.localeCompare(`${right.method} ${right.path}`));
+  rpc.sort((left, right) => left.command.localeCompare(right.command));
+  events.sort((left, right) => left.name.localeCompare(right.name));
+  return {
+    version: 1,
+    commands,
+    queries,
+    routes,
+    permissions: [...permissions].sort(),
+    rpc,
+    events,
+    fixtures: [...fixtures].sort(),
+    artifacts: {
+      ...artifacts,
+      sdk: "generated-client",
+      openapiDocument: "generated",
+      permissionManifest: "generated"
+    }
+  };
+}
+var init_contract_manifest = () => {};
+
 // src/generate.ts
 import { createHash as createHash4 } from "node:crypto";
 import { access, mkdir, rename, unlink, writeFile } from "node:fs/promises";
@@ -218,9 +298,16 @@ function renderApplication(graph, options) {
   const clientCode = options.generateClient ? renderClient(graph, options) : undefined;
   const openApiCode = options.generateOpenApi ? renderOpenApi(graph, options) : undefined;
   const permissionsCode = options.generatePermissions ? renderPermissions(graph) : undefined;
+  const contractsManifest = buildContractManifest(graph, {
+    client: clientCode !== undefined,
+    openapi: openApiCode !== undefined,
+    permissions: permissionsCode !== undefined
+  });
   return {
     applicationCode: code,
     manifestJson: JSON.stringify(manifest, null, 2) + `
+`,
+    contractsManifestJson: JSON.stringify(contractsManifest, null, 2) + `
 `,
     ...clientCode === undefined ? {} : { clientCode },
     ...openApiCode === undefined ? {} : { openApiCode },
@@ -232,9 +319,11 @@ async function generateApplication(graph, options) {
   await mkdir(options.outDir, { recursive: true });
   const applicationPath = join2(options.outDir, "application.ts");
   const manifestPath = join2(options.outDir, "app.manifest.json");
+  const contractsManifestPath = join2(options.outDir, "contracts.manifest.json");
   const writeCandidates = [
     { path: applicationPath, content: rendered.applicationCode },
-    { path: manifestPath, content: rendered.manifestJson }
+    { path: manifestPath, content: rendered.manifestJson },
+    { path: contractsManifestPath, content: rendered.contractsManifestJson }
   ];
   if (rendered.clientCode) {
     writeCandidates.push({ path: join2(options.outDir, "client.ts"), content: rendered.clientCode });
@@ -2095,7 +2184,9 @@ function destroyScopeInstances(
   scopeDestructions.set(scope, destruction);
   return destruction;
 }`;
-var init_generate = () => {};
+var init_generate = __esm(() => {
+  init_contract_manifest();
+});
 
 // src/graphql-client.ts
 var GRAPHQL_CLIENT_SOURCE = `
@@ -2608,9 +2699,9 @@ var init_graphql = __esm(() => {
 });
 
 // src/graphql-schema.ts
-import { mkdir as mkdir5, readFile as readFile11 } from "node:fs/promises";
-import { createHash as createHash9 } from "node:crypto";
-import { dirname as dirname10, resolve as resolve15 } from "node:path";
+import { mkdir as mkdir5, readFile as readFile12 } from "node:fs/promises";
+import { createHash as createHash10 } from "node:crypto";
+import { dirname as dirname10, resolve as resolve16 } from "node:path";
 async function pullGraphqlSchema(options) {
   assertGraphqlOptions({ schema: options.output });
   const endpoint = new URL(options.url);
@@ -2650,7 +2741,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 = resolve15(options.output);
+  const path = resolve16(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.
@@ -2658,13 +2749,13 @@ async function pullGraphqlSchema(options) {
 `;
   let previous;
   try {
-    previous = await readFile11(path, "utf8");
+    previous = await readFile12(path, "utf8");
   } catch (error) {
     if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
       throw error;
   }
   const upToDate = previous === content;
-  const schemaHash = createHash9("sha256").update(content).digest("hex");
+  const schemaHash = createHash10("sha256").update(content).digest("hex");
   if (options.check)
     return { path, schemaHash, upToDate, written: false };
   await mkdir5(dirname10(path), { recursive: true });
@@ -2677,12 +2768,12 @@ var init_graphql_schema = __esm(() => {
 });
 
 // src/database-contracts.ts
-import { createHash as createHash10 } from "node:crypto";
-import { mkdir as mkdir6, readFile as readFile12 } from "node:fs/promises";
-import { dirname as dirname11, relative as relative12, resolve as resolve16 } from "node:path";
+import { createHash as createHash11 } from "node:crypto";
+import { mkdir as mkdir6, readFile as readFile13 } from "node:fs/promises";
+import { dirname as dirname11, relative as relative12, resolve as resolve17 } from "node:path";
 import * as ts13 from "@typescript/typescript6";
 function hash2(value) {
-  return createHash10("sha256").update(value).digest("hex");
+  return createHash11("sha256").update(value).digest("hex");
 }
 function importPath(out, path) {
   const value = relative12(out, path).replaceAll("\\", "/").replace(/\.(?:d\.)?[cm]?ts$/, "");
@@ -2707,19 +2798,19 @@ function parseDatabaseContractsOptions(value, directory) {
     throw new TypeError("migrations must be an ordered list of SQL files");
   }
   return {
-    rootDir: resolve16(directory, field("rootDir")),
-    outDir: resolve16(directory, field("outDir")),
-    postgrestTypes: resolve16(directory, field("postgrestTypes")),
-    drizzleSchema: resolve16(directory, field("drizzleSchema")),
+    rootDir: resolve17(directory, field("rootDir")),
+    outDir: resolve17(directory, field("outDir")),
+    postgrestTypes: resolve17(directory, field("postgrestTypes")),
+    drizzleSchema: resolve17(directory, field("drizzleSchema")),
     role: field("role"),
-    graphql: { ...graphql, schema: resolve16(directory, graphql.schema) },
-    migrations: migrations.map((file) => resolve16(directory, file))
+    graphql: { ...graphql, schema: resolve17(directory, graphql.schema) },
+    migrations: migrations.map((file) => resolve17(directory, file))
   };
 }
 async function generateDatabaseContracts(options, check = false) {
-  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 rootDir = resolve17(options.rootDir), outDir = resolve17(options.outDir);
+  const postgrestTypes = resolve17(rootDir, options.postgrestTypes), drizzleSchema = resolve17(rootDir, options.drizzleSchema);
+  const snapshot = await readFile13(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)
@@ -2746,8 +2837,8 @@ async function generateDatabaseContracts(options, check = false) {
   }
   const inputs = {};
   const addInput = async (path) => {
-    const absolute = resolve16(rootDir, path);
-    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile12(absolute, "utf8"));
+    const absolute = resolve17(rootDir, path);
+    inputs[relative12(rootDir, absolute).replaceAll("\\", "/")] = hash2(await readFile13(absolute, "utf8"));
   };
   await addInput(postgrestTypes);
   await addInput(drizzleSchema);
@@ -2763,8 +2854,8 @@ async function generateDatabaseContracts(options, check = false) {
     if (!source.isDeclarationFile && !source.fileName.includes("/node_modules/"))
       await addInput(source.fileName);
   }
-  await addInput(resolve16(rootDir, options.graphql.schema));
-  if (new Set(options.migrations.map((path) => resolve16(rootDir, path))).size !== options.migrations.length) {
+  await addInput(resolve17(rootDir, options.graphql.schema));
+  if (new Set(options.migrations.map((path) => resolve17(rootDir, path))).size !== options.migrations.length) {
     throw new Error("Duplicate migration in database contracts configuration");
   }
   for (const path of options.migrations)
@@ -2785,17 +2876,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, resolve16(rootDir, path)).replaceAll("\\", "/")),
+    migrationOrder: options.migrations.map((path) => relative12(rootDir, resolve17(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 = resolve16(outDir, file);
+    const path = resolve17(outDir, file);
     let current;
     try {
-      current = await readFile12(path, "utf8");
+      current = await readFile13(path, "utf8");
     } catch (error) {
       if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
         throw error;
@@ -2806,13 +2897,13 @@ async function generateDatabaseContracts(options, check = false) {
   if (!check) {
     await mkdir6(outDir, { recursive: true });
     for (const [file, content] of Object.entries(files))
-      await writeFileIfChanged(resolve16(outDir, file), content);
+      await writeFileIfChanged(resolve17(outDir, file), content);
   }
   return { upToDate: mismatches.length === 0, mismatches, written: check ? [] : mismatches, manifest };
 }
 async function runDatabaseContractsFile(path, check = false) {
-  const absolute = resolve16(path);
-  const value = JSON.parse(await readFile12(absolute, "utf8"));
+  const absolute = resolve17(path);
+  const value = JSON.parse(await readFile13(absolute, "utf8"));
   return generateDatabaseContracts(parseDatabaseContractsOptions(value, dirname11(absolute)), check);
 }
 var init_database_contracts = __esm(() => {
@@ -6982,6 +7073,7 @@ async function compileProject(options) {
       "client.ts": rendered.clientCode,
       "openapi.ts": rendered.openApiCode,
       "permissions.ts": rendered.permissionsCode,
+      "contracts.manifest.json": rendered.contractsManifestJson,
       "graphql.ts": graphql.files["graphql.ts"],
       "graphql.documents.ts": graphql.files["graphql.documents.ts"]
     }, options.strict ?? false));
@@ -7051,7 +7143,8 @@ async function checkProject(options) {
   const expectedFiles = {
     ...graphql.files,
     "application.ts": rendered.applicationCode,
-    "app.manifest.json": rendered.manifestJson
+    "app.manifest.json": rendered.manifestJson,
+    "contracts.manifest.json": rendered.contractsManifestJson
   };
   if (rendered.clientCode) {
     expectedFiles["client.ts"] = rendered.clientCode;
@@ -11495,6 +11588,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,
@@ -11629,6 +11724,16 @@ function findAffectedModules(previous, current, changedFiles) {
 
 // src/watch.ts
 var DEFAULT_DEBOUNCE_MS = 100;
+function isCompilerConfigurationPath(rootDir, changedPath) {
+  const relativePath = relative9(rootDir, changedPath).split(sep9).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 = resolve10(options.rootDir);
   const outDir = resolve10(options.outDir);
@@ -11721,7 +11826,7 @@ function watchProject(options) {
       const relativePath = relative9(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(relative9(rootDir, changedPath));
       }
     });
@@ -11775,7 +11880,7 @@ function compilerVersion() {
 }
 function migrationDependencies() {
   return {
-    "@supacloud/app": "0.15.0",
+    "@supacloud/app": "0.16.0",
     "@supacloud/compiler": compilerVersion(),
     "@supacloud/elysia": "0.18.0",
     elysia: "1.4.30",
@@ -12195,797 +12300,989 @@ async function migrateProject(options) {
     issues
   };
 }
-// src/inspect.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { dirname as dirname8, join as join7, relative as relative11, sep as sep10 } from "node:path";
-function formatGraph(graph) {
-  const lines = [];
-  for (const module of graph.modules) {
-    lines.push(`MODULE ${module.name}`);
-    lines.push(`  file: ${module.file}:${module.line}`);
-    lines.push(`  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`);
-    lines.push(`  providers: ${module.providers.length > 0 ? module.providers.map((p) => p.token).join(", ") : "-"}`);
-    lines.push(`  controllers: ${module.controllers.length > 0 ? module.controllers.map((c) => c.className).join(", ") : "-"}`);
-    lines.push(`  commands: ${module.commands.length > 0 ? module.commands.map((c) => c.name).join(", ") : "-"}`);
+// src/migration-assess.ts
+import { createHash as createHash9 } from "node:crypto";
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join7, resolve as resolve14 } 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 dirname8, resolve as resolve13 } from "node:path";
+import { pathToFileURL } from "node:url";
+
+class OpenApiDocumentError extends Error {
+  code = "OPENAPI_DOCUMENT_INVALID";
+  constructor() {
+    super("OpenAPI document is invalid or could not be loaded.");
+    this.name = "OpenApiDocumentError";
   }
-  lines.push(`EXTERNAL TOKENS ${graph.externalTokens.length > 0 ? graph.externalTokens.join(", ") : "-"}`);
-  return lines.join(`
-`);
 }
-function explainGraph(graph, subject) {
-  const module = graph.modules.find((candidate) => candidate.name === subject);
-  if (module)
-    return explainModule(graph, module);
-  const provider = findProvider(graph, subject);
-  if (provider)
-    return explainProvider(graph, provider.module, provider.provider);
-  if (graph.externalTokens.includes(subject)) {
-    const references = graph.modules.flatMap((candidate) => [
-      ...candidate.providers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.token}`),
-      ...candidate.controllers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.className}`)
-    ]);
-    return [
-      `EXTERNAL TOKEN ${subject}`,
-      "  provided by: platform runtime",
-      `  references: ${references.length > 0 ? references.join(", ") : "-"}`
-    ].join(`
-`);
-  }
-  const known = [...graph.modules.map((item) => item.name), ...graph.externalTokens].sort();
-  throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
+var HTTP_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace"
+];
+var COMPONENT_GROUPS = [
+  "schemas",
+  "responses",
+  "parameters",
+  "requestBodies",
+  "headers",
+  "securitySchemes"
+];
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-function createContextPack(graph, subject) {
-  const subjectModule = graph.modules.find((module) => module.name === subject);
-  if (!subjectModule) {
-    throw new Error(`No module named "${subject}". Context packs require a module name.`);
+function stringValue(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function recordValue(value) {
+  return isRecord(value) ? value : undefined;
+}
+function arrayValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+function sortedKeys(value) {
+  return value ? Object.keys(value).sort() : [];
+}
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function decodeJsonPointerPart(value) {
+  return value.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function resolveSchema(value, document, seen = new Set) {
+  const schema = recordValue(value);
+  if (!schema)
+    return;
+  const ref = stringValue(schema.$ref);
+  if (!ref || !ref.startsWith("#/components/schemas/"))
+    return schema;
+  if (seen.has(ref))
+    return schema;
+  const name = decodeJsonPointerPart(ref.slice("#/components/schemas/".length));
+  const components = recordValue(document.components);
+  const schemas = recordValue(components?.schemas);
+  const target = schemas?.[name];
+  if (target === undefined)
+    return schema;
+  return resolveSchema(target, document, new Set([...seen, ref]));
+}
+function schemaEnum(value) {
+  return Array.isArray(value?.enum) ? value.enum : undefined;
+}
+function schemaProperties(value) {
+  return recordValue(value?.properties);
+}
+function schemaRequired(value) {
+  return new Set(arrayValue(value?.required).filter((item) => typeof item === "string"));
+}
+function schemaType(value) {
+  return value?.type;
+}
+function addChange(changes, change) {
+  if (changes.some((item) => item.kind === change.kind && item.code === change.code && item.path === change.path && item.message === change.message))
+    return;
+  changes.push(change);
+}
+function compareSchema(baseValue, currentValue, baseDocument, currentDocument, path, direction, changes, seen = new Set) {
+  const baseSchema = resolveSchema(baseValue, baseDocument);
+  const currentSchema = resolveSchema(currentValue, currentDocument);
+  if (!baseSchema || !currentSchema)
+    return;
+  const pair = `${path}|${JSON.stringify(baseSchema)}|${JSON.stringify(currentSchema)}`;
+  if (seen.has(pair))
+    return;
+  seen.add(pair);
+  if (schemaType(baseSchema) !== undefined && schemaType(currentSchema) !== undefined && !sameJson(schemaType(baseSchema), schemaType(currentSchema))) {
+    addChange(changes, {
+      kind: "breaking",
+      code: "schema-type-changed",
+      path,
+      message: "The schema type changed."
+    });
   }
-  const byName = new Map(graph.modules.map((module) => [module.name, module]));
-  const selected = new Set([subjectModule.name]);
-  const reverseDependents = new Map;
-  for (const mod of graph.modules) {
-    for (const imp of mod.imports) {
-      const list = reverseDependents.get(imp);
-      if (list)
-        list.push(mod.name);
-      else
-        reverseDependents.set(imp, [mod.name]);
+  const baseEnum = schemaEnum(baseSchema);
+  const currentEnum = schemaEnum(currentSchema);
+  if (baseEnum && currentEnum) {
+    for (const value of baseEnum) {
+      if (!currentEnum.some((candidate) => sameJson(candidate, value))) {
+        addChange(changes, {
+          kind: "breaking",
+          code: "schema-enum-value-removed",
+          path,
+          message: "An enum value accepted by the previous contract was removed."
+        });
+        break;
+      }
     }
   }
-  for (const direction of ["imports", "dependents"]) {
-    const visited = new Set([subjectModule.name]);
-    const queue = [subjectModule.name];
-    let head = 0;
-    while (head < queue.length) {
-      const current = queue[head++];
-      if (!current)
-        continue;
-      const module = byName.get(current);
-      if (!module)
-        continue;
-      const neighbors = direction === "imports" ? module.imports : reverseDependents.get(module.name) ?? [];
-      for (const neighbor of neighbors) {
-        if (!visited.has(neighbor) && byName.has(neighbor)) {
-          visited.add(neighbor);
-          selected.add(neighbor);
-          queue.push(neighbor);
+  const baseProperties = schemaProperties(baseSchema);
+  const currentProperties = schemaProperties(currentSchema);
+  if (baseProperties && currentProperties) {
+    for (const name of sortedKeys(baseProperties)) {
+      if (currentProperties[name] === undefined) {
+        const inputRemovalIsBreaking = baseSchema.additionalProperties === false;
+        if (direction === "output" || inputRemovalIsBreaking) {
+          addChange(changes, {
+            kind: "breaking",
+            code: direction === "output" ? "response-property-removed" : "request-property-removed",
+            path: `${path}.properties.${name}`,
+            message: direction === "output" ? "A property returned by the previous contract was removed." : "A request property was removed while additional properties are rejected."
+          });
         }
+        continue;
       }
+      compareSchema(baseProperties[name], currentProperties[name], baseDocument, currentDocument, `${path}.properties.${name}`, direction, changes, seen);
     }
   }
-  const modules = graph.modules.filter((module) => selected.has(module.name));
-  const queryDocuments = graph.graphql?.documents.filter((file) => modules.some((module) => {
-    const path = relative11(dirname8(module.file), file);
-    return path !== ".." && !path.startsWith(`..${sep10}`);
-  })) ?? [];
-  const graphql = graph.graphql ? {
-    ...graph.graphql,
-    documents: queryDocuments,
-    operations: graph.graphql.operations.filter((operation) => queryDocuments.includes(operation.file))
-  } : undefined;
-  const files = [...new Set(modules.flatMap((module) => [
-    module.file,
-    ...module.providers.map((provider) => provider.file),
-    ...module.controllers.map((controller) => controller.file),
-    ...allAspects(module).flatMap((aspect) => aspect.file ? [aspect.file] : [])
-  ]).concat(graphql ? [graphql.schema, ...queryDocuments] : []))].sort();
-  const referencedTokens = new Set;
-  for (const module of modules) {
-    for (const provider of module.providers) {
-      for (const token of provider.deps)
-        referencedTokens.add(token);
-    }
-    for (const controller of module.controllers) {
-      for (const token of controller.deps)
-        referencedTokens.add(token);
+  const baseRequired = schemaRequired(baseSchema);
+  const currentRequired = schemaRequired(currentSchema);
+  if (direction === "input") {
+    for (const name of currentRequired) {
+      if (!baseRequired.has(name)) {
+        addChange(changes, {
+          kind: "breaking",
+          code: "request-property-required",
+          path: `${path}.required`,
+          message: `Request property '${name}' became required.`
+        });
+      }
     }
-  }
-  return {
-    version: 1,
-    subject: subjectModule.name,
-    modules,
-    files,
-    externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
-    executionPlans: createExecutionPlans({ ...graph, modules }),
-    routeContracts: inspectRouteContracts({ ...graph, modules }),
-    ...graphql ? { graphql } : {},
-    diagnostics: (graph.diagnostics ?? []).filter((diagnostic) => diagnostic.file === undefined || files.includes(diagnostic.file)),
-    relatedModules: {
-      imports: subjectModule.imports.filter((name) => selected.has(name)),
-      importedBy: graph.modules.filter((module) => module.imports.includes(subjectModule.name)).map((module) => module.name).sort()
+    if (baseSchema.additionalProperties !== false && currentSchema.additionalProperties === false) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-additional-properties-rejected",
+        path,
+        message: "The request schema now rejects additional properties."
+      });
     }
-  };
-}
-function allAspects(module) {
-  return [
-    ...module.aspects ?? [],
-    ...module.controllers.flatMap((controller) => controller.routes.flatMap((route) => route.aspects ?? [])),
-    ...module.commands.flatMap((command) => command.aspects ?? []),
-    ...(module.jobs ?? []).flatMap((job) => job.aspects ?? [])
-  ];
-}
-function createExecutionPlans(graph) {
-  const aspects = (boundary, refs = []) => refs.map((ref, index) => `${boundary}.aspect[${index}]:${ref.name}`);
-  return graph.modules.flatMap((module) => [
-    ...module.controllers.flatMap((controller) => controller.routes.map((route) => {
-      const command = module.commands.find((item) => item.className === route.command);
-      const path = `${controller.path}/${route.path}`.replace(/\/+/g, "/");
-      return {
-        module: module.name,
-        kind: "route",
-        name: `${route.method} ${path.length > 1 ? path.replace(/\/+$/, "") : path}`,
-        ...command ? { command: command.name } : {},
-        stages: [
-          ...aspects(`module:${module.name}`, module.aspects),
-          ...aspects("route", route.aspects),
-          ...aspects("command", command?.aspects),
-          ...command ? [
-            "commandExecutor",
-            "authorize",
-            ...command.rpc ? [`rpc:${command.rpc}`] : [
-              ...command.idempotency === "required" ? ["idempotency"] : [],
-              ...command.transaction === "required" ? ["transaction"] : []
-            ]
-          ] : [],
-          "handler",
-          ...command?.audit && !command.rpc ? ["audit"] : []
-        ]
-      };
-    })),
-    ...module.commands.map((command) => ({
-      module: module.name,
-      kind: "command",
-      name: command.name,
-      command: command.name,
-      stages: [
-        "authorize",
-        ...command.rpc ? [`rpc:${command.rpc}`] : [
-          ...command.idempotency === "required" ? ["idempotency"] : [],
-          ...command.transaction === "required" ? ["transaction"] : []
-        ],
-        ...aspects(`module:${module.name}`, module.aspects),
-        ...aspects("command", command.aspects),
-        "handler",
-        ...command.audit && !command.rpc ? ["audit"] : []
-      ]
-    })),
-    ...(module.jobs ?? []).map((job) => ({
-      module: module.name,
-      kind: "job",
-      name: job.name,
-      stages: [...aspects(`module:${module.name}`, module.aspects), ...aspects("job", job.aspects), "jobExecutor", "handler"]
-    }))
-  ]);
-}
-function doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
-  const checks = [
-    {
-      name: "project-root",
-      ok: existsSync4(rootDir),
-      detail: existsSync4(rootDir) ? rootDir : `missing: ${rootDir}`
-    },
-    {
-      name: "tsconfig",
-      ok: existsSync4(join7(rootDir, "tsconfig.json")),
-      detail: existsSync4(join7(rootDir, "tsconfig.json")) ? "tsconfig.json found" : "tsconfig.json missing"
-    },
-    {
-      name: "modules",
-      ok: graph.modules.length > 0,
-      detail: `${graph.modules.length} module(s) discovered`
-    },
-    {
-      name: "generated-artifacts",
-      ok: upToDate,
-      detail: upToDate ? "application.ts and app.manifest.json are up to date" : "generated artifacts are missing or stale"
+  } else {
+    for (const name of baseRequired) {
+      if (!currentRequired.has(name)) {
+        addChange(changes, {
+          kind: "breaking",
+          code: "response-property-optional",
+          path: `${path}.required`,
+          message: `Response property '${name}' is no longer guaranteed.`
+        });
+      }
     }
-  ];
-  const allDiagnostics = [...graph.diagnostics ?? [], ...diagnostics];
-  return {
-    checks,
-    diagnostics: allDiagnostics,
-    errors: allDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length + checks.filter((check) => !check.ok).length
-  };
-}
-function explainModule(graph, module) {
-  const dependents = graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name);
-  return [
-    `MODULE ${module.name}`,
-    `  file: ${module.file}:${module.line}`,
-    `  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`,
-    `  imported by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`,
-    `  providers: ${module.providers.length > 0 ? module.providers.map((provider) => provider.token).join(", ") : "-"}`,
-    `  controllers: ${module.controllers.length > 0 ? module.controllers.map((controller) => controller.className).join(", ") : "-"}`,
-    `  commands: ${module.commands.length > 0 ? module.commands.map((command) => command.name).join(", ") : "-"}`,
-    ...createExecutionPlans({ ...graph, modules: [module] }).map((plan) => `  execution ${plan.name}: ${plan.stages.join(" -> ")}`)
-  ].join(`
-`);
-}
-function explainProvider(graph, module, provider) {
-  const dependents = graph.modules.flatMap((candidate) => [
-    ...candidate.providers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.token}`),
-    ...candidate.controllers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.className}`)
-  ]);
-  return [
-    `PROVIDER ${provider.token}`,
-    `  module: ${module.name}`,
-    `  file: ${provider.file}:${provider.line}`,
-    `  kind: ${provider.kind}`,
-    `  scope: ${provider.scope}`,
-    `  exported: ${provider.exported ? "yes" : "no"}`,
-    `  deps: ${provider.deps.length > 0 ? provider.deps.join(", ") : "-"}`,
-    `  depended on by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`
-  ].join(`
-`);
-}
-function findProvider(graph, subject) {
-  for (const module of graph.modules) {
-    const provider = module.providers.find((candidate) => candidate.token === subject || candidate.useClass === subject || candidate.useFactoryName === subject);
-    if (provider)
-      return { module, provider };
   }
-  return;
 }
-function exportGraphMermaid(graph) {
-  const lines = ["graph TD"];
-  for (const mod of graph.modules) {
-    const safeId = mod.name.replace(/[^a-zA-Z0-9_]/g, "_");
-    lines.push(`  ${safeId}["${mod.className ?? mod.name}"]`);
-    for (const imp of mod.imports) {
-      const safeImp = imp.replace(/[^a-zA-Z0-9_]/g, "_");
-      lines.push(`  ${safeId} --> ${safeImp}`);
+function parameterKey(value) {
+  const parameter = recordValue(value);
+  const name = stringValue(parameter?.name);
+  const location = stringValue(parameter?.in);
+  return name && location ? `${location}:${name}` : undefined;
+}
+function operationParameters(pathItem, operation) {
+  const result = new Map;
+  for (const source of [pathItem.parameters, operation.parameters]) {
+    for (const item of arrayValue(source)) {
+      const parameter = recordValue(item);
+      const key = parameterKey(parameter);
+      if (parameter && key)
+        result.set(key, parameter);
     }
   }
-  return lines.join(`
-`);
+  return result;
 }
-function exportGraphDot(graph) {
-  const lines = [
-    "digraph ApplicationGraph {",
-    "  rankdir=LR;",
-    '  node [shape=box, fontname="Helvetica"];'
-  ];
-  for (const mod of graph.modules) {
-    lines.push(`  "${mod.name}" [label="${mod.className ?? mod.name}"];`);
-    for (const imp of mod.imports) {
-      lines.push(`  "${mod.name}" -> "${imp}";`);
+function parameterSchema(value) {
+  return value.schema;
+}
+function compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  const baseParameters = operationParameters(basePathItem, baseOperation);
+  const currentParameters = operationParameters(currentPathItem, currentOperation);
+  for (const key of [...baseParameters.keys()].sort()) {
+    const baseParameter = baseParameters.get(key);
+    const currentParameter = currentParameters.get(key);
+    if (!baseParameter || !currentParameter) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "parameter-removed",
+        path: `${path}.parameters.${key}`,
+        message: "A parameter from the previous contract was removed."
+      });
+      continue;
+    }
+    if (currentParameter.required === true && baseParameter.required !== true) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "parameter-required",
+        path: `${path}.parameters.${key}`,
+        message: "An optional parameter became required."
+      });
+    }
+    if (parameterSchema(baseParameter) !== undefined && parameterSchema(currentParameter) !== undefined) {
+      compareSchema(parameterSchema(baseParameter), parameterSchema(currentParameter), baseDocument, currentDocument, `${path}.parameters.${key}.schema`, "input", changes);
     }
   }
-  lines.push("}");
-  return lines.join(`
-`);
-}
-
-// src/index.ts
-init_generate();
-
-// 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 resolve13 } from "node:path";
-import { pathToFileURL } from "node:url";
-
-class OpenApiDocumentError extends Error {
-  code = "OPENAPI_DOCUMENT_INVALID";
-  constructor() {
-    super("OpenAPI document is invalid or could not be loaded.");
-    this.name = "OpenApiDocumentError";
+  for (const key of [...currentParameters.keys()].sort()) {
+    if (baseParameters.has(key))
+      continue;
+    const parameter = currentParameters.get(key);
+    if (!parameter)
+      continue;
+    addChange(changes, {
+      kind: parameter.required === true ? "breaking" : "non-breaking",
+      code: parameter.required === true ? "parameter-required" : "parameter-added",
+      path: `${path}.parameters.${key}`,
+      message: parameter.required === true ? "A new required parameter was added." : "An optional parameter was added."
+    });
   }
 }
-var HTTP_METHODS = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace"
-];
-var COMPONENT_GROUPS = [
-  "schemas",
-  "responses",
-  "parameters",
-  "requestBodies",
-  "headers",
-  "securitySchemes"
-];
-function isRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function stringValue(value) {
-  return typeof value === "string" ? value : undefined;
-}
-function recordValue(value) {
-  return isRecord(value) ? value : undefined;
-}
-function arrayValue(value) {
-  return Array.isArray(value) ? value : [];
-}
-function sortedKeys(value) {
-  return value ? Object.keys(value).sort() : [];
-}
-function sameJson(left, right) {
-  return JSON.stringify(left) === JSON.stringify(right);
-}
-function decodeJsonPointerPart(value) {
-  return value.replace(/~1/g, "/").replace(/~0/g, "~");
-}
-function resolveSchema(value, document, seen = new Set) {
-  const schema = recordValue(value);
-  if (!schema)
-    return;
-  const ref = stringValue(schema.$ref);
-  if (!ref || !ref.startsWith("#/components/schemas/"))
-    return schema;
-  if (seen.has(ref))
-    return schema;
-  const name = decodeJsonPointerPart(ref.slice("#/components/schemas/".length));
-  const components = recordValue(document.components);
-  const schemas = recordValue(components?.schemas);
-  const target = schemas?.[name];
-  if (target === undefined)
-    return schema;
-  return resolveSchema(target, document, new Set([...seen, ref]));
-}
-function schemaEnum(value) {
-  return Array.isArray(value?.enum) ? value.enum : undefined;
-}
-function schemaProperties(value) {
-  return recordValue(value?.properties);
-}
-function schemaRequired(value) {
-  return new Set(arrayValue(value?.required).filter((item) => typeof item === "string"));
-}
-function schemaType(value) {
-  return value?.type;
-}
-function addChange(changes, change) {
-  if (changes.some((item) => item.kind === change.kind && item.code === change.code && item.path === change.path && item.message === change.message))
-    return;
-  changes.push(change);
-}
-function compareSchema(baseValue, currentValue, baseDocument, currentDocument, path, direction, changes, seen = new Set) {
-  const baseSchema = resolveSchema(baseValue, baseDocument);
-  const currentSchema = resolveSchema(currentValue, currentDocument);
-  if (!baseSchema || !currentSchema)
-    return;
-  const pair = `${path}|${JSON.stringify(baseSchema)}|${JSON.stringify(currentSchema)}`;
-  if (seen.has(pair))
+function compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  const baseBody = recordValue(baseOperation.requestBody);
+  const currentBody = recordValue(currentOperation.requestBody);
+  if (!baseBody || !currentBody) {
+    if (baseBody && !currentBody) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-body-removed",
+        path: `${path}.requestBody`,
+        message: "A request body from the previous contract was removed."
+      });
+    } else if (!baseBody && currentBody?.required === true) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-body-required",
+        path: `${path}.requestBody`,
+        message: "A request body became required."
+      });
+    } else if (!baseBody && currentBody) {
+      addChange(changes, {
+        kind: "non-breaking",
+        code: "request-body-added",
+        path: `${path}.requestBody`,
+        message: "An optional request body was added."
+      });
+    }
     return;
-  seen.add(pair);
-  if (schemaType(baseSchema) !== undefined && schemaType(currentSchema) !== undefined && !sameJson(schemaType(baseSchema), schemaType(currentSchema))) {
+  }
+  if (currentBody.required === true && baseBody.required !== true) {
     addChange(changes, {
       kind: "breaking",
-      code: "schema-type-changed",
-      path,
-      message: "The schema type changed."
+      code: "request-body-required",
+      path: `${path}.requestBody`,
+      message: "An optional request body became required."
     });
   }
-  const baseEnum = schemaEnum(baseSchema);
-  const currentEnum = schemaEnum(currentSchema);
-  if (baseEnum && currentEnum) {
-    for (const value of baseEnum) {
-      if (!currentEnum.some((candidate) => sameJson(candidate, value))) {
-        addChange(changes, {
-          kind: "breaking",
-          code: "schema-enum-value-removed",
-          path,
-          message: "An enum value accepted by the previous contract was removed."
-        });
-        break;
-      }
+  const baseContent = recordValue(baseBody.content);
+  const currentContent = recordValue(currentBody.content);
+  for (const mediaType of sortedKeys(baseContent)) {
+    const baseMedia = recordValue(baseContent?.[mediaType]);
+    const currentMedia = recordValue(currentContent?.[mediaType]);
+    if (!baseMedia || !currentMedia) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "request-media-type-removed",
+        path: `${path}.requestBody.content.${mediaType}`,
+        message: "A request media type from the previous contract was removed."
+      });
+      continue;
     }
-  }
-  const baseProperties = schemaProperties(baseSchema);
-  const currentProperties = schemaProperties(currentSchema);
-  if (baseProperties && currentProperties) {
-    for (const name of sortedKeys(baseProperties)) {
-      if (currentProperties[name] === undefined) {
-        const inputRemovalIsBreaking = baseSchema.additionalProperties === false;
-        if (direction === "output" || inputRemovalIsBreaking) {
-          addChange(changes, {
-            kind: "breaking",
-            code: direction === "output" ? "response-property-removed" : "request-property-removed",
-            path: `${path}.properties.${name}`,
-            message: direction === "output" ? "A property returned by the previous contract was removed." : "A request property was removed while additional properties are rejected."
-          });
-        }
-        continue;
-      }
-      compareSchema(baseProperties[name], currentProperties[name], baseDocument, currentDocument, `${path}.properties.${name}`, direction, changes, seen);
+    if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
+      compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.requestBody.content.${mediaType}.schema`, "input", changes);
     }
   }
-  const baseRequired = schemaRequired(baseSchema);
-  const currentRequired = schemaRequired(currentSchema);
-  if (direction === "input") {
-    for (const name of currentRequired) {
-      if (!baseRequired.has(name)) {
+}
+function compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  const baseResponses = recordValue(baseOperation.responses);
+  const currentResponses = recordValue(currentOperation.responses);
+  for (const status of sortedKeys(baseResponses)) {
+    const baseResponse = recordValue(baseResponses?.[status]);
+    const currentResponse = recordValue(currentResponses?.[status]);
+    if (!baseResponse || !currentResponse) {
+      addChange(changes, {
+        kind: "breaking",
+        code: "response-removed",
+        path: `${path}.responses.${status}`,
+        message: "A response status from the previous contract was removed."
+      });
+      continue;
+    }
+    const baseContent = recordValue(baseResponse.content);
+    const currentContent = recordValue(currentResponse.content);
+    for (const mediaType of sortedKeys(baseContent)) {
+      const baseMedia = recordValue(baseContent?.[mediaType]);
+      const currentMedia = recordValue(currentContent?.[mediaType]);
+      if (!baseMedia || !currentMedia) {
         addChange(changes, {
-          kind: "breaking",
-          code: "request-property-required",
-          path: `${path}.required`,
-          message: `Request property '${name}' became required.`
+          kind: "breaking",
+          code: "response-media-type-removed",
+          path: `${path}.responses.${status}.content.${mediaType}`,
+          message: "A response media type from the previous contract was removed."
         });
+        continue;
+      }
+      if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
+        compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.responses.${status}.content.${mediaType}.schema`, "output", changes);
       }
     }
-    if (baseSchema.additionalProperties !== false && currentSchema.additionalProperties === false) {
+  }
+  for (const status of sortedKeys(currentResponses)) {
+    if (baseResponses?.[status] !== undefined)
+      continue;
+    addChange(changes, {
+      kind: "non-breaking",
+      code: "response-added",
+      path: `${path}.responses.${status}`,
+      message: "A response status was added."
+    });
+  }
+}
+function compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
+  compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
+  compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
+  compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
+  const baseSecurity = baseOperation.security;
+  const currentSecurity = currentOperation.security;
+  if (Array.isArray(currentSecurity) && currentSecurity.length > 0 && (!Array.isArray(baseSecurity) || baseSecurity.length === 0)) {
+    addChange(changes, {
+      kind: "breaking",
+      code: "security-requirement-added",
+      path: `${path}.security`,
+      message: "The operation now requires authentication or an additional security scheme."
+    });
+  }
+}
+function compareComponents(baseDocument, currentDocument, changes) {
+  const baseComponents = recordValue(baseDocument.components);
+  const currentComponents = recordValue(currentDocument.components);
+  for (const group of COMPONENT_GROUPS) {
+    const baseGroup = recordValue(baseComponents?.[group]);
+    const currentGroup = recordValue(currentComponents?.[group]);
+    for (const name of sortedKeys(baseGroup)) {
+      if (currentGroup?.[name] !== undefined)
+        continue;
       addChange(changes, {
         kind: "breaking",
-        code: "request-additional-properties-rejected",
-        path,
-        message: "The request schema now rejects additional properties."
+        code: "component-removed",
+        path: `components.${group}.${name}`,
+        message: "A reusable component from the previous contract was removed."
       });
     }
-  } else {
-    for (const name of baseRequired) {
-      if (!currentRequired.has(name)) {
-        addChange(changes, {
-          kind: "breaking",
-          code: "response-property-optional",
-          path: `${path}.required`,
-          message: `Response property '${name}' is no longer guaranteed.`
-        });
-      }
+    for (const name of sortedKeys(currentGroup)) {
+      if (baseGroup?.[name] !== undefined)
+        continue;
+      addChange(changes, {
+        kind: "non-breaking",
+        code: "component-added",
+        path: `components.${group}.${name}`,
+        message: "A reusable component was added."
+      });
     }
   }
 }
-function parameterKey(value) {
-  const parameter = recordValue(value);
-  const name = stringValue(parameter?.name);
-  const location = stringValue(parameter?.in);
-  return name && location ? `${location}:${name}` : undefined;
+function parseOpenApiDocument(value) {
+  if (!isRecord(value) || typeof value.openapi !== "string" || !/^3\.[0-9]+(?:\.[0-9]+)?$/.test(value.openapi) || !isRecord(value.info) || !isRecord(value.paths)) {
+    throw new OpenApiDocumentError;
+  }
+  return { ...value, openapi: value.openapi, info: value.info, paths: value.paths };
 }
-function operationParameters(pathItem, operation) {
-  const result = new Map;
-  for (const source of [pathItem.parameters, operation.parameters]) {
-    for (const item of arrayValue(source)) {
-      const parameter = recordValue(item);
-      const key = parameterKey(parameter);
-      if (parameter && key)
-        result.set(key, parameter);
-    }
+function serializeOpenApiJson(document, space = 2) {
+  const parsed = parseOpenApiDocument(document);
+  if (!Number.isInteger(space) || space < 0 || space > 10)
+    throw new OpenApiDocumentError;
+  const serialized = JSON.stringify(parsed, null, space);
+  if (serialized === undefined)
+    throw new OpenApiDocumentError;
+  return `${serialized}
+`;
+}
+async function readOpenApiJson(path) {
+  try {
+    const value = JSON.parse(await readFile10(resolve13(path), "utf8"));
+    return parseOpenApiDocument(value);
+  } catch (error) {
+    if (error instanceof OpenApiDocumentError)
+      throw error;
+    throw new OpenApiDocumentError;
   }
-  return result;
 }
-function parameterSchema(value) {
-  return value.schema;
+async function writeOpenApiJson(document, outputPath, space = 2) {
+  const path = resolve13(outputPath);
+  const content = serializeOpenApiJson(document, space);
+  await mkdir4(dirname8(path), { recursive: true });
+  try {
+    if (await readFile10(path, "utf8") === content)
+      return { path, written: false };
+  } catch {}
+  const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  try {
+    await writeFile5(temporaryPath, content, "utf8");
+    await rename6(temporaryPath, path);
+  } catch (error) {
+    await unlink3(temporaryPath).catch(() => {
+      return;
+    });
+    throw error;
+  }
+  return { path, written: true };
 }
-function compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  const baseParameters = operationParameters(basePathItem, baseOperation);
-  const currentParameters = operationParameters(currentPathItem, currentOperation);
-  for (const key of [...baseParameters.keys()].sort()) {
-    const baseParameter = baseParameters.get(key);
-    const currentParameter = currentParameters.get(key);
-    if (!baseParameter || !currentParameter) {
+async function loadGeneratedOpenApiDocument(modulePath) {
+  try {
+    const moduleUrl = pathToFileURL(resolve13(modulePath));
+    moduleUrl.searchParams.set("supacloud-openapi-export", "1");
+    const loaded = await import(moduleUrl.href);
+    if (!isRecord(loaded))
+      throw new OpenApiDocumentError;
+    return parseOpenApiDocument(loaded.OPENAPI_DOCUMENT);
+  } catch (error) {
+    if (error instanceof OpenApiDocumentError)
+      throw error;
+    throw new OpenApiDocumentError;
+  }
+}
+async function exportGeneratedOpenApiJson(options) {
+  const document = await loadGeneratedOpenApiDocument(options.modulePath);
+  return writeOpenApiJson(document, options.outputPath, options.space);
+}
+function diffOpenApiDocuments(baseValue, currentValue) {
+  const baseDocument = parseOpenApiDocument(baseValue);
+  const currentDocument = parseOpenApiDocument(currentValue);
+  const changes = [];
+  const basePaths = baseDocument.paths;
+  const currentPaths = currentDocument.paths;
+  for (const path of sortedKeys(basePaths)) {
+    const basePathItem = recordValue(basePaths[path]);
+    const currentPathItem = recordValue(currentPaths[path]);
+    if (!basePathItem || !currentPathItem) {
       addChange(changes, {
         kind: "breaking",
-        code: "parameter-removed",
-        path: `${path}.parameters.${key}`,
-        message: "A parameter from the previous contract was removed."
+        code: "path-removed",
+        path: `paths.${path}`,
+        message: "A path from the previous contract was removed."
       });
       continue;
     }
-    if (currentParameter.required === true && baseParameter.required !== true) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "parameter-required",
-        path: `${path}.parameters.${key}`,
-        message: "An optional parameter became required."
-      });
-    }
-    if (parameterSchema(baseParameter) !== undefined && parameterSchema(currentParameter) !== undefined) {
-      compareSchema(parameterSchema(baseParameter), parameterSchema(currentParameter), baseDocument, currentDocument, `${path}.parameters.${key}.schema`, "input", changes);
+    for (const method of HTTP_METHODS) {
+      const baseOperation = recordValue(basePathItem[method]);
+      const currentOperation = recordValue(currentPathItem[method]);
+      if (!baseOperation || !currentOperation) {
+        if (baseOperation) {
+          addChange(changes, {
+            kind: "breaking",
+            code: "operation-removed",
+            path: `paths.${path}.${method}`,
+            message: "An operation from the previous contract was removed."
+          });
+        } else if (currentOperation) {
+          addChange(changes, {
+            kind: "non-breaking",
+            code: "operation-added",
+            path: `paths.${path}.${method}`,
+            message: "An operation was added to an existing path."
+          });
+        }
+        continue;
+      }
+      compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, `paths.${path}.${method}`, changes);
     }
   }
-  for (const key of [...currentParameters.keys()].sort()) {
-    if (baseParameters.has(key))
-      continue;
-    const parameter = currentParameters.get(key);
-    if (!parameter)
+  for (const path of sortedKeys(currentPaths)) {
+    if (basePaths[path] !== undefined)
       continue;
     addChange(changes, {
-      kind: parameter.required === true ? "breaking" : "non-breaking",
-      code: parameter.required === true ? "parameter-required" : "parameter-added",
-      path: `${path}.parameters.${key}`,
-      message: parameter.required === true ? "A new required parameter was added." : "An optional parameter was added."
+      kind: "non-breaking",
+      code: "path-added",
+      path: `paths.${path}`,
+      message: "A path was added."
     });
   }
+  compareComponents(baseDocument, currentDocument, changes);
+  const breaking = changes.filter((change) => change.kind === "breaking");
+  return { ok: breaking.length === 0, breaking, changes };
 }
-function compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  const baseBody = recordValue(baseOperation.requestBody);
-  const currentBody = recordValue(currentOperation.requestBody);
-  if (!baseBody || !currentBody) {
-    if (baseBody && !currentBody) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "request-body-removed",
-        path: `${path}.requestBody`,
-        message: "A request body from the previous contract was removed."
-      });
-    } else if (!baseBody && currentBody?.required === true) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "request-body-required",
-        path: `${path}.requestBody`,
-        message: "A request body became required."
+function formatOpenApiDiff(result) {
+  if (result.changes.length === 0)
+    return "OpenAPI diff passed: no contract changes.";
+  return [
+    `OpenAPI diff ${result.ok ? "passed" : "failed"}: ${result.breaking.length} breaking change(s).`,
+    ...result.changes.map((change) => `${change.kind === "breaking" ? "BREAKING" : "NON-BREAKING"} ${change.code} at ${change.path}: ${change.message}`)
+  ].join(`
+`);
+}
+
+// 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 = resolve14(options.projectDir);
+  const compile = {
+    ...options.compile,
+    rootDir: resolve14(options.compile.rootDir),
+    outDir: resolve14(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."
       });
-    } else if (!baseBody && currentBody) {
-      addChange(changes, {
-        kind: "non-breaking",
-        code: "request-body-added",
-        path: `${path}.requestBody`,
-        message: "An optional request body was added."
+    }
+    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."
       });
     }
-    return;
+  } 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."
+    });
   }
-  if (currentBody.required === true && baseBody.required !== true) {
-    addChange(changes, {
-      kind: "breaking",
-      code: "request-body-required",
-      path: `${path}.requestBody`,
-      message: "An optional request body became required."
+  const contractsManifestPath = join7(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."
     });
   }
-  const baseContent = recordValue(baseBody.content);
-  const currentContent = recordValue(currentBody.content);
-  for (const mediaType of sortedKeys(baseContent)) {
-    const baseMedia = recordValue(baseContent?.[mediaType]);
-    const currentMedia = recordValue(currentContent?.[mediaType]);
-    if (!baseMedia || !currentMedia) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "request-media-type-removed",
-        path: `${path}.requestBody.content.${mediaType}`,
-        message: "A request media type from the previous contract was removed."
+  let openApi;
+  if (options.baselineOpenApiPath && options.currentOpenApiPath) {
+    const baselinePath = resolve14(projectDir, options.baselineOpenApiPath);
+    const currentPath = resolve14(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."
       });
-      continue;
-    }
-    if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
-      compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.requestBody.content.${mediaType}.schema`, "input", changes);
     }
+  } 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 compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  const baseResponses = recordValue(baseOperation.responses);
-  const currentResponses = recordValue(currentOperation.responses);
-  for (const status of sortedKeys(baseResponses)) {
-    const baseResponse = recordValue(baseResponses?.[status]);
-    const currentResponse = recordValue(currentResponses?.[status]);
-    if (!baseResponse || !currentResponse) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "response-removed",
-        path: `${path}.responses.${status}`,
-        message: "A response status from the previous contract was removed."
-      });
-      continue;
+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/inspect.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname9, join as join8, relative as relative11, sep as sep10 } from "node:path";
+function formatGraph(graph) {
+  const lines = [];
+  for (const module of graph.modules) {
+    lines.push(`MODULE ${module.name}`);
+    lines.push(`  file: ${module.file}:${module.line}`);
+    lines.push(`  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`);
+    lines.push(`  providers: ${module.providers.length > 0 ? module.providers.map((p) => p.token).join(", ") : "-"}`);
+    lines.push(`  controllers: ${module.controllers.length > 0 ? module.controllers.map((c) => c.className).join(", ") : "-"}`);
+    lines.push(`  commands: ${module.commands.length > 0 ? module.commands.map((c) => c.name).join(", ") : "-"}`);
+  }
+  lines.push(`EXTERNAL TOKENS ${graph.externalTokens.length > 0 ? graph.externalTokens.join(", ") : "-"}`);
+  return lines.join(`
+`);
+}
+function explainGraph(graph, subject) {
+  const module = graph.modules.find((candidate) => candidate.name === subject);
+  if (module)
+    return explainModule(graph, module);
+  const provider = findProvider(graph, subject);
+  if (provider)
+    return explainProvider(graph, provider.module, provider.provider);
+  if (graph.externalTokens.includes(subject)) {
+    const references = graph.modules.flatMap((candidate) => [
+      ...candidate.providers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.token}`),
+      ...candidate.controllers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.className}`)
+    ]);
+    return [
+      `EXTERNAL TOKEN ${subject}`,
+      "  provided by: platform runtime",
+      `  references: ${references.length > 0 ? references.join(", ") : "-"}`
+    ].join(`
+`);
+  }
+  const known = [...graph.modules.map((item) => item.name), ...graph.externalTokens].sort();
+  throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
+}
+function createContextPack(graph, subject) {
+  const subjectModule = graph.modules.find((module) => module.name === subject);
+  if (!subjectModule) {
+    throw new Error(`No module named "${subject}". Context packs require a module name.`);
+  }
+  const byName = new Map(graph.modules.map((module) => [module.name, module]));
+  const selected = new Set([subjectModule.name]);
+  const reverseDependents = new Map;
+  for (const mod of graph.modules) {
+    for (const imp of mod.imports) {
+      const list = reverseDependents.get(imp);
+      if (list)
+        list.push(mod.name);
+      else
+        reverseDependents.set(imp, [mod.name]);
     }
-    const baseContent = recordValue(baseResponse.content);
-    const currentContent = recordValue(currentResponse.content);
-    for (const mediaType of sortedKeys(baseContent)) {
-      const baseMedia = recordValue(baseContent?.[mediaType]);
-      const currentMedia = recordValue(currentContent?.[mediaType]);
-      if (!baseMedia || !currentMedia) {
-        addChange(changes, {
-          kind: "breaking",
-          code: "response-media-type-removed",
-          path: `${path}.responses.${status}.content.${mediaType}`,
-          message: "A response media type from the previous contract was removed."
-        });
+  }
+  for (const direction of ["imports", "dependents"]) {
+    const visited = new Set([subjectModule.name]);
+    const queue = [subjectModule.name];
+    let head = 0;
+    while (head < queue.length) {
+      const current = queue[head++];
+      if (!current)
         continue;
-      }
-      if (baseMedia.schema !== undefined && currentMedia.schema !== undefined) {
-        compareSchema(baseMedia.schema, currentMedia.schema, baseDocument, currentDocument, `${path}.responses.${status}.content.${mediaType}.schema`, "output", changes);
+      const module = byName.get(current);
+      if (!module)
+        continue;
+      const neighbors = direction === "imports" ? module.imports : reverseDependents.get(module.name) ?? [];
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor) && byName.has(neighbor)) {
+          visited.add(neighbor);
+          selected.add(neighbor);
+          queue.push(neighbor);
+        }
       }
     }
   }
-  for (const status of sortedKeys(currentResponses)) {
-    if (baseResponses?.[status] !== undefined)
-      continue;
-    addChange(changes, {
-      kind: "non-breaking",
-      code: "response-added",
-      path: `${path}.responses.${status}`,
-      message: "A response status was added."
-    });
+  const modules = graph.modules.filter((module) => selected.has(module.name));
+  const queryDocuments = graph.graphql?.documents.filter((file) => modules.some((module) => {
+    const path = relative11(dirname9(module.file), file);
+    return path !== ".." && !path.startsWith(`..${sep10}`);
+  })) ?? [];
+  const graphql = graph.graphql ? {
+    ...graph.graphql,
+    documents: queryDocuments,
+    operations: graph.graphql.operations.filter((operation) => queryDocuments.includes(operation.file))
+  } : undefined;
+  const files = [...new Set(modules.flatMap((module) => [
+    module.file,
+    ...module.providers.map((provider) => provider.file),
+    ...module.controllers.map((controller) => controller.file),
+    ...allAspects(module).flatMap((aspect) => aspect.file ? [aspect.file] : [])
+  ]).concat(graphql ? [graphql.schema, ...queryDocuments] : []))].sort();
+  const referencedTokens = new Set;
+  for (const module of modules) {
+    for (const provider of module.providers) {
+      for (const token of provider.deps)
+        referencedTokens.add(token);
+    }
+    for (const controller of module.controllers) {
+      for (const token of controller.deps)
+        referencedTokens.add(token);
+    }
   }
+  return {
+    version: 1,
+    subject: subjectModule.name,
+    modules,
+    files,
+    externalTokens: graph.externalTokens.filter((token) => referencedTokens.has(token)),
+    executionPlans: createExecutionPlans({ ...graph, modules }),
+    routeContracts: inspectRouteContracts({ ...graph, modules }),
+    ...graphql ? { graphql } : {},
+    diagnostics: (graph.diagnostics ?? []).filter((diagnostic) => diagnostic.file === undefined || files.includes(diagnostic.file)),
+    relatedModules: {
+      imports: subjectModule.imports.filter((name) => selected.has(name)),
+      importedBy: graph.modules.filter((module) => module.imports.includes(subjectModule.name)).map((module) => module.name).sort()
+    }
+  };
 }
-function compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes) {
-  compareParameters(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
-  compareRequestBody(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
-  compareResponses(baseOperation, currentOperation, baseDocument, currentDocument, path, changes);
-  const baseSecurity = baseOperation.security;
-  const currentSecurity = currentOperation.security;
-  if (Array.isArray(currentSecurity) && currentSecurity.length > 0 && (!Array.isArray(baseSecurity) || baseSecurity.length === 0)) {
-    addChange(changes, {
-      kind: "breaking",
-      code: "security-requirement-added",
-      path: `${path}.security`,
-      message: "The operation now requires authentication or an additional security scheme."
-    });
-  }
+function allAspects(module) {
+  return [
+    ...module.aspects ?? [],
+    ...module.controllers.flatMap((controller) => controller.routes.flatMap((route) => route.aspects ?? [])),
+    ...module.commands.flatMap((command) => command.aspects ?? []),
+    ...(module.jobs ?? []).flatMap((job) => job.aspects ?? [])
+  ];
+}
+function createExecutionPlans(graph) {
+  const aspects = (boundary, refs = []) => refs.map((ref, index) => `${boundary}.aspect[${index}]:${ref.name}`);
+  return graph.modules.flatMap((module) => [
+    ...module.controllers.flatMap((controller) => controller.routes.map((route) => {
+      const command = module.commands.find((item) => item.className === route.command);
+      const path = `${controller.path}/${route.path}`.replace(/\/+/g, "/");
+      return {
+        module: module.name,
+        kind: "route",
+        name: `${route.method} ${path.length > 1 ? path.replace(/\/+$/, "") : path}`,
+        ...command ? { command: command.name } : {},
+        stages: [
+          ...aspects(`module:${module.name}`, module.aspects),
+          ...aspects("route", route.aspects),
+          ...aspects("command", command?.aspects),
+          ...command ? [
+            "commandExecutor",
+            "authorize",
+            ...command.rpc ? [`rpc:${command.rpc}`] : [
+              ...command.idempotency === "required" ? ["idempotency"] : [],
+              ...command.transaction === "required" ? ["transaction"] : []
+            ]
+          ] : [],
+          "handler",
+          ...command?.audit && !command.rpc ? ["audit"] : []
+        ]
+      };
+    })),
+    ...module.commands.map((command) => ({
+      module: module.name,
+      kind: "command",
+      name: command.name,
+      command: command.name,
+      stages: [
+        "authorize",
+        ...command.rpc ? [`rpc:${command.rpc}`] : [
+          ...command.idempotency === "required" ? ["idempotency"] : [],
+          ...command.transaction === "required" ? ["transaction"] : []
+        ],
+        ...aspects(`module:${module.name}`, module.aspects),
+        ...aspects("command", command.aspects),
+        "handler",
+        ...command.audit && !command.rpc ? ["audit"] : []
+      ]
+    })),
+    ...(module.jobs ?? []).map((job) => ({
+      module: module.name,
+      kind: "job",
+      name: job.name,
+      stages: [...aspects(`module:${module.name}`, module.aspects), ...aspects("job", job.aspects), "jobExecutor", "handler"]
+    }))
+  ]);
 }
-function compareComponents(baseDocument, currentDocument, changes) {
-  const baseComponents = recordValue(baseDocument.components);
-  const currentComponents = recordValue(currentDocument.components);
-  for (const group of COMPONENT_GROUPS) {
-    const baseGroup = recordValue(baseComponents?.[group]);
-    const currentGroup = recordValue(currentComponents?.[group]);
-    for (const name of sortedKeys(baseGroup)) {
-      if (currentGroup?.[name] !== undefined)
-        continue;
-      addChange(changes, {
-        kind: "breaking",
-        code: "component-removed",
-        path: `components.${group}.${name}`,
-        message: "A reusable component from the previous contract was removed."
-      });
-    }
-    for (const name of sortedKeys(currentGroup)) {
-      if (baseGroup?.[name] !== undefined)
-        continue;
-      addChange(changes, {
-        kind: "non-breaking",
-        code: "component-added",
-        path: `components.${group}.${name}`,
-        message: "A reusable component was added."
-      });
+function doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
+  const checks = [
+    {
+      name: "project-root",
+      ok: existsSync4(rootDir),
+      detail: existsSync4(rootDir) ? rootDir : `missing: ${rootDir}`
+    },
+    {
+      name: "tsconfig",
+      ok: existsSync4(join8(rootDir, "tsconfig.json")),
+      detail: existsSync4(join8(rootDir, "tsconfig.json")) ? "tsconfig.json found" : "tsconfig.json missing"
+    },
+    {
+      name: "modules",
+      ok: graph.modules.length > 0,
+      detail: `${graph.modules.length} module(s) discovered`
+    },
+    {
+      name: "generated-artifacts",
+      ok: upToDate,
+      detail: upToDate ? "application.ts and app.manifest.json are up to date" : "generated artifacts are missing or stale"
     }
-  }
-}
-function parseOpenApiDocument(value) {
-  if (!isRecord(value) || typeof value.openapi !== "string" || !/^3\.[0-9]+(?:\.[0-9]+)?$/.test(value.openapi) || !isRecord(value.info) || !isRecord(value.paths)) {
-    throw new OpenApiDocumentError;
-  }
-  return { ...value, openapi: value.openapi, info: value.info, paths: value.paths };
+  ];
+  const allDiagnostics = [...graph.diagnostics ?? [], ...diagnostics];
+  return {
+    checks,
+    diagnostics: allDiagnostics,
+    errors: allDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length + checks.filter((check) => !check.ok).length
+  };
 }
-function serializeOpenApiJson(document, space = 2) {
-  const parsed = parseOpenApiDocument(document);
-  if (!Number.isInteger(space) || space < 0 || space > 10)
-    throw new OpenApiDocumentError;
-  const serialized = JSON.stringify(parsed, null, space);
-  if (serialized === undefined)
-    throw new OpenApiDocumentError;
-  return `${serialized}
-`;
+function explainModule(graph, module) {
+  const dependents = graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name);
+  return [
+    `MODULE ${module.name}`,
+    `  file: ${module.file}:${module.line}`,
+    `  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`,
+    `  imported by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`,
+    `  providers: ${module.providers.length > 0 ? module.providers.map((provider) => provider.token).join(", ") : "-"}`,
+    `  controllers: ${module.controllers.length > 0 ? module.controllers.map((controller) => controller.className).join(", ") : "-"}`,
+    `  commands: ${module.commands.length > 0 ? module.commands.map((command) => command.name).join(", ") : "-"}`,
+    ...createExecutionPlans({ ...graph, modules: [module] }).map((plan) => `  execution ${plan.name}: ${plan.stages.join(" -> ")}`)
+  ].join(`
+`);
 }
-async function readOpenApiJson(path) {
-  try {
-    const value = JSON.parse(await readFile10(resolve13(path), "utf8"));
-    return parseOpenApiDocument(value);
-  } catch (error) {
-    if (error instanceof OpenApiDocumentError)
-      throw error;
-    throw new OpenApiDocumentError;
-  }
+function explainProvider(graph, module, provider) {
+  const dependents = graph.modules.flatMap((candidate) => [
+    ...candidate.providers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.token}`),
+    ...candidate.controllers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.className}`)
+  ]);
+  return [
+    `PROVIDER ${provider.token}`,
+    `  module: ${module.name}`,
+    `  file: ${provider.file}:${provider.line}`,
+    `  kind: ${provider.kind}`,
+    `  scope: ${provider.scope}`,
+    `  exported: ${provider.exported ? "yes" : "no"}`,
+    `  deps: ${provider.deps.length > 0 ? provider.deps.join(", ") : "-"}`,
+    `  depended on by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`
+  ].join(`
+`);
 }
-async function writeOpenApiJson(document, outputPath, space = 2) {
-  const path = resolve13(outputPath);
-  const content = serializeOpenApiJson(document, space);
-  await mkdir4(dirname9(path), { recursive: true });
-  try {
-    if (await readFile10(path, "utf8") === content)
-      return { path, written: false };
-  } catch {}
-  const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
-  try {
-    await writeFile5(temporaryPath, content, "utf8");
-    await rename6(temporaryPath, path);
-  } catch (error) {
-    await unlink3(temporaryPath).catch(() => {
-      return;
-    });
-    throw error;
+function findProvider(graph, subject) {
+  for (const module of graph.modules) {
+    const provider = module.providers.find((candidate) => candidate.token === subject || candidate.useClass === subject || candidate.useFactoryName === subject);
+    if (provider)
+      return { module, provider };
   }
-  return { path, written: true };
+  return;
 }
-async function loadGeneratedOpenApiDocument(modulePath) {
-  try {
-    const moduleUrl = pathToFileURL(resolve13(modulePath));
-    moduleUrl.searchParams.set("supacloud-openapi-export", "1");
-    const loaded = await import(moduleUrl.href);
-    if (!isRecord(loaded))
-      throw new OpenApiDocumentError;
-    return parseOpenApiDocument(loaded.OPENAPI_DOCUMENT);
-  } catch (error) {
-    if (error instanceof OpenApiDocumentError)
-      throw error;
-    throw new OpenApiDocumentError;
+function exportGraphMermaid(graph) {
+  const lines = ["graph TD"];
+  for (const mod of graph.modules) {
+    const safeId = mod.name.replace(/[^a-zA-Z0-9_]/g, "_");
+    lines.push(`  ${safeId}["${mod.className ?? mod.name}"]`);
+    for (const imp of mod.imports) {
+      const safeImp = imp.replace(/[^a-zA-Z0-9_]/g, "_");
+      lines.push(`  ${safeId} --> ${safeImp}`);
+    }
   }
+  return lines.join(`
+`);
 }
-async function exportGeneratedOpenApiJson(options) {
-  const document = await loadGeneratedOpenApiDocument(options.modulePath);
-  return writeOpenApiJson(document, options.outputPath, options.space);
-}
-function diffOpenApiDocuments(baseValue, currentValue) {
-  const baseDocument = parseOpenApiDocument(baseValue);
-  const currentDocument = parseOpenApiDocument(currentValue);
-  const changes = [];
-  const basePaths = baseDocument.paths;
-  const currentPaths = currentDocument.paths;
-  for (const path of sortedKeys(basePaths)) {
-    const basePathItem = recordValue(basePaths[path]);
-    const currentPathItem = recordValue(currentPaths[path]);
-    if (!basePathItem || !currentPathItem) {
-      addChange(changes, {
-        kind: "breaking",
-        code: "path-removed",
-        path: `paths.${path}`,
-        message: "A path from the previous contract was removed."
-      });
-      continue;
-    }
-    for (const method of HTTP_METHODS) {
-      const baseOperation = recordValue(basePathItem[method]);
-      const currentOperation = recordValue(currentPathItem[method]);
-      if (!baseOperation || !currentOperation) {
-        if (baseOperation) {
-          addChange(changes, {
-            kind: "breaking",
-            code: "operation-removed",
-            path: `paths.${path}.${method}`,
-            message: "An operation from the previous contract was removed."
-          });
-        } else if (currentOperation) {
-          addChange(changes, {
-            kind: "non-breaking",
-            code: "operation-added",
-            path: `paths.${path}.${method}`,
-            message: "An operation was added to an existing path."
-          });
-        }
-        continue;
-      }
-      compareOperation(basePathItem, currentPathItem, baseOperation, currentOperation, baseDocument, currentDocument, `paths.${path}.${method}`, changes);
+function exportGraphDot(graph) {
+  const lines = [
+    "digraph ApplicationGraph {",
+    "  rankdir=LR;",
+    '  node [shape=box, fontname="Helvetica"];'
+  ];
+  for (const mod of graph.modules) {
+    lines.push(`  "${mod.name}" [label="${mod.className ?? mod.name}"];`);
+    for (const imp of mod.imports) {
+      lines.push(`  "${mod.name}" -> "${imp}";`);
     }
   }
-  for (const path of sortedKeys(currentPaths)) {
-    if (basePaths[path] !== undefined)
-      continue;
-    addChange(changes, {
-      kind: "non-breaking",
-      code: "path-added",
-      path: `paths.${path}`,
-      message: "A path was added."
-    });
-  }
-  compareComponents(baseDocument, currentDocument, changes);
-  const breaking = changes.filter((change) => change.kind === "breaking");
-  return { ok: breaking.length === 0, breaking, changes };
-}
-function formatOpenApiDiff(result) {
-  if (result.changes.length === 0)
-    return "OpenAPI diff passed: no contract changes.";
-  return [
-    `OpenAPI diff ${result.ok ? "passed" : "failed"}: ${result.breaking.length} breaking change(s).`,
-    ...result.changes.map((change) => `${change.kind === "breaking" ? "BREAKING" : "NON-BREAKING"} ${change.code} at ${change.path}: ${change.message}`)
-  ].join(`
+  lines.push("}");
+  return lines.join(`
 `);
 }
+
+// src/index.ts
+init_generate();
+init_contract_manifest();
+
 // src/config.ts
 init_graphql_options();
 import { existsSync as existsSync5 } from "node:fs";
-import { join as join8, resolve as resolve14 } from "node:path";
+import { join as join9, resolve as resolve15 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 var DEFAULT_SUPACLOUD_CONFIG = {
   graphql: false,
@@ -13078,8 +13375,8 @@ function validateGovernanceConfig(config) {
 function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
   const resolved = defineSupacloudConfig(config);
   return {
-    rootDir: resolve14(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
-    outDir: resolve14(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
+    rootDir: resolve15(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
+    outDir: resolve15(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
     include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
     strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
     requireRouteContracts: resolved.requireRouteContracts ?? DEFAULT_SUPACLOUD_CONFIG.requireRouteContracts,
@@ -13097,16 +13394,16 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders,
     graphql: resolved.graphql ? {
       ...resolved.graphql,
-      schema: resolve14(cwd, resolved.graphql.schema)
+      schema: resolve15(cwd, resolved.graphql.schema)
     } : undefined
   };
 }
 async function loadSupacloudConfig(cwd = process.cwd()) {
   const candidates = [
-    join8(cwd, "supacloud.config.ts"),
-    join8(cwd, "supacloud.config.mts"),
-    join8(cwd, "supacloud.config.js"),
-    join8(cwd, "supacloud.config.mjs")
+    join9(cwd, "supacloud.config.ts"),
+    join9(cwd, "supacloud.config.mts"),
+    join9(cwd, "supacloud.config.js"),
+    join9(cwd, "supacloud.config.mjs")
   ];
   const configPath = candidates.find((candidate) => existsSync5(candidate));
   if (!configPath)
@@ -13143,6 +13440,8 @@ export {
   TraitCompiler,
   analyzeProject,
   applyDiagnosticFix,
+  assessMigration,
+  buildContractManifest,
   buildDeliveryProject,
   camelName,
   checkProject,
@@ -13164,6 +13463,7 @@ export {
   exportGraphMermaid,
   formatDeliveryPlan,
   formatGraph,
+  formatMigrationAssessment,
   formatOpenApiDiff,
   generateApplication,
   generateDatabaseContracts,