@beignet/cli 0.0.47 → 0.0.49

package/src/inspect.ts

@@ -1,6 +1,16 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { parseProviderPackageMetadata } from "@beignet/core/providers";
+import ts from "typescript";
+import {
+  type ContractFactoryBindings,
+  type ContractFactoryName,
+  contractFactoryBindings,
+  isImportedContractFactoryCall,
+} from "./analysis/contract-factories.js";
+import { canonicalFeatureLayerPath } from "./analysis/layers.js";
+import { analyzePortWiringFiles } from "./analysis/port-wiring.js";
+import { exportedVariableDeclarations } from "./analysis/source-index.js";
 import { createPainter } from "./ansi.js";
 import type { DatabaseSchemaDialect, DatabaseSchemaTable } from "./choices.js";
 import {
@@ -43,6 +53,7 @@ import {
 import {
   detectedProviderVariants,
   diagnosticPackageJsonFile,
+  formatProviderEnvAlternatives,
   formatProviderMetadataIssues,
   installedPackageNames,
   providerDoctorRulesForInstalledPackages,
@@ -65,7 +76,8 @@ import {
   identifiersFromArrayExpression,
   insertAfterImports,
   matchingDelimiterIndex,
-  outboxRegistryValueInfo,
+  outboxRegistryEntryState,
+  outboxRegistryIdentifiers,
 } from "./registry-edits.js";
 import {
   currentGeneratedPackageScripts,
@@ -220,6 +232,16 @@ type FeatureRouteGroup = {
   }>;
 };
 
+type ReadContractsResult = {
+  contracts: InspectedContract[];
+  queryTransportDiagnostics: InspectDiagnostic[];
+};
+
+type ParsedContract = {
+  contract: InspectedContract;
+  queryTransportMissing: boolean;
+};
+
 export async function inspectApp(
   options: InspectAppOptions = {},
 ): Promise<InspectAppResult> {
@@ -231,7 +253,8 @@ export async function inspectApp(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir, files);
   const convention = inspectConvention(files, config);
-  const contracts = await readContracts(targetDir, files, config);
+  const inspectedContracts = await readContracts(targetDir, files, config);
+  const { contracts } = inspectedContracts;
   const matchedRoutes = await inspectRouteSurface(
     targetDir,
     files,
@@ -246,6 +269,7 @@ export async function inspectApp(
     contracts,
     matchedRoutes,
     Boolean(options.strict),
+    inspectedContracts.queryTransportDiagnostics,
   );
 
   return {
@@ -329,7 +353,7 @@ async function buildDoctorFixPlan(
     ? resolveConfig(options.config)
     : await loadBeignetConfig(targetDir, files);
   const convention = inspectConvention(files, config);
-  const contracts = await readContracts(targetDir, files, config);
+  const { contracts } = await readContracts(targetDir, files, config);
   const matchedRoutes = await inspectRouteSurface(
     targetDir,
     files,
@@ -710,7 +734,6 @@ export const productionHardeningDiagnosticCodes = new Set([
   "BEIGNET_BILLING_IDEMPOTENCY_PORT_MISSING",
   "BEIGNET_CORS_CREDENTIALS_WILDCARD",
   "BEIGNET_CRON_SECRET_MISSING",
-  "BEIGNET_DEVTOOLS_ROUTE_EXPOSED",
   "BEIGNET_ENTITLEMENTS_PORT_MISSING",
   "BEIGNET_PAYMENTS_STRIPE_MEMORY_PROVIDER",
   "BEIGNET_PAYMENTS_WEBHOOK_ROUTE_MISSING",
@@ -829,16 +852,32 @@ async function readContracts(
   targetDir: string,
   files: string[],
   config: ResolvedBeignetConfig,
-): Promise<InspectedContract[]> {
+): Promise<ReadContractsResult> {
   const contracts: InspectedContract[] = [];
+  const queryTransportDiagnostics: InspectDiagnostic[] = [];
   const contractFiles = contractSourceFiles(files, config);
 
   for (const file of contractFiles) {
     const source = await readFile(path.join(targetDir, file), "utf8");
-    contracts.push(...parseContracts(source, file));
+    for (const parsed of parseContracts(source, file)) {
+      contracts.push(parsed.contract);
+      if (!parsed.queryTransportMissing) continue;
+
+      queryTransportDiagnostics.push({
+        severity: "error",
+        code: "BEIGNET_QUERY_TRANSPORT_MISSING",
+        file,
+        contract: parsed.contract.exportName,
+        subject: { file, exportName: parsed.contract.exportName },
+        message: `${parsed.contract.exportName} declares a query schema without an explicit query transport. Pass defineQueryTransport(...) as the second .query(...) argument so the client, server, and OpenAPI document share one wire format.`,
+      });
+    }
   }
 
-  return contracts.sort(compareContracts);
+  return {
+    contracts: contracts.sort(compareContracts),
+    queryTransportDiagnostics,
+  };
 }
 
 function inspectConvention(
@@ -900,68 +939,126 @@ function hasRequirement(files: string[], requirement: string): boolean {
   return files.includes(requirement);
 }
 
-function parseContracts(source: string, file: string): InspectedContract[] {
-  const contracts: InspectedContract[] = [];
-  const groupPrefixes = parseContractGroupPrefixes(source);
-  const groupErrorRefs = parseContractGroupErrorRefs(source);
-  const exportRegex =
-    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=([\s\S]*?)(?=\nexport const\s+[A-Za-z_$][\w$]*\s*=|$)/g;
+function parseContracts(source: string, file: string): ParsedContract[] {
+  const contracts: ParsedContract[] = [];
+  const sourceFile = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const assignments = variableAssignments(sourceFile);
+  const assignmentsByName = new Map(
+    assignments.map((assignment) => [assignment.name, assignment.expression]),
+  );
+  const factoryBindings = contractFactoryBindings(sourceFile);
 
-  for (const exportMatch of source.matchAll(exportRegex)) {
-    const block = exportMatch[2];
-    const methodMatch =
-      /([A-Za-z_$][\w$]*)(?:\s*\.\s*[A-Za-z_$][\w$]*\([^)]*\))*\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["'](?:\s*,\s*["'][^"']+["'])?\s*\)/.exec(
-        block,
-      );
-    if (methodMatch) {
-      const receiver = methodMatch[1];
-      const pathPrefix = groupPrefixes.get(receiver) ?? "";
-      const routePath = joinContractPaths(pathPrefix, methodMatch[3]);
+  for (const { exportName, declaration } of exportedVariableDeclarations(
+    sourceFile,
+  )) {
+    if (!declaration.initializer) continue;
+    const chain = resolveContractCallChain(
+      declaration.initializer,
+      assignmentsByName,
+    );
+    if (!chain) continue;
 
+    const directContract = parseDirectContract(chain, factoryBindings);
+    if (directContract) {
       contracts.push({
-        exportName: exportMatch[1],
-        file,
-        metadata: parseContractMetadata(
-          block,
-          groupErrorRefs.get(receiver) ?? [],
-        ),
-        method: methodMatch[2].toUpperCase() as HttpMethod,
-        path: routePath,
+        contract: {
+          exportName,
+          file,
+          metadata: parseContractMetadata(
+            applyContractMetadataCalls(
+              emptyContractMetadataState(),
+              chain.calls,
+            ),
+          ),
+          method: directContract.method,
+          path: normalizeContractPath(directContract.path),
+        },
+        queryTransportMissing: contractQueryHasTransport(chain) === false,
       });
       continue;
     }
 
-    const directContract = parseDirectContract(block);
-    if (directContract) {
-      contracts.push({
-        exportName: exportMatch[1],
+    const methodIndex = chain.calls.findIndex((call) =>
+      isHttpMethod(call.name.toUpperCase()),
+    );
+    if (methodIndex === -1) continue;
+    const methodCall = chain.calls[methodIndex];
+    const routePath = staticString(methodCall.arguments[0]);
+    if (!routePath) continue;
+
+    const hasGroupFactory = contractFactoryCall(
+      chain,
+      "defineContractGroup",
+      factoryBindings,
+    );
+    if (!hasGroupFactory) continue;
+
+    const pathPrefix = applyStaticPrefixes(
+      "",
+      chain.calls.slice(0, methodIndex),
+    );
+    if (pathPrefix === undefined) continue;
+
+    contracts.push({
+      contract: {
+        exportName,
         file,
-        metadata: parseContractMetadata(block),
-        method: directContract.method,
-        path: normalizeContractPath(directContract.path),
-      });
-    }
+        metadata: parseContractMetadata(
+          applyContractMetadataCalls(emptyContractMetadataState(), chain.calls),
+        ),
+        method: methodCall.name.toUpperCase() as HttpMethod,
+        path: joinContractPaths(pathPrefix, routePath),
+      },
+      queryTransportMissing: contractQueryHasTransport(chain) === false,
+    });
   }
 
   return contracts;
 }
 
+function unwrapContractExpression(expression: ts.Expression): ts.Expression {
+  let current = expression;
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
+    ts.isNonNullExpression(current) ||
+    ts.isSatisfiesExpression(current)
+  ) {
+    current = current.expression;
+  }
+  return current;
+}
+
+type ContractMetadataState = {
+  authRequired?: boolean;
+  authorizationAbility?: string;
+  authorizationAuditRequired?: boolean;
+  audit?: boolean;
+  auditRequired?: boolean;
+  catalogErrors: InspectedCatalogErrorRef[];
+};
+
+function emptyContractMetadataState(): ContractMetadataState {
+  return { catalogErrors: [] };
+}
+
 function parseContractMetadata(
-  block: string,
-  inheritedCatalogErrors: InspectedCatalogErrorRef[] = [],
+  state: ContractMetadataState,
 ): InspectedContractMetadata | undefined {
-  const authRequired = /\bauth\s*:\s*["']required["']/.test(block);
-  const authorizationAbility =
-    /\bauthorization\s*:\s*\{[\s\S]*?\bability\s*:\s*["']([^"']+)["']/.exec(
-      block,
-    )?.[1];
+  const authRequired = state.authRequired === true;
+  const authorizationAbility = state.authorizationAbility;
   const auditRequired =
-    /\baudit\s*:\s*["']required["']/.test(block) ||
-    /\bauditRequired\s*:\s*true\b/.test(block);
-  const catalogErrors = dedupeCatalogErrorRefs([
-    ...inheritedCatalogErrors,
-    ...parseCatalogErrorRefs(block),
-  ]);
+    state.audit === true ||
+    state.auditRequired === true ||
+    state.authorizationAuditRequired === true;
+  const catalogErrors = state.catalogErrors;
 
   if (
     !authRequired &&
@@ -980,21 +1077,129 @@ function parseContractMetadata(
   };
 }
 
-function parseDirectContract(
-  block: string,
-): { method: HttpMethod; path: string } | undefined {
-  const configMatch = /defineContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
-  if (!configMatch) return undefined;
+function applyContractMetadataCalls(
+  initialState: ContractMetadataState,
+  calls: ContractCall[],
+): ContractMetadataState {
+  const state: ContractMetadataState = {
+    ...initialState,
+    catalogErrors: [...initialState.catalogErrors],
+  };
 
-  const configSource = configMatch[1];
-  const methodMatch = /method\s*:\s*["']([^"']+)["']/.exec(configSource);
-  const pathMatch = /path\s*:\s*["']([^"']+)["']/.exec(configSource);
-  if (!methodMatch || !pathMatch) return undefined;
+  for (const call of calls) {
+    if (call.name === "meta") {
+      applyContractMetaObject(state, objectLiteral(call.arguments[0]));
+      continue;
+    }
+    if (call.name === "errors") {
+      state.catalogErrors = applyCatalogErrorCall(
+        state.catalogErrors,
+        call.arguments[0],
+      );
+    }
+  }
 
-  const method = methodMatch[1].toUpperCase();
-  if (!isHttpMethod(method)) return undefined;
+  return state;
+}
 
-  return { method, path: pathMatch[1] };
+function applyContractMetaObject(
+  state: ContractMetadataState,
+  metadata: ts.ObjectLiteralExpression | undefined,
+): void {
+  if (!metadata) {
+    state.authRequired = undefined;
+    state.authorizationAbility = undefined;
+    state.authorizationAuditRequired = undefined;
+    state.audit = undefined;
+    state.auditRequired = undefined;
+    return;
+  }
+
+  const auth = objectPropertyResult(metadata, "auth");
+  if (auth.kind !== "absent") {
+    state.authRequired =
+      auth.kind === "value" ? staticRequiredValue(auth.value) : undefined;
+  }
+
+  const authorization = objectPropertyResult(metadata, "authorization");
+  if (authorization.kind !== "absent") {
+    const value =
+      authorization.kind === "value"
+        ? objectLiteral(authorization.value)
+        : undefined;
+    if (!value) {
+      state.authorizationAbility = undefined;
+      state.authorizationAuditRequired = undefined;
+    } else {
+      const ability = objectPropertyResult(value, "ability");
+      state.authorizationAbility =
+        ability.kind === "value" ? staticString(ability.value) : undefined;
+      state.authorizationAuditRequired = objectRequiresAudit(value);
+    }
+  }
+
+  const audit = objectPropertyResult(metadata, "audit");
+  const auditRequired = objectPropertyResult(metadata, "auditRequired");
+  if (audit.kind !== "absent") {
+    state.audit =
+      audit.kind === "value" ? staticRequiredValue(audit.value) : undefined;
+  }
+  if (auditRequired.kind !== "absent") {
+    state.auditRequired =
+      auditRequired.kind === "value"
+        ? staticBoolean(auditRequired.value)
+        : undefined;
+  }
+}
+
+function objectRequiresAudit(
+  metadata: ts.ObjectLiteralExpression,
+): boolean | undefined {
+  const audit = objectPropertyResult(metadata, "audit");
+  const auditRequired = objectPropertyResult(metadata, "auditRequired");
+  if (audit.kind === "unknown" || auditRequired.kind === "unknown") {
+    return undefined;
+  }
+  const auditValue =
+    audit.kind === "value" ? staticRequiredValue(audit.value) : false;
+  const auditRequiredValue =
+    auditRequired.kind === "value" ? staticBoolean(auditRequired.value) : false;
+  if (auditValue === undefined || auditRequiredValue === undefined) {
+    return undefined;
+  }
+  return auditValue || auditRequiredValue;
+}
+
+function staticRequiredValue(expression: ts.Expression): boolean | undefined {
+  const value = staticString(expression);
+  return value === undefined ? undefined : value === "required";
+}
+
+function staticBoolean(expression: ts.Expression): boolean | undefined {
+  if (expression.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (expression.kind === ts.SyntaxKind.FalseKeyword) return false;
+  return undefined;
+}
+
+function parseDirectContract(
+  chain: ContractCallChain,
+  factoryBindings: ContractFactoryBindings,
+): { method: HttpMethod; path: string } | undefined {
+  const factoryCall = contractFactoryCall(
+    chain,
+    "defineContract",
+    factoryBindings,
+  );
+  if (!factoryCall) return undefined;
+  const options = objectLiteral(factoryCall.arguments[0]);
+  if (!options) return undefined;
+  const methodValue = staticString(objectProperty(options, "method"));
+  const contractPath = staticString(objectProperty(options, "path"));
+  if (!methodValue || !contractPath) return undefined;
+
+  const method = methodValue.toUpperCase();
+  if (!isHttpMethod(method)) return undefined;
+  return { method, path: contractPath };
 }
 
 function isHttpMethod(method: string): method is HttpMethod {
@@ -1003,118 +1208,245 @@ function isHttpMethod(method: string): method is HttpMethod {
   );
 }
 
-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>();
+type VariableAssignment = {
+  name: string;
+  expression: ts.Expression;
+};
 
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const assignment of assignments) {
-      if (prefixes.has(assignment.name)) continue;
+type ContractCall = {
+  name: string;
+  arguments: readonly ts.Expression[];
+  node: ts.CallExpression;
+};
 
-      const basePrefix = baseGroupPrefix(assignment.expression, prefixes);
-      if (basePrefix === undefined) continue;
+type ContractCallChain = {
+  baseIdentifier?: string;
+  rootCall?: ContractCall;
+  calls: ContractCall[];
+};
 
-      const prefix = prefixCalls(assignment.expression).reduce(
-        (current, next) => joinContractPaths(current, next),
-        basePrefix,
-      );
-      prefixes.set(assignment.name, prefix);
-      changed = true;
+function variableAssignments(sourceFile: ts.SourceFile): VariableAssignment[] {
+  return sourceFile.statements
+    .filter(ts.isVariableStatement)
+    .flatMap((statement) =>
+      [...statement.declarationList.declarations]
+        .filter(
+          (
+            declaration,
+          ): declaration is ts.VariableDeclaration & {
+            name: ts.Identifier;
+            initializer: ts.Expression;
+          } =>
+            ts.isIdentifier(declaration.name) &&
+            declaration.initializer !== undefined,
+        )
+        .map((declaration) => ({
+          name: declaration.name.text,
+          expression: declaration.initializer,
+        })),
+    );
+}
+
+function resolveContractCallChain(
+  expression: ts.Expression,
+  assignments: ReadonlyMap<string, ts.Expression>,
+  resolving = new Set<string>(),
+): ContractCallChain | undefined {
+  const chain = contractCallChain(expression);
+  if (!chain || chain.rootCall || !chain.baseIdentifier) return chain;
+
+  const baseExpression = assignments.get(chain.baseIdentifier);
+  if (!baseExpression || resolving.has(chain.baseIdentifier)) return chain;
+
+  const nextResolving = new Set(resolving);
+  nextResolving.add(chain.baseIdentifier);
+  const baseChain = resolveContractCallChain(
+    baseExpression,
+    assignments,
+    nextResolving,
+  );
+  if (!baseChain) return chain;
+
+  return {
+    ...baseChain,
+    calls: [...baseChain.calls, ...chain.calls],
+  };
+}
+
+function contractCallChain(
+  rawExpression: ts.Expression,
+): ContractCallChain | undefined {
+  const calls: ContractCall[] = [];
+  let expression = rawExpression;
+
+  while (true) {
+    expression = unwrapContractExpression(expression);
+    if (ts.isPropertyAccessExpression(expression)) {
+      expression = expression.expression;
+      continue;
+    }
+    if (ts.isCallExpression(expression)) {
+      const callee = unwrapContractExpression(expression.expression);
+      if (ts.isPropertyAccessExpression(callee)) {
+        calls.unshift({
+          name: callee.name.text,
+          arguments: [...expression.arguments],
+          node: expression,
+        });
+        expression = callee.expression;
+        continue;
+      }
+      if (ts.isIdentifier(callee)) {
+        return {
+          baseIdentifier: callee.text,
+          rootCall: {
+            name: callee.text,
+            arguments: [...expression.arguments],
+            node: expression,
+          },
+          calls,
+        };
+      }
+      return undefined;
     }
+    if (ts.isIdentifier(expression)) {
+      return { baseIdentifier: expression.text, calls };
+    }
+    return undefined;
   }
+}
 
-  return prefixes;
+function contractFactoryCall(
+  chain: ContractCallChain,
+  name: ContractFactoryName,
+  factoryBindings: ContractFactoryBindings,
+): ContractCall | undefined {
+  const calls = chain.rootCall ? [chain.rootCall] : chain.calls;
+  return calls.find((call) =>
+    isImportedContractFactoryCall(call.node, name, factoryBindings),
+  );
 }
 
-function parseContractGroupErrorRefs(
-  source: string,
-): Map<string, InspectedCatalogErrorRef[]> {
-  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 groupErrors = new Map<string, InspectedCatalogErrorRef[]>();
-
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const assignment of assignments) {
-      if (groupErrors.has(assignment.name)) continue;
-
-      const baseErrors = baseGroupErrors(assignment.expression, groupErrors);
-      if (baseErrors === undefined) continue;
-
-      groupErrors.set(
-        assignment.name,
-        dedupeCatalogErrorRefs([
-          ...baseErrors,
-          ...parseCatalogErrorRefs(assignment.expression),
-        ]),
-      );
-      changed = true;
-    }
+function applyStaticPrefixes(
+  initialPrefix: string,
+  calls: ContractCall[],
+): string | undefined {
+  let prefix = initialPrefix;
+  for (const call of calls) {
+    if (call.name !== "prefix") continue;
+    const next = staticString(call.arguments[0]);
+    if (next === undefined) return undefined;
+    prefix = joinContractPaths(prefix, next);
   }
+  return prefix;
+}
 
-  return groupErrors;
+function contractQueryHasTransport(
+  chain: ContractCallChain,
+): boolean | undefined {
+  const queryCall = chain.calls.find((call) => call.name === "query");
+  return queryCall ? queryCall.arguments.length >= 2 : undefined;
 }
 
-function baseGroupErrors(
-  expression: string,
-  groupErrors: Map<string, InspectedCatalogErrorRef[]>,
-): InspectedCatalogErrorRef[] | undefined {
-  if (expression.includes("defineContractGroup(")) return [];
+function applyCatalogErrorCall(
+  current: InspectedCatalogErrorRef[],
+  expression: ts.Expression | undefined,
+): InspectedCatalogErrorRef[] {
+  const errors = objectLiteral(expression);
+  if (!errors) return [];
+  let merged = [...current];
 
-  const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
-  if (!baseMatch) return undefined;
+  for (const property of errors.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      merged = [];
+      continue;
+    }
+    const key = staticPropertyName(property.name);
+    if (!key) {
+      merged = [];
+      continue;
+    }
 
-  return groupErrors.get(baseMatch[1]);
-}
+    merged = merged.filter((ref) => ref.key !== key);
+    if (!ts.isPropertyAssignment(property)) continue;
+    const value = unwrapContractExpression(property.initializer);
+    if (
+      !ts.isPropertyAccessExpression(value) ||
+      !ts.isIdentifier(value.expression)
+    ) {
+      continue;
+    }
+    merged.push({
+      key,
+      catalog: value.expression.text,
+      catalogKey: value.name.text,
+    });
+  }
 
-function baseGroupPrefix(
-  expression: string,
-  prefixes: Map<string, string>,
-): string | undefined {
-  if (expression.includes("defineContractGroup(")) return "";
+  return merged;
+}
 
-  const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
-  if (!baseMatch) return undefined;
+function objectLiteral(
+  expression: ts.Expression | undefined,
+): ts.ObjectLiteralExpression | undefined {
+  if (!expression) return undefined;
+  const unwrapped = unwrapContractExpression(expression);
+  return ts.isObjectLiteralExpression(unwrapped) ? unwrapped : undefined;
+}
 
-  return prefixes.get(baseMatch[1]);
+function objectProperty(
+  object: ts.ObjectLiteralExpression,
+  name: string,
+): ts.Expression | undefined {
+  const result = objectPropertyResult(object, name);
+  return result.kind === "value" ? result.value : undefined;
 }
 
-function prefixCalls(expression: string): string[] {
-  return [...expression.matchAll(/\.prefix\(\s*["']([^"']+)["']\s*\)/g)].map(
-    (match) => match[1],
-  );
+type ObjectPropertyResult =
+  | { kind: "absent" }
+  | { kind: "unknown" }
+  | { kind: "value"; value: ts.Expression };
+
+function objectPropertyResult(
+  object: ts.ObjectLiteralExpression,
+  name: string,
+): ObjectPropertyResult {
+  for (const property of [...object.properties].reverse()) {
+    if (ts.isSpreadAssignment(property)) return { kind: "unknown" };
+    const propertyName = staticPropertyName(property.name);
+    if (propertyName === undefined) return { kind: "unknown" };
+    if (propertyName !== name) continue;
+    if (ts.isPropertyAssignment(property)) {
+      return {
+        kind: "value",
+        value: unwrapContractExpression(property.initializer),
+      };
+    }
+    return { kind: "unknown" };
+  }
+  return { kind: "absent" };
 }
 
-function parseCatalogErrorRefs(source: string): InspectedCatalogErrorRef[] {
-  return dedupeCatalogErrorRefs(
-    objectArgumentBodies(source, /\.errors\s*\(/g).flatMap((body) =>
-      [...body.matchAll(errorCatalogRefRegex)].map((match) => ({
-        key: match[1],
-        catalog: match[2],
-        catalogKey: match[3],
-      })),
-    ),
-  );
+function staticPropertyName(name: ts.PropertyName): string | undefined {
+  if (
+    ts.isIdentifier(name) ||
+    ts.isStringLiteral(name) ||
+    ts.isNumericLiteral(name)
+  ) {
+    return name.text;
+  }
+  return undefined;
 }
 
-const errorCatalogRefRegex =
-  /(?:^|[,{])\s*([A-Za-z_$][\w$]*)\s*:\s*([A-Za-z_$][\w$]*)\s*\.\s*([A-Za-z_$][\w$]*)/g;
+function staticString(
+  expression: ts.Expression | undefined,
+): string | undefined {
+  if (!expression) return undefined;
+  const value = unwrapContractExpression(expression);
+  return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+    ? value.text
+    : undefined;
+}
 
 function parseErrorCatalogKeys(source: string): Set<string> {
   const keys = new Set<string>();
@@ -1207,23 +1539,6 @@ function topLevelObjectKeys(body: string): string[] {
   return keys;
 }
 
-function dedupeCatalogErrorRefs(
-  refs: InspectedCatalogErrorRef[],
-): InspectedCatalogErrorRef[] {
-  const seen = new Set<string>();
-  const deduped: InspectedCatalogErrorRef[] = [];
-
-  for (const ref of refs) {
-    const key = `${ref.key}:${ref.catalog}:${ref.catalogKey}`;
-    if (seen.has(key)) continue;
-
-    seen.add(key);
-    deduped.push(ref);
-  }
-
-  return deduped;
-}
-
 function joinContractPaths(prefix: string, routePath: string): string {
   if (!prefix) return normalizeContractPath(routePath);
   const segments = [
@@ -1666,8 +1981,9 @@ async function inspectDiagnostics(
   contracts: InspectedContract[],
   matchedRoutes: MatchedRoutesResult,
   strict: boolean,
+  queryTransportDiagnostics: InspectDiagnostic[],
 ): Promise<InspectDiagnostic[]> {
-  const diagnostics: InspectDiagnostic[] = [];
+  const diagnostics: InspectDiagnostic[] = [...queryTransportDiagnostics];
   const frameworkLayout =
     config.framework === "next" ? convention.nextLayout : convention.webLayout;
   const missingFrameworkLayout =
@@ -1774,6 +2090,7 @@ async function inspectDiagnostics(
       contracts,
     )),
     ...(await inspectServerlessFootguns(targetDir, files, config, convention)),
+    ...(await inspectOutboxJobDispatcherDrift(targetDir, files, config)),
     ...(await inspectProductionReadiness(targetDir, files, config, convention)),
     ...(await inspectFeatureArtifactDrift(
       targetDir,
@@ -2471,14 +2788,14 @@ async function inspectProductionReadiness(
 
     if (
       containsCallExpression(source, "createDevtoolsRoute") &&
-      /\benabled\s*:\s*true\b/.test(source) &&
-      !/\bauthorize\s*:/.test(source)
+      !/\bauthorize\s*(?::|\()/.test(source) &&
+      !/\ballowUnauthenticatedDevelopmentAccess\s*:\s*true\b/.test(source)
     ) {
       diagnostics.push({
         severity: "warning",
-        code: "BEIGNET_DEVTOOLS_ROUTE_EXPOSED",
+        code: "BEIGNET_DEVTOOLS_ROUTE_POLICY_MISSING",
         file,
-        message: `${file} enables devtools with enabled: true and no authorize callback. Keep devtools disabled in production or add app-owned authorization before exposing diagnostic data.`,
+        message: `${file} creates a devtools route without an access policy, so the route remains hidden. Add app-owned authorize(...), or explicitly set allowUnauthenticatedDevelopmentAccess: true only for a development server bound exclusively to loopback.`,
       });
     }
 
@@ -2619,6 +2936,27 @@ async function inspectProductionReadiness(
         provider.variants,
         providerEntries,
       )) {
+        const envAlternatives = configuredProviderRequiredEnvAlternatives(
+          variant.requiredEnvAlternatives,
+          config,
+        );
+        if (
+          envAlternatives.length > 0 &&
+          !(await providerRequiredEnvAlternativeExists(
+            targetDir,
+            configFiles,
+            envAlternatives,
+            sourceCache,
+          ))
+        ) {
+          diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_PROVIDER_ENV_MISSING",
+            file: "package.json",
+            message: `${provider.packageName} is installed and ${variant.displayName} is registered, but none of its required environment configurations are fully mentioned in app env/config files. Configure ${formatProviderEnvAlternatives(envAlternatives)}, or remove the provider registration.`,
+          });
+        }
+
         for (const envVar of configuredProviderRequiredEnv(
           variant.requiredEnv,
           config,
@@ -2669,6 +3007,27 @@ async function inspectProductionReadiness(
       continue;
     }
 
+    const envAlternatives = configuredProviderRequiredEnvAlternatives(
+      provider.requiredEnvAlternatives ?? [],
+      config,
+    );
+    if (
+      envAlternatives.length > 0 &&
+      !(await providerRequiredEnvAlternativeExists(
+        targetDir,
+        configFiles,
+        envAlternatives,
+        sourceCache,
+      ))
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_PROVIDER_ENV_MISSING",
+        file: "package.json",
+        message: `${provider.packageName} is installed, but none of its required environment configurations are fully mentioned in app env/config files. Configure ${formatProviderEnvAlternatives(envAlternatives)}, or remove the unused provider package.`,
+      });
+    }
+
     for (const envVar of configuredProviderRequiredEnv(
       provider.requiredEnv ?? [],
       config,
@@ -3839,9 +4198,7 @@ async function inspectFeatureArtifactDrift(
   }
 
   for (const file of files) {
-    const match = new RegExp(
-      `^${escapeRegExp(featuresPath)}/([^/]+)/[^/]+\\.test\\.ts$`,
-    ).exec(file);
+    const match = directFeatureTestMatch(file, featuresPath);
     if (!match) continue;
     diagnostics.push({
       severity: "warning",
@@ -3853,23 +4210,27 @@ async function inspectFeatureArtifactDrift(
 
   for (const file of files) {
     if (
-      !file.endsWith(".ts") ||
-      file.endsWith(".test.ts") ||
-      file.endsWith(".d.ts")
+      !/\.(?:ts|tsx|mts|cts)$/.test(file) ||
+      /\.d\.(?:ts|mts|cts)$/.test(file)
     ) {
       continue;
     }
 
-    const misplaced = misplacedFeatureArtifactFolder(file, featuresPath);
+    const misplaced = directFeatureTestMatch(file, featuresPath)
+      ? undefined
+      : misplacedFeatureLayer(file, config);
     if (misplaced) {
       diagnostics.push({
         severity: "warning",
         code: "BEIGNET_FEATURE_ARTIFACT_FOLDER",
         file,
-        message: `${file} uses ${misplaced.actual}, but Beignet expects ${misplaced.expected}. Keep feature-owned workflow artifacts in the canonical feature folders so CLI generators, docs, and architecture lint stay aligned.`,
+        message: `${file} uses ${misplaced.actual}, but Beignet expects ${misplaced.expected}. Keep feature-owned files in the canonical feature folders so CLI generators, docs, and architecture lint stay aligned.`,
       });
     }
 
+    if (isTestSourceFile(file)) continue;
+    if (!file.endsWith(".ts")) continue;
+
     if (
       isNotificationDefinitionFile(file, featuresPath) ||
       isInfraOrServerFile(file, config)
@@ -3890,6 +4251,15 @@ async function inspectFeatureArtifactDrift(
   return diagnostics;
 }
 
+function directFeatureTestMatch(
+  file: string,
+  featuresPath: string,
+): RegExpExecArray | null {
+  return new RegExp(
+    `^${escapeRegExp(featuresPath)}/([^/]+)/[^/]+\\.(?:test|spec)\\.(?:ts|tsx|mts|cts)$`,
+  ).exec(file);
+}
+
 function isFeatureArtifactFile(
   file: string,
   featuresPath: string,
@@ -3922,34 +4292,30 @@ async function appHasUploadRoute(
   return false;
 }
 
-function misplacedFeatureArtifactFolder(
+function misplacedFeatureLayer(
   file: string,
-  featuresPath: string,
+  config: ResolvedBeignetConfig,
 ): { actual: string; expected: string } | undefined {
-  const match = new RegExp(
-    `^${escapeRegExp(featuresPath)}/([^/]+)/([^/]+)/`,
-  ).exec(file);
+  const featuresPath = directoryPath(config.paths.features);
+  const match = new RegExp(`^${escapeRegExp(featuresPath)}/([^/]+)/(.+)$`).exec(
+    file,
+  );
   if (!match) return undefined;
 
-  const folder = match[2];
-  const mappings: Record<string, string> = {
-    command: "tasks/",
-    commands: "tasks/",
-    event: "domain/events/",
-    events: "domain/events/",
-    job: "jobs/",
-    listener: "listeners/",
-    notification: "notifications/",
-    schedule: "schedules/",
-    scheduled: "schedules/",
-    task: "tasks/",
-    upload: "uploads/",
-  };
+  const canonicalPath = canonicalFeatureLayerPath(file, config);
+  if (!canonicalPath) return undefined;
 
-  const expected = mappings[folder];
-  if (!expected) return undefined;
+  const featurePrefix = `${featuresPath}/${match[1]}/`;
+  const actualRelative = file.slice(featurePrefix.length);
+  const expectedRelative = canonicalPath.slice(featurePrefix.length);
+  const actual = actualRelative.includes("/")
+    ? `${actualRelative.split("/")[0]}/`
+    : actualRelative;
+  const expectedDirectory = path.posix.dirname(expectedRelative);
+  const expected =
+    expectedDirectory === "." ? expectedRelative : `${expectedDirectory}/`;
 
-  return { actual: `${folder}/`, expected };
+  return { actual, expected };
 }
 
 function isNotificationDefinitionFile(
@@ -4328,10 +4694,7 @@ async function workflowRegistrationDrift(
         // Events without listeners have nothing to deliver on drain, so only
         // record-only events stay out of the registry without a warning.
         const listened = await listenedEventNames(targetDir, files, config);
-        const value = outboxRegistryValueInfo(outboxSource, "events");
-        const registered = value
-          ? identifiersFromArrayExpression(value.text)
-          : new Set<string>();
+        const registered = outboxRegistryIdentifiers(outboxSource, "events");
         drift.outbox.events = unregisteredWorkflowRegistries(
           eventRegistries,
           registered,
@@ -4340,10 +4703,7 @@ async function workflowRegistrationDrift(
       }
 
       if (jobRegistries.length > 0) {
-        const value = outboxRegistryValueInfo(outboxSource, "jobs");
-        const registered = value
-          ? identifiersFromArrayExpression(value.text)
-          : new Set<string>();
+        const registered = outboxRegistryIdentifiers(outboxSource, "jobs");
         drift.outbox.jobs = unregisteredWorkflowRegistries(
           jobRegistries,
           registered,
@@ -5043,6 +5403,56 @@ async function appHasOutboxDrainEntrypoint(
   return false;
 }
 
+async function inspectOutboxJobDispatcherDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<InspectDiagnostic[]> {
+  if (!hasOutboxRegistry(files, config)) return [];
+
+  const source = await readFile(
+    path.join(targetDir, config.paths.outbox),
+    "utf8",
+  );
+  const jobsState = outboxRegistryEntryState(source, "jobs");
+  if (jobsState === "absent" || jobsState === "empty") return [];
+
+  const analysis = await analyzePortWiringFiles({ targetDir, files, config });
+  const declaresJobs = analysis.declared.has("jobs");
+  const wiresJobs = analysis.bound.has("jobs") || analysis.deferred.has("jobs");
+  if (declaresJobs && wiresJobs) return [];
+
+  const file =
+    jobsState === "indeterminate"
+      ? config.paths.outbox
+      : !declaresJobs
+        ? config.paths.ports
+        : config.paths.portWiring;
+  const reason = !analysis.portsFileExists
+    ? `${config.paths.ports} does not exist at the configured path`
+    : !declaresJobs
+      ? analysis.declarationIndeterminate
+        ? `${config.paths.ports} does not expose a statically verifiable jobs declaration`
+        : `${config.paths.ports} does not declare a jobs port`
+      : !analysis.portWiringFileExists
+        ? `${config.paths.portWiring} does not exist at the configured path`
+        : analysis.indeterminate
+          ? `${config.paths.portWiring} does not expose statically verifiable jobs wiring`
+          : `${config.paths.portWiring} does not bind or defer the jobs port`;
+
+  return [
+    {
+      severity: "warning",
+      code: "BEIGNET_OUTBOX_JOB_DISPATCHER_MISSING",
+      file,
+      message:
+        jobsState === "indeterminate"
+          ? `The jobs entries in the outbox registry at ${config.paths.outbox} could not be statically resolved, and ${reason}. Keep the jobs property explicit so doctor can verify it, or add jobs: JobDispatcherPort to AppPorts and bind it directly or list "jobs" as deferred with an inline or provider-backed dispatcher. If the app uses custom paths, configure paths.ports and paths.portWiring in beignet.config.ts.`
+          : `The outbox registry in ${config.paths.outbox} contains jobs, but ${reason}. Add jobs: JobDispatcherPort to AppPorts and bind it directly or list "jobs" as deferred with an inline or provider-backed dispatcher. If the app uses custom paths, configure paths.ports and paths.portWiring in beignet.config.ts.`,
+    },
+  ];
+}
+
 async function inspectPortProviderDrift(
   targetDir: string,
   files: string[],
@@ -5175,7 +5585,7 @@ async function inspectDatabaseLifecycleDrift(
   }
 
   if (hasDrizzleArtifacts) {
-    for (const script of ["db:generate", "db:migrate"] as const) {
+    for (const script of ["db:generate", "db:migrate", "db:status"] as const) {
       if (packageScripts[script]) continue;
       diagnostics.push({
         severity: "warning",
@@ -5257,6 +5667,12 @@ async function inspectDatabaseLifecycleDrift(
       file: `${infrastructurePath}/db/reset.ts`,
       code: "BEIGNET_DB_RESET_ENTRYPOINT_MISSING",
     },
+    {
+      script: "db:status",
+      command: "status",
+      file: `${infrastructurePath}/db/migration-status.ts`,
+      code: "BEIGNET_DB_STATUS_ENTRYPOINT_MISSING",
+    },
   ] as const;
 
   for (const entrypoint of standardEntrypoints) {
@@ -6284,6 +6700,32 @@ function configuredProviderRequiredEnv(
   return envVars.filter((envVar) => !ignored.has(envVar));
 }
 
+function configuredProviderRequiredEnvAlternatives(
+  alternatives: readonly (readonly string[])[],
+  config: ResolvedBeignetConfig,
+): string[][] {
+  return alternatives.map((alternative) =>
+    configuredProviderRequiredEnv(alternative, config),
+  );
+}
+
+async function providerRequiredEnvAlternativeExists(
+  targetDir: string,
+  configFiles: readonly string[],
+  alternatives: readonly (readonly string[])[],
+  sourceCache: Map<string, string>,
+): Promise<boolean> {
+  for (const alternative of alternatives) {
+    const exists = await Promise.all(
+      alternative.map((envVar) =>
+        providerRequiredEnvExists(targetDir, configFiles, envVar, sourceCache),
+      ),
+    );
+    if (exists.every(Boolean)) return true;
+  }
+  return false;
+}
+
 function configuredProviderRequiredTable(
   tableName: string,
   config: ResolvedBeignetConfig,
@@ -8309,8 +8751,9 @@ async function contractsFromRoutesSource(
     source,
     routeIdentifier,
   );
+  const { contracts } = await readContracts(targetDir, files, config);
   const registeredContracts = contractsForRegisteredRouteGroups(
-    await readContracts(targetDir, files, config),
+    contracts,
     routeGroups,
     registeredGroups,
   );