@beignet/cli 0.0.47 → 0.0.49

package/dist/inspect.js

@@ -1,14 +1,19 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { parseProviderPackageMetadata } from "@beignet/core/providers";
+import ts from "typescript";
+import { 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 { clientDirPath, clientFormsPath, clientIndexPath, defaultBeignetConfig, directoryPath, loadBeignetConfig, normalizePath, resolveConfig, } from "./config.js";
 import { renderDatabaseSchema, resolveDatabaseSchemaDialect } from "./db.js";
 import { applyPlannedDoctorFixes, createDoctorFixPlan, planDoctorFixFileChange, publicDoctorFixPlan, } from "./doctor-fixes.js";
 import { formatGithubAnnotation, } from "./github-annotations.js";
 import { createListenersRegistrySource, listenersFilePath, providersFilePath, updateListenersRegistrySource, wireListenersProviderSource, } from "./make/shared.js";
-import { detectedProviderVariants, diagnosticPackageJsonFile, formatProviderMetadataIssues, installedPackageNames, providerDoctorRulesForInstalledPackages, providerOperationalConfigFiles, providerRequiredEnvExists, providerRequiredTableExists, providerVariantRegistrationSeverity, readProviderListEntries, readProviderPackageMetadataSource, registrationTokenHint, serverProviderFiles, } from "./provider-audit.js";
-import { appendToArrayExpression, appendToNamedArray, appendToOutboxRegistryArray, arrayInitializerInfo, codeCharacterIndexes, identifiersFromArrayExpression, insertAfterImports, matchingDelimiterIndex, outboxRegistryValueInfo, } from "./registry-edits.js";
+import { detectedProviderVariants, diagnosticPackageJsonFile, formatProviderEnvAlternatives, formatProviderMetadataIssues, installedPackageNames, providerDoctorRulesForInstalledPackages, providerOperationalConfigFiles, providerRequiredEnvExists, providerRequiredTableExists, providerVariantRegistrationSeverity, readProviderListEntries, readProviderPackageMetadataSource, registrationTokenHint, serverProviderFiles, } from "./provider-audit.js";
+import { appendToArrayExpression, appendToNamedArray, appendToOutboxRegistryArray, arrayInitializerInfo, codeCharacterIndexes, identifiersFromArrayExpression, insertAfterImports, matchingDelimiterIndex, outboxRegistryEntryState, outboxRegistryIdentifiers, } from "./registry-edits.js";
 import { currentGeneratedPackageScripts, externalVersions, isLegacyGeneratedPackageScript, legacyGeneratedPackageScripts, } from "./templates/shared.js";
 import { testSupportTemplateFiles } from "./templates/testing.js";
 import { getCliVersion } from "./version.js";
@@ -20,9 +25,10 @@ export async function inspectApp(options = {}) {
         ? 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, config, contracts);
-    const diagnostics = await inspectDiagnostics(targetDir, files, config, convention, contracts, matchedRoutes, Boolean(options.strict));
+    const diagnostics = await inspectDiagnostics(targetDir, files, config, convention, contracts, matchedRoutes, Boolean(options.strict), inspectedContracts.queryTransportDiagnostics);
     return {
         schemaVersion: 1,
         targetDir,
@@ -76,7 +82,7 @@ async function buildDoctorFixPlan(options = {}) {
         ? 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, config, contracts);
     const operations = [];
     const packageFix = await planPackageScripts(targetDir, files, convention);
@@ -318,7 +324,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",
@@ -409,12 +414,28 @@ async function listFiles(targetDir) {
 }
 async function readContracts(targetDir, files, config) {
     const contracts = [];
+    const queryTransportDiagnostics = [];
     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(files, config) {
     const missingNextLayout = missingRequirements(files, [
@@ -464,47 +485,77 @@ function hasRequirement(files, requirement) {
 }
 function parseContracts(source, file) {
     const contracts = [];
-    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;
-    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]);
-            contracts.push({
-                exportName: exportMatch[1],
-                file,
-                metadata: parseContractMetadata(block, groupErrorRefs.get(receiver) ?? []),
-                method: methodMatch[2].toUpperCase(),
-                path: routePath,
-            });
+    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 { exportName, declaration } of exportedVariableDeclarations(sourceFile)) {
+        if (!declaration.initializer)
             continue;
-        }
-        const directContract = parseDirectContract(block);
+        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),
-                method: directContract.method,
-                path: normalizeContractPath(directContract.path),
+                contract: {
+                    exportName,
+                    file,
+                    metadata: parseContractMetadata(applyContractMetadataCalls(emptyContractMetadataState(), chain.calls)),
+                    method: directContract.method,
+                    path: normalizeContractPath(directContract.path),
+                },
+                queryTransportMissing: contractQueryHasTransport(chain) === false,
             });
+            continue;
         }
+        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(applyContractMetadataCalls(emptyContractMetadataState(), chain.calls)),
+                method: methodCall.name.toUpperCase(),
+                path: joinContractPaths(pathPrefix, routePath),
+            },
+            queryTransportMissing: contractQueryHasTransport(chain) === false,
+        });
     }
     return contracts;
 }
-function parseContractMetadata(block, inheritedCatalogErrors = []) {
-    const authRequired = /\bauth\s*:\s*["']required["']/.test(block);
-    const authorizationAbility = /\bauthorization\s*:\s*\{[\s\S]*?\bability\s*:\s*["']([^"']+)["']/.exec(block)?.[1];
-    const auditRequired = /\baudit\s*:\s*["']required["']/.test(block) ||
-        /\bauditRequired\s*:\s*true\b/.test(block);
-    const catalogErrors = dedupeCatalogErrorRefs([
-        ...inheritedCatalogErrors,
-        ...parseCatalogErrorRefs(block),
-    ]);
+function unwrapContractExpression(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;
+}
+function emptyContractMetadataState() {
+    return { catalogErrors: [] };
+}
+function parseContractMetadata(state) {
+    const authRequired = state.authRequired === true;
+    const authorizationAbility = state.authorizationAbility;
+    const auditRequired = state.audit === true ||
+        state.auditRequired === true ||
+        state.authorizationAuditRequired === true;
+    const catalogErrors = state.catalogErrors;
     if (!authRequired &&
         !authorizationAbility &&
         !auditRequired &&
@@ -518,100 +569,271 @@ function parseContractMetadata(block, inheritedCatalogErrors = []) {
         catalogErrors,
     };
 }
-function parseDirectContract(block) {
-    const configMatch = /defineContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
-    if (!configMatch)
+function applyContractMetadataCalls(initialState, calls) {
+    const state = {
+        ...initialState,
+        catalogErrors: [...initialState.catalogErrors],
+    };
+    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]);
+        }
+    }
+    return state;
+}
+function applyContractMetaObject(state, metadata) {
+    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) {
+    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) {
+    const value = staticString(expression);
+    return value === undefined ? undefined : value === "required";
+}
+function staticBoolean(expression) {
+    if (expression.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (expression.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
+function parseDirectContract(chain, factoryBindings) {
+    const factoryCall = contractFactoryCall(chain, "defineContract", factoryBindings);
+    if (!factoryCall)
+        return undefined;
+    const options = objectLiteral(factoryCall.arguments[0]);
+    if (!options)
         return undefined;
-    const configSource = configMatch[1];
-    const methodMatch = /method\s*:\s*["']([^"']+)["']/.exec(configSource);
-    const pathMatch = /path\s*:\s*["']([^"']+)["']/.exec(configSource);
-    if (!methodMatch || !pathMatch)
+    const methodValue = staticString(objectProperty(options, "method"));
+    const contractPath = staticString(objectProperty(options, "path"));
+    if (!methodValue || !contractPath)
         return undefined;
-    const method = methodMatch[1].toUpperCase();
+    const method = methodValue.toUpperCase();
     if (!isHttpMethod(method))
         return undefined;
-    return { method, path: pathMatch[1] };
+    return { method, path: contractPath };
 }
 function isHttpMethod(method) {
     return ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].includes(method);
 }
-function parseContractGroupPrefixes(source) {
-    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();
-    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)
+function variableAssignments(sourceFile) {
+    return sourceFile.statements
+        .filter(ts.isVariableStatement)
+        .flatMap((statement) => [...statement.declarationList.declarations]
+        .filter((declaration) => ts.isIdentifier(declaration.name) &&
+        declaration.initializer !== undefined)
+        .map((declaration) => ({
+        name: declaration.name.text,
+        expression: declaration.initializer,
+    })));
+}
+function resolveContractCallChain(expression, assignments, resolving = new Set()) {
+    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) {
+    const calls = [];
+    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;
-            const prefix = prefixCalls(assignment.expression).reduce((current, next) => joinContractPaths(current, next), basePrefix);
-            prefixes.set(assignment.name, prefix);
-            changed = true;
+            }
+            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 parseContractGroupErrorRefs(source) {
-    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();
-    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 contractFactoryCall(chain, name, factoryBindings) {
+    const calls = chain.rootCall ? [chain.rootCall] : chain.calls;
+    return calls.find((call) => isImportedContractFactoryCall(call.node, name, factoryBindings));
+}
+function applyStaticPrefixes(initialPrefix, calls) {
+    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 groupErrors;
+    return prefix;
+}
+function contractQueryHasTransport(chain) {
+    const queryCall = chain.calls.find((call) => call.name === "query");
+    return queryCall ? queryCall.arguments.length >= 2 : undefined;
 }
-function baseGroupErrors(expression, groupErrors) {
-    if (expression.includes("defineContractGroup("))
+function applyCatalogErrorCall(current, expression) {
+    const errors = objectLiteral(expression);
+    if (!errors)
         return [];
-    const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
-    if (!baseMatch)
-        return undefined;
-    return groupErrors.get(baseMatch[1]);
+    let merged = [...current];
+    for (const property of errors.properties) {
+        if (ts.isSpreadAssignment(property)) {
+            merged = [];
+            continue;
+        }
+        const key = staticPropertyName(property.name);
+        if (!key) {
+            merged = [];
+            continue;
+        }
+        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,
+        });
+    }
+    return merged;
 }
-function baseGroupPrefix(expression, prefixes) {
-    if (expression.includes("defineContractGroup("))
-        return "";
-    const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
-    if (!baseMatch)
+function objectLiteral(expression) {
+    if (!expression)
         return undefined;
-    return prefixes.get(baseMatch[1]);
-}
-function prefixCalls(expression) {
-    return [...expression.matchAll(/\.prefix\(\s*["']([^"']+)["']\s*\)/g)].map((match) => match[1]);
+    const unwrapped = unwrapContractExpression(expression);
+    return ts.isObjectLiteralExpression(unwrapped) ? unwrapped : undefined;
+}
+function objectProperty(object, name) {
+    const result = objectPropertyResult(object, name);
+    return result.kind === "value" ? result.value : undefined;
+}
+function objectPropertyResult(object, name) {
+    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 staticPropertyName(name) {
+    if (ts.isIdentifier(name) ||
+        ts.isStringLiteral(name) ||
+        ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return undefined;
 }
-function parseCatalogErrorRefs(source) {
-    return dedupeCatalogErrorRefs(objectArgumentBodies(source, /\.errors\s*\(/g).flatMap((body) => [...body.matchAll(errorCatalogRefRegex)].map((match) => ({
-        key: match[1],
-        catalog: match[2],
-        catalogKey: match[3],
-    }))));
+function staticString(expression) {
+    if (!expression)
+        return undefined;
+    const value = unwrapContractExpression(expression);
+    return ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)
+        ? value.text
+        : undefined;
 }
-const errorCatalogRefRegex = /(?:^|[,{])\s*([A-Za-z_$][\w$]*)\s*:\s*([A-Za-z_$][\w$]*)\s*\.\s*([A-Za-z_$][\w$]*)/g;
 function parseErrorCatalogKeys(source) {
     const keys = new Set();
     const catalogBodies = objectArgumentBodies(source, /\bdefineErrors\s*\(/g);
@@ -691,18 +913,6 @@ function topLevelObjectKeys(body) {
     }
     return keys;
 }
-function dedupeCatalogErrorRefs(refs) {
-    const seen = new Set();
-    const deduped = [];
-    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, routePath) {
     if (!prefix)
         return normalizeContractPath(routePath);
@@ -985,8 +1195,8 @@ function contractPathMatchesCatchAll(contractPath, catchAllPrefix) {
     return (contractPath === catchAllPrefix ||
         contractPath.startsWith(`${catchAllPrefix}/`));
 }
-async function inspectDiagnostics(targetDir, files, config, convention, contracts, matchedRoutes, strict) {
-    const diagnostics = [];
+async function inspectDiagnostics(targetDir, files, config, convention, contracts, matchedRoutes, strict, queryTransportDiagnostics) {
+    const diagnostics = [...queryTransportDiagnostics];
     const frameworkLayout = config.framework === "next" ? convention.nextLayout : convention.webLayout;
     const missingFrameworkLayout = config.framework === "next"
         ? convention.missingNextLayout
@@ -1025,7 +1235,7 @@ async function inspectDiagnostics(targetDir, files, config, convention, contract
             diagnostics.push(unmatchedRouteDiagnostic(routeHandler));
         }
     }
-    diagnostics.push(...(await inspectPackageScripts(targetDir, files, convention)), ...(await inspectOpenApiDrift(targetDir, files, config, convention, contracts, matchedRoutes)), ...(await inspectFeatureRouteRegistration(targetDir, files, config, convention, contracts)), ...(await inspectRouteErrorCatalogDrift(targetDir, files, config, convention, contracts, strict)), ...(await inspectCanonicalConformance(targetDir, files, config, convention, strict)), ...(await inspectVersionSkew(targetDir, files)), ...(await inspectProviderMetadataDrift(targetDir, files, convention)), ...(await inspectPortProviderDrift(targetDir, files, config, convention)), ...(await inspectProviderRegistrationDrift(targetDir, files, config, convention)), ...(await inspectInngestProductionPath(targetDir, files, config)), ...(await inspectDatabaseLifecycleDrift(targetDir, files, config, convention, strict)), ...(await inspectAuthzAuditDrift(targetDir, files, config, convention, contracts)), ...(await inspectServerlessFootguns(targetDir, files, config, convention)), ...(await inspectProductionReadiness(targetDir, files, config, convention)), ...(await inspectFeatureArtifactDrift(targetDir, files, config, convention)), ...(await inspectWorkflowRegistrationDrift(targetDir, files, config, convention)), ...(await inspectRuntimeManifestDrift(targetDir, files, config, convention)), ...(await inspectResourceSlices(targetDir, files, config, convention, strict)));
+    diagnostics.push(...(await inspectPackageScripts(targetDir, files, convention)), ...(await inspectOpenApiDrift(targetDir, files, config, convention, contracts, matchedRoutes)), ...(await inspectFeatureRouteRegistration(targetDir, files, config, convention, contracts)), ...(await inspectRouteErrorCatalogDrift(targetDir, files, config, convention, contracts, strict)), ...(await inspectCanonicalConformance(targetDir, files, config, convention, strict)), ...(await inspectVersionSkew(targetDir, files)), ...(await inspectProviderMetadataDrift(targetDir, files, convention)), ...(await inspectPortProviderDrift(targetDir, files, config, convention)), ...(await inspectProviderRegistrationDrift(targetDir, files, config, convention)), ...(await inspectInngestProductionPath(targetDir, files, config)), ...(await inspectDatabaseLifecycleDrift(targetDir, files, config, convention, strict)), ...(await inspectAuthzAuditDrift(targetDir, files, config, convention, contracts)), ...(await inspectServerlessFootguns(targetDir, files, config, convention)), ...(await inspectOutboxJobDispatcherDrift(targetDir, files, config)), ...(await inspectProductionReadiness(targetDir, files, config, convention)), ...(await inspectFeatureArtifactDrift(targetDir, files, config, convention)), ...(await inspectWorkflowRegistrationDrift(targetDir, files, config, convention)), ...(await inspectRuntimeManifestDrift(targetDir, files, config, convention)), ...(await inspectResourceSlices(targetDir, files, config, convention, strict)));
     return dedupeDiagnostics(diagnostics);
 }
 async function inspectFrameworkAdapter(targetDir, files, config) {
@@ -1485,13 +1695,13 @@ async function inspectProductionReadiness(targetDir, files, config, convention)
             hasSecurityHeadersHook = true;
         }
         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.`,
             });
         }
         if (fileWithinDirectory(file, cronDirectory) &&
@@ -1576,6 +1786,16 @@ async function inspectProductionReadiness(targetDir, files, config, convention)
             // Multi-variant packages only require the env vars of the variants the
             // app actually registers; an unused variant must not warn.
             for (const variant of detectedProviderVariants(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)) {
                     if (await providerRequiredEnvExists(targetDir, configFiles, envVar, sourceCache)) {
                         continue;
@@ -1601,6 +1821,16 @@ async function inspectProductionReadiness(targetDir, files, config, convention)
             }
             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)) {
             if (await providerRequiredEnvExists(targetDir, configFiles, envVar, sourceCache)) {
                 continue;
@@ -2296,7 +2526,7 @@ async function inspectFeatureArtifactDrift(targetDir, files, config, convention)
         });
     }
     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({
@@ -2307,20 +2537,25 @@ async function inspectFeatureArtifactDrift(targetDir, files, config, convention)
         });
     }
     for (const file of files) {
-        if (!file.endsWith(".ts") ||
-            file.endsWith(".test.ts") ||
-            file.endsWith(".d.ts")) {
+        if (!/\.(?: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)) {
             continue;
@@ -2337,6 +2572,9 @@ async function inspectFeatureArtifactDrift(targetDir, files, config, convention)
     }
     return diagnostics;
 }
+function directFeatureTestMatch(file, featuresPath) {
+    return new RegExp(`^${escapeRegExp(featuresPath)}/([^/]+)/[^/]+\\.(?:test|spec)\\.(?:ts|tsx|mts|cts)$`).exec(file);
+}
 function isFeatureArtifactFile(file, featuresPath, folder) {
     const match = new RegExp(`^${escapeRegExp(featuresPath)}/[^/]+/${folder}/([^/]+)\\.ts$`).exec(file);
     return Boolean(match && match[1] !== "index");
@@ -2355,28 +2593,23 @@ async function appHasUploadRoute(targetDir, files, config) {
     }
     return false;
 }
-function misplacedFeatureArtifactFolder(file, featuresPath) {
-    const match = new RegExp(`^${escapeRegExp(featuresPath)}/([^/]+)/([^/]+)/`).exec(file);
+function misplacedFeatureLayer(file, config) {
+    const featuresPath = directoryPath(config.paths.features);
+    const match = new RegExp(`^${escapeRegExp(featuresPath)}/([^/]+)/(.+)$`).exec(file);
     if (!match)
         return undefined;
-    const folder = match[2];
-    const mappings = {
-        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 expected = mappings[folder];
-    if (!expected)
+    const canonicalPath = canonicalFeatureLayerPath(file, config);
+    if (!canonicalPath)
         return undefined;
-    return { actual: `${folder}/`, expected };
+    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, expected };
 }
 function isNotificationDefinitionFile(file, featuresPath) {
     return isFeatureArtifactFile(file, featuresPath, "notifications");
@@ -2596,17 +2829,11 @@ async function workflowRegistrationDrift(targetDir, files, config) {
                 // 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();
+                const registered = outboxRegistryIdentifiers(outboxSource, "events");
                 drift.outbox.events = unregisteredWorkflowRegistries(eventRegistries, registered, (member) => listened.has(member));
             }
             if (jobRegistries.length > 0) {
-                const value = outboxRegistryValueInfo(outboxSource, "jobs");
-                const registered = value
-                    ? identifiersFromArrayExpression(value.text)
-                    : new Set();
+                const registered = outboxRegistryIdentifiers(outboxSource, "jobs");
                 drift.outbox.jobs = unregisteredWorkflowRegistries(jobRegistries, registered);
             }
         }
@@ -3094,6 +3321,45 @@ async function appHasOutboxDrainEntrypoint(targetDir, files, config) {
     }
     return false;
 }
+async function inspectOutboxJobDispatcherDrift(targetDir, files, config) {
+    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, files, config, convention) {
     if (!convention.resourceGenerator)
         return [];
@@ -3187,7 +3453,7 @@ async function inspectDatabaseLifecycleDrift(targetDir, files, config, conventio
         });
     }
     if (hasDrizzleArtifacts) {
-        for (const script of ["db:generate", "db:migrate"]) {
+        for (const script of ["db:generate", "db:migrate", "db:status"]) {
             if (packageScripts[script])
                 continue;
             diagnostics.push({
@@ -3246,6 +3512,12 @@ async function inspectDatabaseLifecycleDrift(targetDir, files, config, conventio
             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",
+        },
     ];
     for (const entrypoint of standardEntrypoints) {
         const script = packageScripts[entrypoint.script];
@@ -3881,6 +4153,17 @@ function configuredProviderRequiredEnv(envVars, config) {
     const ignored = new Set(config.providerAudit.ignoreRequiredEnv);
     return envVars.filter((envVar) => !ignored.has(envVar));
 }
+function configuredProviderRequiredEnvAlternatives(alternatives, config) {
+    return alternatives.map((alternative) => configuredProviderRequiredEnv(alternative, config));
+}
+async function providerRequiredEnvAlternativeExists(targetDir, configFiles, alternatives, sourceCache) {
+    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, config) {
     for (const [key, defaultTableName] of Object.entries(defaultBeignetConfig.database.tables)) {
         if (tableName === defaultTableName)
@@ -5239,7 +5522,8 @@ async function contractsFromRoutesSource(targetDir, files, config, file, source,
         return undefined;
     const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
     const registeredGroups = await registeredRouteGroupsForSource(targetDir, files, file, source, routeIdentifier);
-    const registeredContracts = contractsForRegisteredRouteGroups(await readContracts(targetDir, files, config), routeGroups, registeredGroups);
+    const { contracts } = await readContracts(targetDir, files, config);
+    const registeredContracts = contractsForRegisteredRouteGroups(contracts, routeGroups, registeredGroups);
     return new Set(registeredContracts.map((contract) => contract.exportName));
 }
 function contractsFromRoutesIdentifier(source, exportName) {