@beignet/cli 0.0.1

package/src/inspect.ts

@@ -0,0 +1,1951 @@
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  type BeignetConfig,
+  directoryPath,
+  loadBeignetConfig,
+  normalizePath,
+  type ResolvedBeignetConfig,
+  resolveConfig,
+} from "./config.js";
+
+type InspectAppOptions = {
+  cwd?: string;
+  config?: BeignetConfig;
+  strict?: boolean;
+};
+
+type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS";
+
+export type InspectedContract = {
+  exportName: string;
+  file: string;
+  method: HttpMethod;
+  path: string;
+};
+
+export type InspectedRoute = InspectedContract & {
+  handlerFile?: string;
+  handlerExport?: HttpMethod;
+  handlerSource: "next-route" | "route-local" | "missing";
+};
+
+export type InspectDiagnostic = {
+  severity: "error" | "warning";
+  code: string;
+  message: string;
+  file?: string;
+  contract?: string;
+};
+
+export type InspectFix = {
+  code: string;
+  message: string;
+  file: string;
+};
+
+export type InspectConvention = {
+  kind: "standard" | "next" | "custom";
+  nextLayout: boolean;
+  resourceGenerator: boolean;
+  configFile?: string;
+  missingNextLayout: string[];
+  missingResourceGenerator: string[];
+};
+
+export type InspectAppResult = {
+  targetDir: string;
+  config: ResolvedBeignetConfig;
+  strict: boolean;
+  convention: InspectConvention;
+  contracts: InspectedContract[];
+  routes: InspectedRoute[];
+  diagnostics: InspectDiagnostic[];
+  fixes: InspectFix[];
+};
+
+type RouteExport = {
+  method: HttpMethod;
+  handlerFile: string;
+  contractRef?: string;
+  contractFile?: string;
+  catchAllPrefix?: string;
+  source: "next-route" | "route-local";
+};
+
+type MatchedRoutesResult = {
+  routes: InspectedRoute[];
+  unmatchedRouteHandlers: RouteExport[];
+};
+
+type ContractListItem =
+  | { kind: "contract"; name: string }
+  | {
+      kind: "list";
+      name: string;
+      file?: string;
+    };
+
+type ContractList = {
+  name: string;
+  file: string;
+  items: ContractListItem[];
+};
+
+type FeatureRouteGroup = {
+  name: string;
+  file: string;
+  contracts: Array<{
+    exportName: string;
+    file?: string;
+  }>;
+};
+
+export async function inspectApp(
+  options: InspectAppOptions = {},
+): Promise<InspectAppResult> {
+  const targetDir = path.resolve(options.cwd ?? process.cwd());
+  await assertDirectory(targetDir);
+
+  const files = await listFiles(targetDir);
+  const config = options.config
+    ? resolveConfig(options.config)
+    : await loadBeignetConfig(targetDir, files);
+  const convention = inspectConvention(files, config);
+  const contracts = await readContracts(targetDir, files, config);
+  const routeFiles = files.filter(
+    (file) =>
+      file.startsWith(`${directoryPath(config.paths.routes)}/`) &&
+      file.endsWith("/route.ts"),
+  );
+  const routeExports = await readRouteExports(targetDir, routeFiles, config);
+  const matchedRoutes = matchRoutes(contracts, routeExports);
+  const diagnostics = await inspectDiagnostics(
+    targetDir,
+    files,
+    config,
+    convention,
+    contracts,
+    matchedRoutes,
+    Boolean(options.strict),
+  );
+
+  return {
+    targetDir,
+    config,
+    strict: Boolean(options.strict),
+    convention,
+    contracts,
+    routes: matchedRoutes.routes,
+    diagnostics,
+    fixes: [],
+  };
+}
+
+export async function applyDoctorFixes(
+  options: InspectAppOptions = {},
+): Promise<InspectFix[]> {
+  const targetDir = path.resolve(options.cwd ?? process.cwd());
+  await assertDirectory(targetDir);
+
+  const files = await listFiles(targetDir);
+  const config = options.config
+    ? resolveConfig(options.config)
+    : await loadBeignetConfig(targetDir, files);
+  const convention = inspectConvention(files, config);
+  const contracts = await readContracts(targetDir, files, config);
+  const fixes: InspectFix[] = [];
+
+  const packageFix = await fixMissingTestScript(targetDir, files, convention);
+  if (packageFix) fixes.push(packageFix);
+
+  const openApiFix = await fixDirectOpenApiArrayDrift(
+    targetDir,
+    config,
+    contracts,
+  );
+  if (openApiFix) fixes.push(openApiFix);
+
+  return fixes;
+}
+
+export function formatRoutes(result: InspectAppResult): string {
+  if (result.routes.length === 0) {
+    return `No Beignet routes found in ${result.targetDir}`;
+  }
+
+  const rows = result.routes.map((route) => ({
+    method: route.method,
+    path: route.path,
+    contract: route.exportName,
+    handler:
+      route.handlerSource === "missing"
+        ? "missing"
+        : `${route.handlerFile ?? "unknown"}:${route.handlerExport ?? route.method}`,
+  }));
+
+  return table([
+    ["METHOD", "PATH", "CONTRACT", "HANDLER"],
+    ...rows.map((row) => [row.method, row.path, row.contract, row.handler]),
+  ]);
+}
+
+export function formatDoctor(result: InspectAppResult): string {
+  const fixLines =
+    result.fixes.length === 0
+      ? []
+      : [
+          `Applied ${result.fixes.length} Beignet fix${
+            result.fixes.length === 1 ? "" : "es"
+          }:`,
+          "",
+          ...result.fixes.map(
+            (fix) => `FIXED ${fix.code} ${fix.file}
+  ${fix.message}`,
+          ),
+          "",
+        ];
+
+  if (result.diagnostics.length === 0) {
+    return [...fixLines, `No Beignet drift found in ${result.targetDir}.`].join(
+      "\n",
+    );
+  }
+
+  return [
+    ...fixLines,
+    `Found ${result.diagnostics.length} Beignet issue${
+      result.diagnostics.length === 1 ? "" : "s"
+    } in ${result.targetDir}:`,
+    "",
+    ...result.diagnostics.map((diagnostic) => {
+      const location = diagnostic.file ? ` ${diagnostic.file}` : "";
+      return `${diagnostic.severity.toUpperCase()} ${diagnostic.code}${location}
+  ${diagnostic.message}`;
+    }),
+  ].join("\n");
+}
+
+async function assertDirectory(targetDir: string): Promise<void> {
+  try {
+    const stats = await stat(targetDir);
+    if (!stats.isDirectory()) {
+      throw new Error(`${targetDir} is not a directory.`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("not a directory")) {
+      throw error;
+    }
+    throw new Error(`Directory ${targetDir} does not exist.`);
+  }
+}
+
+async function listFiles(targetDir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function visit(relativeDir: string): Promise<void> {
+    const absoluteDir = path.join(targetDir, relativeDir);
+    const entries = await readdir(absoluteDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (
+        entry.name === "node_modules" ||
+        entry.name === ".next" ||
+        entry.name === ".git" ||
+        entry.name === ".turbo" ||
+        entry.name === "coverage" ||
+        entry.name === "dist"
+      ) {
+        continue;
+      }
+
+      const relativePath = normalizePath(path.join(relativeDir, entry.name));
+      if (entry.isDirectory()) {
+        await visit(relativePath);
+      } else if (entry.isFile()) {
+        files.push(relativePath);
+      }
+    }
+  }
+
+  await visit("");
+  return files.sort();
+}
+
+async function readContracts(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<InspectedContract[]> {
+  const contracts: InspectedContract[] = [];
+  const contractFiles = contractSourceFiles(files, config);
+
+  for (const file of contractFiles) {
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    contracts.push(...parseContracts(source, file));
+  }
+
+  return contracts.sort(compareContracts);
+}
+
+function inspectConvention(
+  files: string[],
+  config: ResolvedBeignetConfig,
+): InspectConvention {
+  const missingNextLayout = missingRequirements(files, [
+    `${directoryPath(config.paths.contracts)}/`,
+    `${directoryPath(config.paths.routes)}/`,
+    config.paths.server,
+  ]);
+  const missingResourceGenerator = missingRequirements(files, [
+    config.paths.appContext,
+    config.paths.infrastructurePorts,
+    config.paths.ports,
+    config.paths.server,
+    config.paths.useCaseBuilder,
+  ]);
+  const nextLayout = missingNextLayout.length === 0;
+  const resourceGenerator = missingResourceGenerator.length === 0;
+
+  return {
+    kind: resourceGenerator ? "standard" : nextLayout ? "next" : "custom",
+    nextLayout,
+    resourceGenerator,
+    configFile: config.configFile,
+    missingNextLayout,
+    missingResourceGenerator,
+  };
+}
+
+function missingRequirements(
+  files: string[],
+  requirements: string[],
+): string[] {
+  return requirements.filter(
+    (requirement) => !hasRequirement(files, requirement),
+  );
+}
+
+function hasRequirement(files: string[], requirement: string): boolean {
+  if (requirement.endsWith("/")) {
+    return files.some((file) => file.startsWith(requirement));
+  }
+
+  return files.includes(requirement);
+}
+
+function parseContracts(source: string, file: string): InspectedContract[] {
+  const contracts: InspectedContract[] = [];
+  const groupPrefixes = parseContractGroupPrefixes(source);
+  const exportRegex =
+    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=([\s\S]*?)(?=\nexport const\s+[A-Za-z_$][\w$]*\s*=|$)/g;
+
+  for (const exportMatch of source.matchAll(exportRegex)) {
+    const block = exportMatch[2];
+    const methodMatch =
+      /([A-Za-z_$][\w$]*)\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["']\s*\)/.exec(
+        block,
+      );
+    if (methodMatch) {
+      const receiver = methodMatch[1];
+      const pathPrefix = groupPrefixes.get(receiver) ?? "";
+      const routePath = joinContractPaths(pathPrefix, methodMatch[3]);
+
+      contracts.push({
+        exportName: exportMatch[1],
+        file,
+        method: methodMatch[2].toUpperCase() as HttpMethod,
+        path: routePath,
+      });
+      continue;
+    }
+
+    const directContract = parseDirectContract(block);
+    if (directContract) {
+      contracts.push({
+        exportName: exportMatch[1],
+        file,
+        method: directContract.method,
+        path: normalizeContractPath(directContract.path),
+      });
+    }
+  }
+
+  return contracts;
+}
+
+function parseDirectContract(
+  block: string,
+): { method: HttpMethod; path: string } | undefined {
+  const configMatch = /createContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
+  if (!configMatch) return undefined;
+
+  const configSource = configMatch[1];
+  const methodMatch = /method\s*:\s*["']([^"']+)["']/.exec(configSource);
+  const pathMatch = /path\s*:\s*["']([^"']+)["']/.exec(configSource);
+  if (!methodMatch || !pathMatch) return undefined;
+
+  const method = methodMatch[1].toUpperCase();
+  if (!isHttpMethod(method)) return undefined;
+
+  return { method, path: pathMatch[1] };
+}
+
+function isHttpMethod(method: string): method is HttpMethod {
+  return ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].includes(
+    method,
+  );
+}
+
+function parseContractGroupPrefixes(source: string): Map<string, string> {
+  const assignments = [
+    ...source.matchAll(
+      /(?:^|\n)(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*([\s\S]*?);/g,
+    ),
+  ].map((match) => ({
+    name: match[1],
+    expression: match[2],
+  }));
+  const prefixes = new Map<string, string>();
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const assignment of assignments) {
+      if (prefixes.has(assignment.name)) continue;
+
+      const basePrefix = baseGroupPrefix(assignment.expression, prefixes);
+      if (basePrefix === undefined) continue;
+
+      const prefix = prefixCalls(assignment.expression).reduce(
+        (current, next) => joinContractPaths(current, next),
+        basePrefix,
+      );
+      prefixes.set(assignment.name, prefix);
+      changed = true;
+    }
+  }
+
+  return prefixes;
+}
+
+function baseGroupPrefix(
+  expression: string,
+  prefixes: Map<string, string>,
+): string | undefined {
+  if (expression.includes("createContractGroup(")) return "";
+
+  const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
+  if (!baseMatch) return undefined;
+
+  return prefixes.get(baseMatch[1]);
+}
+
+function prefixCalls(expression: string): string[] {
+  return [...expression.matchAll(/\.prefix\(\s*["']([^"']+)["']\s*\)/g)].map(
+    (match) => match[1],
+  );
+}
+
+function joinContractPaths(prefix: string, routePath: string): string {
+  if (!prefix) return normalizeContractPath(routePath);
+  const segments = [
+    ...prefix.split("/").filter(Boolean),
+    ...routePath.split("/").filter(Boolean),
+  ];
+  return `/${segments.join("/")}`;
+}
+
+function normalizeContractPath(routePath: string): string {
+  const segments = routePath.split("/").filter(Boolean);
+  return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+
+async function readRouteExports(
+  targetDir: string,
+  routeFiles: string[],
+  config: ResolvedBeignetConfig,
+): Promise<Map<string, RouteExport[]>> {
+  const routeExports = new Map<string, RouteExport[]>();
+
+  for (const file of routeFiles) {
+    const routePath = nextRoutePath(file, config.paths.routes);
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    routeExports.set(file, parseRouteExports(source, file, routePath, config));
+  }
+
+  return routeExports;
+}
+
+function parseRouteExports(
+  source: string,
+  handlerFile: string,
+  routePath: string,
+  config: ResolvedBeignetConfig,
+): RouteExport[] {
+  const exports: RouteExport[] = [];
+  const imports = parseNamedImports(source, config);
+  const exportRegex =
+    /export const\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*=\s*([^;\n]+)/g;
+
+  for (const match of source.matchAll(exportRegex)) {
+    const method = match[1] as HttpMethod;
+    const expression = match[2];
+    const contractMatch =
+      /server\.route\(\s*([A-Za-z_$][\w$]*)\s*\)\.handle/.exec(expression);
+
+    if (contractMatch) {
+      const localName = contractMatch[1];
+      const imported = imports.get(localName);
+      exports.push({
+        method,
+        handlerFile,
+        contractRef: imported?.importedName ?? localName,
+        contractFile: imported?.contractFile,
+        source: "route-local",
+      });
+      continue;
+    }
+
+    if (/server\.api\b/.test(expression)) {
+      exports.push({
+        method,
+        handlerFile,
+        contractRef: routePath,
+        catchAllPrefix: catchAllRoutePrefix(routePath),
+        source: "next-route",
+      });
+    }
+  }
+
+  return exports;
+}
+
+function catchAllRoutePrefix(routePath: string): string | undefined {
+  const segments = routePath.split("/").filter(Boolean);
+  const catchAllIndex = segments.findIndex((segment) => segment.endsWith("*"));
+  if (catchAllIndex === -1) return undefined;
+
+  const prefixSegments = segments.slice(0, catchAllIndex);
+  return prefixSegments.length === 0 ? "/" : `/${prefixSegments.join("/")}`;
+}
+
+function parseNamedImports(
+  source: string,
+  config: ResolvedBeignetConfig,
+  importerFile?: string,
+): Map<
+  string,
+  {
+    importedName: string;
+    contractFile?: string;
+  }
+> {
+  const imports = new Map<
+    string,
+    {
+      importedName: string;
+      contractFile?: string;
+    }
+  >();
+  const importRegex = /import\s+\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
+
+  for (const match of source.matchAll(importRegex)) {
+    const sourcePath = match[2];
+    const contractFile = contractFileFromImport(
+      sourcePath,
+      config,
+      importerFile,
+    );
+    for (const member of match[1].split(",")) {
+      const parsed = parseImportMember(member);
+      if (!parsed) continue;
+      imports.set(parsed.localName, {
+        importedName: parsed.importedName,
+        contractFile,
+      });
+    }
+  }
+
+  return imports;
+}
+
+function parseImportMember(
+  member: string,
+): { importedName: string; localName: string } | undefined {
+  const trimmed = member.trim();
+  if (!trimmed) return undefined;
+
+  const aliasMatch = /^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/.exec(
+    trimmed,
+  );
+  if (aliasMatch) {
+    return {
+      importedName: aliasMatch[1],
+      localName: aliasMatch[2],
+    };
+  }
+
+  if (/^[A-Za-z_$][\w$]*$/.test(trimmed)) {
+    return {
+      importedName: trimmed,
+      localName: trimmed,
+    };
+  }
+
+  return undefined;
+}
+
+function contractFileFromImport(
+  sourcePath: string,
+  config: ResolvedBeignetConfig,
+  importerFile?: string,
+): string | undefined {
+  const contractsPath = directoryPath(config.paths.contracts);
+  const aliasPrefix = `@/${contractsPath}/`;
+  const aliasExact = `@/${contractsPath}`;
+  const relativePrefix = `${contractsPath}/`;
+  const relativeExact = contractsPath;
+
+  if (sourcePath === aliasExact || sourcePath === relativeExact) {
+    return `${contractsPath}/index.ts`;
+  }
+  if (sourcePath.startsWith(aliasPrefix)) {
+    return `${sourcePath.slice("@/".length)}.ts`;
+  }
+
+  if (sourcePath.startsWith(relativePrefix)) {
+    return `${sourcePath}.ts`;
+  }
+
+  if (importerFile && sourcePath.startsWith(".")) {
+    const resolved = normalizePath(
+      path.join(path.dirname(importerFile), sourcePath),
+    );
+    return `${resolved}.ts`;
+  }
+
+  return undefined;
+}
+
+function matchRoutes(
+  contracts: InspectedContract[],
+  routeExports: Map<string, RouteExport[]>,
+): MatchedRoutesResult {
+  const matched = new Set<string>();
+  const routes: InspectedRoute[] = [];
+  const unmatchedRouteHandlers: RouteExport[] = [];
+  const exports = [...routeExports.entries()].flatMap(
+    ([handlerFile, entries]) =>
+      entries.map((routeExport) => ({ handlerFile, routeExport })),
+  );
+
+  for (const { handlerFile, routeExport } of exports.filter(
+    ({ routeExport }) => !routeExport.catchAllPrefix,
+  )) {
+    const contract = findContract(contracts, routeExport);
+    if (!contract) {
+      unmatchedRouteHandlers.push(routeExport);
+      continue;
+    }
+
+    const key = contractKey(contract);
+    if (matched.has(key)) continue;
+    matched.add(key);
+    routes.push({
+      ...contract,
+      handlerFile,
+      handlerExport: routeExport.method,
+      handlerSource: routeExport.source,
+    });
+  }
+
+  for (const { handlerFile, routeExport } of exports.filter(
+    ({ routeExport }) => routeExport.catchAllPrefix,
+  )) {
+    const contractsForExport = findContracts(contracts, routeExport);
+    if (contractsForExport.length === 0) continue;
+
+    for (const contract of contractsForExport) {
+      const key = contractKey(contract);
+      if (matched.has(key)) continue;
+
+      matched.add(key);
+      routes.push({
+        ...contract,
+        handlerFile,
+        handlerExport: routeExport.method,
+        handlerSource: routeExport.source,
+      });
+    }
+  }
+
+  for (const contract of contracts) {
+    if (!matched.has(contractKey(contract))) {
+      routes.push({
+        ...contract,
+        handlerSource: "missing",
+      });
+    }
+  }
+
+  return {
+    routes: routes.sort(compareContracts),
+    unmatchedRouteHandlers,
+  };
+}
+
+function findContract(
+  contracts: InspectedContract[],
+  routeExport: RouteExport,
+): InspectedContract | undefined {
+  return findContracts(contracts, routeExport)[0];
+}
+
+function findContracts(
+  contracts: InspectedContract[],
+  routeExport: RouteExport,
+): InspectedContract[] {
+  if (routeExport.source === "route-local") {
+    const contract = contracts.find(
+      (contract) =>
+        contract.exportName === routeExport.contractRef &&
+        (!routeExport.contractFile ||
+          contract.file === routeExport.contractFile ||
+          contract.file ===
+            routeExport.contractFile.replace(/\.ts$/, "/index.ts")),
+    );
+    return contract ? [contract] : [];
+  }
+
+  if (routeExport.catchAllPrefix) {
+    const catchAllPrefix = routeExport.catchAllPrefix;
+    return contracts.filter(
+      (contract) =>
+        contract.method === routeExport.method &&
+        contractPathMatchesCatchAll(contract.path, catchAllPrefix),
+    );
+  }
+
+  const contract = contracts.find(
+    (contract) =>
+      contract.path === routeExport.contractRef &&
+      contract.method === routeExport.method,
+  );
+  return contract ? [contract] : [];
+}
+
+function contractPathMatchesCatchAll(
+  contractPath: string,
+  catchAllPrefix: string,
+): boolean {
+  return (
+    contractPath === catchAllPrefix ||
+    contractPath.startsWith(`${catchAllPrefix}/`)
+  );
+}
+
+async function inspectDiagnostics(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  contracts: InspectedContract[],
+  matchedRoutes: MatchedRoutesResult,
+  strict: boolean,
+): Promise<InspectDiagnostic[]> {
+  const diagnostics: InspectDiagnostic[] = [];
+
+  if (!convention.nextLayout) {
+    diagnostics.push({
+      severity: "warning",
+      code: "CK_APP_LAYOUT_NOT_FOUND",
+      message: `This directory does not match the standard Beignet app layout. CLI inspection expects ${directoryPath(config.paths.contracts)}/, ${directoryPath(config.paths.routes)}/, and ${config.paths.server}. Missing: ${convention.missingNextLayout.join(", ")}. Add the missing app files or configure their paths in beignet.config.ts.`,
+    });
+  }
+
+  for (const route of matchedRoutes.routes) {
+    if (route.handlerSource !== "missing") continue;
+    diagnostics.push({
+      severity: "error",
+      code: "CK_ROUTE_MISSING",
+      file: route.file,
+      contract: route.exportName,
+      message: `${route.exportName} (${route.method} ${route.path}) has no matching Next route handler. Add ${methodArticle(route.method)} ${route.method} export to ${directoryPath(config.paths.routes)}/[[...path]]/route.ts or a matching route file, or remove the unused contract.`,
+    });
+  }
+
+  for (const routeHandler of matchedRoutes.unmatchedRouteHandlers) {
+    diagnostics.push(unmatchedRouteDiagnostic(routeHandler));
+  }
+
+  diagnostics.push(
+    ...(await inspectPackageScripts(targetDir, files, convention)),
+    ...(await inspectOpenApiDrift(targetDir, files, config, contracts)),
+    ...(await inspectFeatureRouteRegistration(
+      targetDir,
+      files,
+      config,
+      convention,
+      contracts,
+    )),
+    ...(await inspectPortProviderDrift(targetDir, files, config, convention)),
+    ...(await inspectResourceSlices(
+      targetDir,
+      files,
+      config,
+      convention,
+      strict,
+    )),
+  );
+
+  return dedupeDiagnostics(diagnostics);
+}
+
+async function inspectPortProviderDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const portsSource = files.includes(config.paths.ports)
+    ? await readFile(path.join(targetDir, config.paths.ports), "utf8")
+    : "";
+  const packageJson = files.includes("package.json")
+    ? (JSON.parse(
+        await readFile(path.join(targetDir, "package.json"), "utf8"),
+      ) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        peerDependencies?: Record<string, string>;
+      })
+    : undefined;
+  const installedPackages = new Set([
+    ...Object.keys(packageJson?.dependencies ?? {}),
+    ...Object.keys(packageJson?.devDependencies ?? {}),
+    ...Object.keys(packageJson?.peerDependencies ?? {}),
+  ]);
+
+  for (const expected of canonicalProviderPorts) {
+    if (!installedPackages.has(expected.packageName)) continue;
+    if (portsSource.includes(`${expected.portName}:`)) continue;
+    diagnostics.push({
+      severity: "warning",
+      code: "CK_PROVIDER_PORT_MISSING",
+      file: config.paths.ports,
+      message: `${expected.packageName} is installed, but AppPorts does not declare ${expected.portName}: ${expected.portType}. Add the canonical port to AppPorts or remove the unused provider package.`,
+    });
+  }
+
+  const portDir = directoryPath(path.dirname(config.paths.ports));
+  for (const file of files) {
+    if (
+      !file.startsWith(`${portDir}/`) ||
+      !file.endsWith(".ts") ||
+      file === config.paths.ports ||
+      file.endsWith("-repository.ts")
+    ) {
+      continue;
+    }
+
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    const generatedPort =
+      /export interface ([A-Z]\w*Port)\s*\{[\s\S]*execute\(/.exec(source);
+    if (!generatedPort) continue;
+    const fakeFactory = `createFake${generatedPort[1].replace(/Port$/, "")}Port`;
+    if (source.includes(fakeFactory)) continue;
+    diagnostics.push({
+      severity: "warning",
+      code: "CK_PORT_TEST_FAKE_MISSING",
+      file,
+      message: `${file} looks like a generated port, but it does not export ${fakeFactory}(). Re-run make port with --force or add a small fake adapter so use-case tests can stay vendor-free.`,
+    });
+  }
+
+  return diagnostics;
+}
+
+const canonicalProviderPorts = [
+  {
+    packageName: "@beignet/provider-auth-better-auth",
+    portName: "auth",
+    portType: "AuthPort",
+  },
+  {
+    packageName: "@beignet/provider-event-bus-memory",
+    portName: "eventBus",
+    portType: "EventBusPort",
+  },
+  {
+    packageName: "@beignet/provider-inngest",
+    portName: "jobs",
+    portType: "JobDispatcherPort",
+  },
+  {
+    packageName: "@beignet/provider-logger-pino",
+    portName: "logger",
+    portType: "LoggerPort",
+  },
+  {
+    packageName: "@beignet/provider-mail-resend",
+    portName: "mailer",
+    portType: "MailerPort",
+  },
+  {
+    packageName: "@beignet/provider-mail-smtp",
+    portName: "mailer",
+    portType: "MailerPort",
+  },
+  {
+    packageName: "@beignet/provider-rate-limit-upstash",
+    portName: "rateLimit",
+    portType: "RateLimitPort",
+  },
+  {
+    packageName: "@beignet/provider-redis",
+    portName: "cache",
+    portType: "CachePort",
+  },
+] as const;
+
+async function inspectPackageScripts(
+  targetDir: string,
+  files: string[],
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator || !files.includes("package.json")) {
+    return [];
+  }
+
+  const packageJson = JSON.parse(
+    await readFile(path.join(targetDir, "package.json"), "utf8"),
+  ) as {
+    scripts?: Record<string, string>;
+  };
+
+  if (packageJson.scripts?.test) return [];
+
+  return [
+    {
+      severity: "warning",
+      code: "CK_PACKAGE_TEST_SCRIPT_MISSING",
+      file: "package.json",
+      message:
+        'package.json does not define a test script. Add "test": "bun test" or run beignet doctor --fix.',
+    },
+  ];
+}
+
+async function fixMissingTestScript(
+  targetDir: string,
+  files: string[],
+  convention: InspectConvention,
+): Promise<InspectFix | undefined> {
+  if (!convention.resourceGenerator || !files.includes("package.json")) {
+    return undefined;
+  }
+
+  const filePath = path.join(targetDir, "package.json");
+  const original = await readFile(filePath, "utf8");
+  const packageJson = JSON.parse(original) as {
+    scripts?: Record<string, string>;
+  };
+  packageJson.scripts = packageJson.scripts ?? {};
+  if (packageJson.scripts.test) return undefined;
+
+  packageJson.scripts.test = "bun test";
+  const next = `${JSON.stringify(packageJson, null, "\t")}\n`;
+  if (next === original) return undefined;
+
+  await writeFile(filePath, next);
+  return {
+    code: "CK_PACKAGE_TEST_SCRIPT_MISSING",
+    file: "package.json",
+    message: 'Added "test": "bun test".',
+  };
+}
+
+function unmatchedRouteDiagnostic(
+  routeHandler: RouteExport,
+): InspectDiagnostic {
+  if (routeHandler.source === "next-route") {
+    return {
+      severity: "error",
+      code: "CK_ROUTE_HANDLER_ORPHANED",
+      file: routeHandler.handlerFile,
+      message: `${routeHandler.handlerFile} exports ${routeHandler.method} = server.api, but no known contract matches ${routeHandler.method} ${routeHandler.contractRef}. Add the matching contract, update the route file path, or remove the handler export.`,
+    };
+  }
+
+  const contractLabel = routeHandler.contractFile
+    ? `${routeHandler.contractFile}#${routeHandler.contractRef}`
+    : routeHandler.contractRef;
+
+  return {
+    severity: "error",
+    code: "CK_ROUTE_HANDLER_UNKNOWN_CONTRACT",
+    file: routeHandler.handlerFile,
+    contract: routeHandler.contractRef,
+    message: `${routeHandler.handlerFile} references ${contractLabel}, but that contract was not found under the configured contracts path. Fix the import/export or remove the route handler.`,
+  };
+}
+
+function dedupeDiagnostics(
+  diagnostics: InspectDiagnostic[],
+): InspectDiagnostic[] {
+  const seen = new Set<string>();
+  const deduped: InspectDiagnostic[] = [];
+
+  for (const diagnostic of diagnostics) {
+    const key = [
+      diagnostic.code,
+      diagnostic.file ?? "",
+      diagnostic.contract ?? "",
+      diagnostic.message,
+    ].join(":");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(diagnostic);
+  }
+
+  return deduped;
+}
+
+async function inspectOpenApiDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  contracts: InspectedContract[],
+): Promise<InspectDiagnostic[]> {
+  const routePath = path.join(targetDir, config.paths.openapiRoute);
+  try {
+    await stat(routePath);
+  } catch {
+    return [];
+  }
+
+  const source = await readFile(routePath, "utf8");
+  const listedContracts = await openApiContracts(
+    targetDir,
+    files,
+    config,
+    source,
+  );
+  if (!listedContracts) {
+    return [];
+  }
+
+  return contracts
+    .filter((contract) => !listedContracts.has(contract.exportName))
+    .map((contract) => ({
+      severity: "warning" as const,
+      code: "CK_OPENAPI_MISSING",
+      file: config.paths.openapiRoute,
+      contract: contract.exportName,
+      message: `${contract.exportName} (${contract.method} ${contract.path}) is not listed in createOpenAPIHandler. Add it to the OpenAPI contract array/list or remove the contract from the documented API surface.`,
+    }));
+}
+
+async function inspectFeatureRouteRegistration(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  contracts: InspectedContract[],
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+  if (!files.includes(config.paths.server)) return [];
+
+  const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
+  if (routeGroups.length === 0) return [];
+
+  const serverSource = await readFile(
+    path.join(targetDir, config.paths.server),
+    "utf8",
+  );
+  const registeredGroups = await registeredRouteGroupsForServer(
+    targetDir,
+    files,
+    config,
+    serverSource,
+  );
+  const diagnostics: InspectDiagnostic[] = [];
+
+  for (const routeGroup of routeGroups) {
+    if (registeredGroups.has(routeGroup.name)) continue;
+
+    for (const routeGroupContract of routeGroup.contracts) {
+      const contract = findRouteGroupContract(contracts, routeGroupContract);
+      diagnostics.push({
+        severity: "error",
+        code: "CK_ROUTE_GROUP_UNREGISTERED",
+        file: config.paths.server,
+        contract: routeGroupContract.exportName,
+        message: contract
+          ? `${routeGroup.file} declares ${routeGroup.name} for ${contract.exportName} (${contract.method} ${contract.path}), but ${routeGroup.name} is not registered in defineRoutes([...]) in ${config.paths.server}. Import ${routeGroup.name} and add it to the central route list.`
+          : `${routeGroup.file} declares ${routeGroup.name} for ${routeGroupContract.exportName}, but ${routeGroup.name} is not registered in defineRoutes([...]) in ${config.paths.server}. Import ${routeGroup.name} and add it to the central route list.`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+async function readFeatureRouteGroups(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<FeatureRouteGroup[]> {
+  const featuresPath = `${directoryPath(config.paths.features)}/`;
+  const routeFiles = files.filter(
+    (file) => file.startsWith(featuresPath) && file.endsWith("/routes.ts"),
+  );
+  const routeGroups: FeatureRouteGroup[] = [];
+
+  for (const file of routeFiles) {
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    const imports = parseNamedImports(source, config, file);
+    routeGroups.push(...parseFeatureRouteGroups(source, file, imports));
+  }
+
+  return routeGroups;
+}
+
+function parseFeatureRouteGroups(
+  source: string,
+  file: string,
+  imports: ReturnType<typeof parseNamedImports>,
+): FeatureRouteGroup[] {
+  const routeGroups: FeatureRouteGroup[] = [];
+  const exportRegex =
+    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=\s*defineRouteGroup(?:<[^>]+>)?\(\s*(?:\{[\s\S]*?routes:\s*)?\[([\s\S]*?)\]\s*(?:,?\s*\})?\s*\)\s*;?/g;
+
+  for (const match of source.matchAll(exportRegex)) {
+    const contracts = [...match[2].matchAll(/contract:\s*([^,\n}]+)/g)]
+      .map((contractMatch) =>
+        routeGroupContractRef(contractMatch[1].trim(), imports),
+      )
+      .filter((contract): contract is FeatureRouteGroup["contracts"][number] =>
+        Boolean(contract),
+      );
+
+    routeGroups.push({
+      name: match[1],
+      file,
+      contracts,
+    });
+  }
+
+  return routeGroups;
+}
+
+function routeGroupContractRef(
+  expression: string,
+  imports: ReturnType<typeof parseNamedImports>,
+): FeatureRouteGroup["contracts"][number] | undefined {
+  const namedMatch = /^([A-Za-z_$][\w$]*)$/.exec(expression);
+  if (namedMatch) {
+    const localName = namedMatch[1];
+    const imported = imports.get(localName);
+    return {
+      exportName: imported?.importedName ?? localName,
+      file: imported?.contractFile,
+    };
+  }
+
+  const namespaceMatch = /^[A-Za-z_$][\w$]*\.([A-Za-z_$][\w$]*)$/.exec(
+    expression,
+  );
+  if (namespaceMatch) {
+    return {
+      exportName: namespaceMatch[1],
+    };
+  }
+
+  return undefined;
+}
+
+function registeredRouteGroups(source: string): Set<string> {
+  const defineRoutesMatch = /defineRoutes(?:<[^>]+>)?\(\[/.exec(source);
+  if (!defineRoutesMatch) return new Set();
+
+  const defineRoutesSource = source.slice(defineRoutesMatch.index);
+  const defineRoutesEnd = defineRoutesSource.indexOf("]),");
+  const searchSource =
+    defineRoutesEnd === -1
+      ? defineRoutesSource
+      : defineRoutesSource.slice(0, defineRoutesEnd);
+
+  return new Set(
+    [...searchSource.matchAll(/\b([A-Za-z_$][\w$]*)\b/g)].map(
+      (match) => match[1],
+    ),
+  );
+}
+
+async function registeredRouteGroupsForServer(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  serverSource: string,
+): Promise<Set<string>> {
+  const registeredGroups = registeredRouteGroups(serverSource);
+  const imports = parseNamedImports(serverSource, config, config.paths.server);
+
+  for (const identifier of routeOptionIdentifiers(serverSource)) {
+    const imported = imports.get(identifier);
+    if (!imported?.contractFile || !files.includes(imported.contractFile)) {
+      continue;
+    }
+
+    const source = await readFile(path.join(targetDir, imported.contractFile), {
+      encoding: "utf8",
+    });
+    for (const routeGroup of registeredRouteGroups(source)) {
+      registeredGroups.add(routeGroup);
+    }
+  }
+
+  return registeredGroups;
+}
+
+function routeOptionIdentifiers(source: string): Set<string> {
+  const identifiers = new Set<string>();
+  for (const match of source.matchAll(
+    /(?:^|[,{])\s*routes\s*:\s*([A-Za-z_$][\w$]*)/g,
+  )) {
+    identifiers.add(match[1]);
+  }
+
+  if (/(?:^|[,{])\s*routes\s*(?:[,}])/m.test(source)) {
+    identifiers.add("routes");
+  }
+
+  return identifiers;
+}
+
+function findRouteGroupContract(
+  contracts: InspectedContract[],
+  routeGroupContract: FeatureRouteGroup["contracts"][number],
+): InspectedContract | undefined {
+  return contracts.find(
+    (contract) =>
+      contract.exportName === routeGroupContract.exportName &&
+      (!routeGroupContract.file ||
+        contract.file === routeGroupContract.file ||
+        contract.file ===
+          routeGroupContract.file.replace(/\.ts$/, "/index.ts")),
+  );
+}
+
+async function fixDirectOpenApiArrayDrift(
+  targetDir: string,
+  config: ResolvedBeignetConfig,
+  contracts: InspectedContract[],
+): Promise<InspectFix | undefined> {
+  const routePath = path.join(targetDir, config.paths.openapiRoute);
+  let source: string;
+  try {
+    source = await readFile(routePath, "utf8");
+  } catch {
+    return undefined;
+  }
+
+  const firstArg = firstCreateOpenAPIHandlerArgInfo(source);
+  if (!firstArg?.text.startsWith("[")) return undefined;
+
+  const listedContracts = contractsFromArrayExpression(firstArg.text);
+  const missingContracts = contracts.filter(
+    (contract) => !listedContracts.has(contract.exportName),
+  );
+  if (missingContracts.length === 0) return undefined;
+
+  if (
+    missingContracts.some(
+      (contract) => !hasImportedIdentifier(source, contract.exportName),
+    )
+  ) {
+    return undefined;
+  }
+
+  const nextArray = appendToArrayExpression(
+    firstArg.text,
+    missingContracts.map((contract) => contract.exportName),
+  );
+  const next = `${source.slice(0, firstArg.start)}${nextArray}${source.slice(
+    firstArg.end,
+  )}`;
+  if (next === source) return undefined;
+
+  await writeFile(routePath, next);
+  return {
+    code: "CK_OPENAPI_MISSING",
+    file: config.paths.openapiRoute,
+    message: `Added ${missingContracts
+      .map((contract) => contract.exportName)
+      .join(", ")} to the direct createOpenAPIHandler contract array.`,
+  };
+}
+
+async function openApiContracts(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  source: string,
+): Promise<Set<string> | undefined> {
+  const firstArg = firstCreateOpenAPIHandlerArg(source);
+  if (!firstArg) return undefined;
+
+  if (firstArg.startsWith("[")) {
+    return contractsFromArrayExpression(firstArg);
+  }
+
+  const identifier = /^([A-Za-z_$][\w$]*)$/.exec(firstArg)?.[1];
+  if (!identifier) return undefined;
+
+  const imports = parseNamedImports(source, config);
+  const imported = imports.get(identifier);
+  const listFile = imported?.contractFile ?? config.paths.openapiRoute;
+
+  return resolveContractList(
+    await readContractLists(targetDir, files, config),
+    listFile,
+    imported?.importedName ?? identifier,
+  );
+}
+
+function firstCreateOpenAPIHandlerArg(source: string): string | undefined {
+  return firstCreateOpenAPIHandlerArgInfo(source)?.text;
+}
+
+function firstCreateOpenAPIHandlerArgInfo(
+  source: string,
+): { text: string; start: number; end: number } | undefined {
+  const start = source.indexOf("createOpenAPIHandler(");
+  if (start === -1) return undefined;
+
+  let depth = 0;
+  let inString: string | undefined;
+  let escaped = false;
+  const argStart = start + "createOpenAPIHandler(".length;
+
+  for (let index = argStart; index < source.length; index++) {
+    const char = source[index];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === inString) {
+        inString = undefined;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === "`") {
+      inString = char;
+      continue;
+    }
+
+    if (char === "[" || char === "(" || char === "{") {
+      depth++;
+      continue;
+    }
+
+    if (char === "]" || char === ")" || char === "}") {
+      if (depth === 0) {
+        return trimmedSlice(source, argStart, index);
+      }
+      depth--;
+      continue;
+    }
+
+    if (char === "," && depth === 0) {
+      return trimmedSlice(source, argStart, index);
+    }
+  }
+
+  return undefined;
+}
+
+function trimmedSlice(
+  source: string,
+  start: number,
+  end: number,
+): { text: string; start: number; end: number } {
+  let trimmedStart = start;
+  let trimmedEnd = end;
+
+  while (trimmedStart < trimmedEnd && /\s/.test(source[trimmedStart])) {
+    trimmedStart++;
+  }
+  while (trimmedEnd > trimmedStart && /\s/.test(source[trimmedEnd - 1])) {
+    trimmedEnd--;
+  }
+
+  return {
+    text: source.slice(trimmedStart, trimmedEnd),
+    start: trimmedStart,
+    end: trimmedEnd,
+  };
+}
+
+function contractsFromArrayExpression(expression: string): Set<string> {
+  const withoutBrackets = expression.replace(/^\[/, "").replace(/\]$/, "");
+
+  return new Set(
+    Array.from(
+      withoutBrackets.matchAll(/\b[A-Za-z_$][\w$]*\b/g),
+      ([name]) => name,
+    ),
+  );
+}
+
+function appendToArrayExpression(expression: string, names: string[]): string {
+  const closingBracket = /\]\s*$/.exec(expression);
+  if (!closingBracket) return expression;
+
+  const beforeClosingBracket = expression.slice(0, closingBracket.index);
+  const closingBracketText = expression.slice(closingBracket.index);
+  const inner = beforeClosingBracket.replace(/^\[/, "");
+  if (!inner.trim()) return `[${names.join(", ")}]`;
+
+  if (!expression.includes("\n")) {
+    const separator = /,\s*$/.test(inner) ? " " : ", ";
+    return `${beforeClosingBracket}${separator}${names.join(", ")}${closingBracketText}`;
+  }
+
+  const itemIndent =
+    inner
+      .split("\n")
+      .find((line) => line.trim())
+      ?.match(/^[\t ]*/)?.[0] ?? "\t";
+  const closingIndent = inner.match(/\n([\t ]*)$/)?.[1] ?? "";
+  const trimmedBeforeClosingBracket = beforeClosingBracket.replace(/\s*$/, "");
+  const appendedNames = names.join(`,\n${itemIndent}`);
+
+  if (/,\s*$/.test(inner)) {
+    return `${trimmedBeforeClosingBracket}\n${itemIndent}${appendedNames},\n${closingIndent}${closingBracketText}`;
+  }
+
+  return `${trimmedBeforeClosingBracket},\n${itemIndent}${appendedNames}${closingBracketText}`;
+}
+
+function hasImportedIdentifier(source: string, identifier: string): boolean {
+  const importRegex = /import\s+\{([^}]+)\}\s+from\s+["'][^"']+["']/g;
+
+  for (const match of source.matchAll(importRegex)) {
+    for (const member of match[1].split(",")) {
+      const parsed = parseImportMember(member);
+      if (parsed?.localName === identifier) return true;
+    }
+  }
+
+  return false;
+}
+
+async function readContractLists(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<Map<string, ContractList>> {
+  const lists = new Map<string, ContractList>();
+  const contractFiles = contractListSourceFiles(files, config);
+
+  for (const file of contractFiles) {
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    const imports = parseNamedImports(source, config, file);
+    for (const list of parseContractLists(source, file, imports)) {
+      lists.set(contractListKey(list.file, list.name), list);
+    }
+  }
+
+  return lists;
+}
+
+function contractSourceFiles(
+  files: string[],
+  config: ResolvedBeignetConfig,
+): string[] {
+  const contractsPath = directoryPath(config.paths.contracts);
+  if (usesFeatureOwnedContracts(config)) {
+    return files.filter(
+      (file) =>
+        new RegExp(
+          `^${escapeRegExp(contractsPath)}/[^/]+/contracts\\.ts$`,
+        ).test(file) && !file.endsWith(".test.ts"),
+    );
+  }
+
+  return files.filter(
+    (file) =>
+      file.startsWith(`${contractsPath}/`) &&
+      file.endsWith(".ts") &&
+      !file.endsWith(".test.ts"),
+  );
+}
+
+function contractListSourceFiles(
+  files: string[],
+  config: ResolvedBeignetConfig,
+): string[] {
+  const contractsPath = directoryPath(config.paths.contracts);
+  if (usesFeatureOwnedContracts(config)) {
+    return files.filter((file) => {
+      if (!file.endsWith(".ts") || file.endsWith(".test.ts")) return false;
+      if (file === `${contractsPath}/index.ts`) return true;
+      if (file === `${contractsPath}/contracts.ts`) return true;
+      return new RegExp(
+        `^${escapeRegExp(contractsPath)}/[^/]+/contracts\\.ts$`,
+      ).test(file);
+    });
+  }
+
+  return files.filter(
+    (file) =>
+      (file === `${contractsPath}.ts` ||
+        file.startsWith(`${contractsPath}/`)) &&
+      file.endsWith(".ts") &&
+      !file.endsWith(".test.ts"),
+  );
+}
+
+function parseContractLists(
+  source: string,
+  file: string,
+  imports: ReturnType<typeof parseNamedImports>,
+): ContractList[] {
+  const lists: ContractList[] = [];
+  const exportRegex =
+    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=\s*\[([\s\S]*?)\]\s*;?/g;
+
+  for (const match of source.matchAll(exportRegex)) {
+    const items: ContractListItem[] = [];
+    for (const item of match[2].split(",")) {
+      const trimmed = item.trim();
+      if (!trimmed) continue;
+      const spreadMatch = /^\.\.\.([A-Za-z_$][\w$]*)$/.exec(trimmed);
+      if (spreadMatch) {
+        const imported = imports.get(spreadMatch[1]);
+        items.push({
+          kind: "list",
+          name: imported?.importedName ?? spreadMatch[1],
+          file: imported?.contractFile ?? file,
+        });
+        continue;
+      }
+
+      const contractMatch = /^([A-Za-z_$][\w$]*)$/.exec(trimmed);
+      if (contractMatch) {
+        const imported = imports.get(contractMatch[1]);
+        items.push({
+          kind: "contract",
+          name: imported?.importedName ?? contractMatch[1],
+        });
+      }
+    }
+
+    lists.push({ name: match[1], file, items });
+  }
+
+  return lists;
+}
+
+function resolveContractList(
+  lists: Map<string, ContractList>,
+  file: string,
+  name: string,
+  seen = new Set<string>(),
+): Set<string> | undefined {
+  const key = contractListKey(file, name);
+  if (seen.has(key)) return new Set();
+  const list =
+    lists.get(key) ??
+    lists.get(contractListKey(file.replace(/\.ts$/, "/index.ts"), name));
+  if (!list) return undefined;
+
+  seen.add(key);
+  const contracts = new Set<string>();
+  for (const item of list.items) {
+    if (item.kind === "contract") {
+      contracts.add(item.name);
+      continue;
+    }
+
+    const nested = resolveContractList(
+      lists,
+      item.file ?? file,
+      item.name,
+      seen,
+    );
+    if (!nested) continue;
+    for (const contract of nested) contracts.add(contract);
+  }
+
+  return contracts;
+}
+
+function contractListKey(file: string, name: string): string {
+  return `${file}:${name}`;
+}
+
+async function inspectResourceSlices(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  strict: boolean,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const resources = await collectResourceNames(targetDir, files, config);
+  const diagnostics: InspectDiagnostic[] = [];
+
+  for (const resource of resources) {
+    const singular = singularize(resource);
+    const contractFile = resourceContractFile(resource, config);
+    const useCaseDir = resourceUseCaseDir(resource, config);
+    const portFile = resourcePortFile(resource, singular, config);
+    const infrastructureDir = `${directoryPath(
+      path.dirname(config.paths.infrastructurePorts),
+    )}/${resource}/`;
+    const routeFile = path.join(config.paths.routes, resource, "route.ts");
+    const catchAllRouteFile = path.join(
+      config.paths.routes,
+      "[[...path]]",
+      "route.ts",
+    );
+    const testFile = resourceTestFile(resource, config);
+
+    if (!hasRequirement(files, contractFile)) {
+      diagnostics.push(
+        resourceDiagnostic(
+          "CK_RESOURCE_CONTRACT_MISSING",
+          resource,
+          contractFile,
+        ),
+      );
+    }
+    if (!hasRequirement(files, useCaseDir)) {
+      diagnostics.push(
+        resourceDiagnostic(
+          "CK_RESOURCE_USE_CASES_MISSING",
+          resource,
+          useCaseDir,
+        ),
+      );
+    }
+    if (!hasRequirement(files, portFile)) {
+      diagnostics.push(
+        resourceDiagnostic("CK_RESOURCE_PORT_MISSING", resource, portFile),
+      );
+    }
+    if (!hasRequirement(files, infrastructureDir)) {
+      diagnostics.push(
+        resourceDiagnostic(
+          "CK_RESOURCE_INFRASTRUCTURE_MISSING",
+          resource,
+          infrastructureDir,
+        ),
+      );
+    }
+    if (
+      !hasRequirement(files, routeFile) &&
+      !hasRequirement(files, catchAllRouteFile)
+    ) {
+      diagnostics.push(
+        resourceDiagnostic("CK_RESOURCE_ROUTE_MISSING", resource, routeFile),
+      );
+    }
+    if (strict && !hasRequirement(files, testFile)) {
+      diagnostics.push({
+        ...resourceDiagnostic("CK_RESOURCE_TEST_MISSING", resource, testFile),
+        severity: "warning",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+async function collectResourceNames(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<string[]> {
+  const resources = new Set<string>();
+  const portsPath = directoryPath(path.dirname(config.paths.ports));
+  const featuresPath = directoryPath(config.paths.features);
+  const infrastructurePath = directoryPath(
+    path.dirname(config.paths.infrastructurePorts),
+  );
+
+  for (const file of files) {
+    const portMatch = new RegExp(
+      `^${escapeRegExp(portsPath)}/([^/]+)-repository\\.ts$`,
+    ).exec(file);
+    if (portMatch) {
+      resources.add(pluralize(portMatch[1]));
+    }
+
+    const featurePortMatch = new RegExp(
+      `^${escapeRegExp(featuresPath)}/([^/]+)/ports\\.ts$`,
+    ).exec(file);
+    if (
+      featurePortMatch &&
+      (await isGeneratedResourcePort(targetDir, file, featurePortMatch[1]))
+    ) {
+      resources.add(featurePortMatch[1]);
+    }
+
+    const infrastructureMatch = new RegExp(
+      `^${escapeRegExp(infrastructurePath)}/([^/]+)/.*-repository\\.ts$`,
+    ).exec(file);
+    if (
+      infrastructureMatch &&
+      (await isGeneratedInfrastructureRepository(
+        targetDir,
+        file,
+        infrastructureMatch[1],
+      ))
+    ) {
+      resources.add(infrastructureMatch[1]);
+    }
+  }
+
+  return [...resources].sort();
+}
+
+async function isGeneratedResourcePort(
+  targetDir: string,
+  file: string,
+  resource: string,
+): Promise<boolean> {
+  let source: string;
+  try {
+    source = await readFile(path.join(targetDir, file), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+
+  const singular = singularize(resource);
+  const singularPascal = pascalCase(singular);
+  const pluralPascal = pascalCase(resource);
+
+  return (
+    source.includes(`Create${singularPascal}Input`) &&
+    source.includes(`List${pluralPascal}Input`) &&
+    source.includes(`List${pluralPascal}Result`) &&
+    source.includes(`interface ${singularPascal}Repository`) &&
+    source.includes(`create(input: Create${singularPascal}Input)`)
+  );
+}
+
+async function isGeneratedInfrastructureRepository(
+  targetDir: string,
+  file: string,
+  resource: string,
+): Promise<boolean> {
+  let source: string;
+  try {
+    source = await readFile(path.join(targetDir, file), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+
+  const singularPascal = pascalCase(singularize(resource));
+
+  return source.includes(`createInMemory${singularPascal}Repository`);
+}
+
+function usesFeatureOwnedContracts(config: ResolvedBeignetConfig): boolean {
+  return (
+    directoryPath(config.paths.contracts) ===
+    directoryPath(config.paths.features)
+  );
+}
+
+function usesFeatureOwnedUseCases(config: ResolvedBeignetConfig): boolean {
+  return (
+    directoryPath(config.paths.useCases) ===
+    directoryPath(config.paths.features)
+  );
+}
+
+function usesFeatureOwnedTests(config: ResolvedBeignetConfig): boolean {
+  return (
+    usesFeatureOwnedUseCases(config) &&
+    directoryPath(config.paths.tests) === "tests"
+  );
+}
+
+function resourceContractFile(
+  resource: string,
+  config: ResolvedBeignetConfig,
+): string {
+  if (usesFeatureOwnedContracts(config)) {
+    return path.join(config.paths.features, resource, "contracts.ts");
+  }
+
+  return path.join(config.paths.contracts, `${resource}.ts`);
+}
+
+function resourceUseCaseDir(
+  resource: string,
+  config: ResolvedBeignetConfig,
+): string {
+  if (usesFeatureOwnedUseCases(config)) {
+    return `${directoryPath(config.paths.features)}/${resource}/use-cases/`;
+  }
+
+  return `${directoryPath(config.paths.useCases)}/${resource}/`;
+}
+
+function resourcePortFile(
+  resource: string,
+  singular: string,
+  config: ResolvedBeignetConfig,
+): string {
+  if (usesFeatureOwnedContracts(config)) {
+    return path.join(config.paths.features, resource, "ports.ts");
+  }
+
+  return path.join(
+    path.dirname(config.paths.ports),
+    `${singular}-repository.ts`,
+  );
+}
+
+function resourceTestFile(
+  resource: string,
+  config: ResolvedBeignetConfig,
+): string {
+  if (usesFeatureOwnedTests(config)) {
+    return path.join(
+      config.paths.features,
+      resource,
+      "tests",
+      `${resource}.test.ts`,
+    );
+  }
+
+  return path.join(config.paths.tests, `${resource}.test.ts`);
+}
+
+function resourceDiagnostic(
+  code: string,
+  resource: string,
+  file: string,
+): InspectDiagnostic {
+  return {
+    severity: "error",
+    code,
+    file,
+    message: `${resource} appears to be a generated resource slice, but ${file} is missing. Re-run make resource ${resource}, restore the missing file, or remove the partial resource wiring.`,
+  };
+}
+
+function nextRoutePath(file: string, routeRoot: string): string {
+  const normalizedRouteRoot = directoryPath(routeRoot);
+  const routeSegments = file
+    .slice(normalizedRouteRoot.length + 1)
+    .replace(/\/route\.ts$/, "")
+    .split("/")
+    .filter(Boolean);
+  const apiPath = routeSegments.map(nextSegmentToContractSegment).join("/");
+  return apiPath ? `/api/${apiPath}` : "/api";
+}
+
+function nextSegmentToContractSegment(segment: string): string {
+  const catchAll = /^\[\.\.\.(.+)\]$/.exec(segment);
+  if (catchAll) return `:${catchAll[1]}*`;
+
+  const optionalCatchAll = /^\[\[\.\.\.(.+)\]\]$/.exec(segment);
+  if (optionalCatchAll) return `:${optionalCatchAll[1]}*`;
+
+  const dynamic = /^\[(.+)\]$/.exec(segment);
+  if (dynamic) return `:${dynamic[1]}`;
+
+  return segment;
+}
+
+function methodArticle(_method: HttpMethod): "a" {
+  return "a";
+}
+
+function pascalCase(value: string): string {
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join("");
+}
+
+function singularize(value: string): string {
+  if (value.endsWith("ies") && value.length > 3) {
+    return `${value.slice(0, -3)}y`;
+  }
+  if (value.endsWith("ses") && value.length > 3) {
+    return value.slice(0, -2);
+  }
+  if (value.endsWith("s") && value.length > 1) {
+    return value.slice(0, -1);
+  }
+  return value;
+}
+
+function pluralize(value: string): string {
+  if (value.endsWith("y") && value.length > 1) {
+    return `${value.slice(0, -1)}ies`;
+  }
+  if (value.endsWith("s")) {
+    return `${value}es`;
+  }
+  return `${value}s`;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function compareContracts(
+  left: Pick<InspectedContract, "path" | "method" | "exportName">,
+  right: Pick<InspectedContract, "path" | "method" | "exportName">,
+): number {
+  return (
+    left.path.localeCompare(right.path) ||
+    left.method.localeCompare(right.method) ||
+    left.exportName.localeCompare(right.exportName)
+  );
+}
+
+function contractKey(contract: InspectedContract): string {
+  return `${contract.file}:${contract.exportName}`;
+}
+
+function table(rows: string[][]): string {
+  const widths = rows[0].map((_, columnIndex) =>
+    Math.max(...rows.map((row) => row[columnIndex].length)),
+  );
+
+  return rows
+    .map((row) =>
+      row
+        .map((cell, columnIndex) => cell.padEnd(widths[columnIndex]))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n");
+}