@beignet/cli 0.0.1 → 0.0.3

package/src/inspect.ts

@@ -24,6 +24,9 @@ type HttpMethod =
   | "HEAD"
   | "OPTIONS";
 
+/**
+ * Contract discovered by app inspection.
+ */
 export type InspectedContract = {
   exportName: string;
   file: string;
@@ -31,12 +34,18 @@ export type InspectedContract = {
   path: string;
 };
 
+/**
+ * Route handler mapping discovered by app inspection.
+ */
 export type InspectedRoute = InspectedContract & {
   handlerFile?: string;
   handlerExport?: HttpMethod;
   handlerSource: "next-route" | "route-local" | "missing";
 };
 
+/**
+ * Doctor diagnostic produced by app inspection.
+ */
 export type InspectDiagnostic = {
   severity: "error" | "warning";
   code: string;
@@ -45,12 +54,18 @@ export type InspectDiagnostic = {
   contract?: string;
 };
 
+/**
+ * Automatic doctor fix that was applied.
+ */
 export type InspectFix = {
   code: string;
   message: string;
   file: string;
 };
 
+/**
+ * Detected app convention and missing convention files.
+ */
 export type InspectConvention = {
   kind: "standard" | "next" | "custom";
   nextLayout: boolean;
@@ -60,6 +75,9 @@ export type InspectConvention = {
   missingResourceGenerator: string[];
 };
 
+/**
+ * Full app inspection result.
+ */
 export type InspectAppResult = {
   targetDir: string;
   config: ResolvedBeignetConfig;
@@ -176,6 +194,9 @@ export async function applyDoctorFixes(
   return fixes;
 }
 
+/**
+ * Format inspected routes as a CLI table.
+ */
 export function formatRoutes(result: InspectAppResult): string {
   if (result.routes.length === 0) {
     return `No Beignet routes found in ${result.targetDir}`;
@@ -197,6 +218,9 @@ export function formatRoutes(result: InspectAppResult): string {
   ]);
 }
 
+/**
+ * Format doctor diagnostics and applied fixes for CLI output.
+ */
 export function formatDoctor(result: InspectAppResult): string {
   const fixLines =
     result.fixes.length === 0
@@ -797,6 +821,20 @@ async function inspectDiagnostics(
       contracts,
     )),
     ...(await inspectPortProviderDrift(targetDir, files, config, convention)),
+    ...(await inspectDatabaseLifecycleDrift(
+      targetDir,
+      files,
+      config,
+      convention,
+      strict,
+    )),
+    ...(await inspectServerlessFootguns(targetDir, files)),
+    ...(await inspectFeatureArtifactDrift(
+      targetDir,
+      files,
+      config,
+      convention,
+    )),
     ...(await inspectResourceSlices(
       targetDir,
       files,
@@ -809,6 +847,284 @@ async function inspectDiagnostics(
   return dedupeDiagnostics(diagnostics);
 }
 
+async function inspectFeatureArtifactDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const featuresPath = directoryPath(config.paths.features);
+  const uploadDefinitions = files.filter((file) =>
+    isFeatureArtifactFile(file, featuresPath, "uploads"),
+  );
+
+  if (
+    uploadDefinitions.length > 0 &&
+    !(await appHasUploadRoute(targetDir, files, config))
+  ) {
+    diagnostics.push({
+      severity: "warning",
+      code: "CK_UPLOAD_ROUTE_MISSING",
+      file: uploadDefinitions[0],
+      message:
+        "This app defines feature uploads but no known upload route. Register the upload registry with createUploadRouter(...) and expose it through createUploadRoute(...) so browser uploads can reach the workflow.",
+    });
+  }
+
+  for (const file of files) {
+    if (
+      !file.endsWith(".ts") ||
+      file.endsWith(".test.ts") ||
+      file.endsWith(".d.ts")
+    ) {
+      continue;
+    }
+
+    const misplaced = misplacedFeatureArtifactFolder(file, featuresPath);
+    if (misplaced) {
+      diagnostics.push({
+        severity: "warning",
+        code: "CK_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.`,
+      });
+    }
+
+    if (
+      isNotificationDefinitionFile(file, featuresPath) ||
+      isInfraOrServerFile(file, config)
+    ) {
+      continue;
+    }
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    if (containsCallExpression(source, "createInlineNotificationDispatcher")) {
+      diagnostics.push({
+        severity: "warning",
+        code: "CK_NOTIFICATION_PORT_BYPASS",
+        file,
+        message: `${file} creates a notification dispatcher directly. Application workflows should send notifications through ctx.ports.notifications so delivery can be swapped, tested, instrumented, and run through jobs/outbox consistently.`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+function isFeatureArtifactFile(
+  file: string,
+  featuresPath: string,
+  folder: "uploads" | "notifications",
+): boolean {
+  const match = new RegExp(
+    `^${escapeRegExp(featuresPath)}/[^/]+/${folder}/([^/]+)\\.ts$`,
+  ).exec(file);
+  return Boolean(match && match[1] !== "index");
+}
+
+async function appHasUploadRoute(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<boolean> {
+  for (const file of files) {
+    if (!file.endsWith(".ts") || file.endsWith(".test.ts")) continue;
+    if (!isRouteServerOrInfraFile(file, config)) continue;
+
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    if (
+      containsCallExpression(source, "createUploadRoute") ||
+      containsCallExpression(source, "createUploadRouter")
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function misplacedFeatureArtifactFolder(
+  file: string,
+  featuresPath: string,
+): { actual: string; expected: string } | undefined {
+  const match = new RegExp(
+    `^${escapeRegExp(featuresPath)}/([^/]+)/([^/]+)/`,
+  ).exec(file);
+  if (!match) return undefined;
+
+  const folder = match[2];
+  const mappings: Record<string, string> = {
+    event: "domain/events/",
+    events: "domain/events/",
+    job: "jobs/",
+    listener: "listeners/",
+    notification: "notifications/",
+    schedule: "schedules/",
+    scheduled: "schedules/",
+    upload: "uploads/",
+  };
+
+  const expected = mappings[folder];
+  if (!expected) return undefined;
+
+  return { actual: `${folder}/`, expected };
+}
+
+function isNotificationDefinitionFile(
+  file: string,
+  featuresPath: string,
+): boolean {
+  return isFeatureArtifactFile(file, featuresPath, "notifications");
+}
+
+function isRouteServerOrInfraFile(
+  file: string,
+  config: ResolvedBeignetConfig,
+): boolean {
+  return (
+    file.startsWith(`${directoryPath(config.paths.routes)}/`) ||
+    isInfraOrServerFile(file, config)
+  );
+}
+
+function isInfraOrServerFile(
+  file: string,
+  config: ResolvedBeignetConfig,
+): boolean {
+  const serverDir = directoryPath(path.dirname(config.paths.server));
+  const infrastructureDir = directoryPath(
+    path.dirname(config.paths.infrastructurePorts),
+  );
+
+  return (
+    file === config.paths.server ||
+    file.startsWith(`${serverDir}/`) ||
+    file === config.paths.infrastructurePorts ||
+    file.startsWith(`${infrastructureDir}/`)
+  );
+}
+
+function containsCallExpression(source: string, name: string): boolean {
+  return new RegExp(
+    `\\b${escapeRegExp(name)}\\s*(?:<[^;=(){}]*>\\s*)?\\(`,
+  ).test(source);
+}
+
+async function inspectServerlessFootguns(
+  targetDir: string,
+  files: string[],
+): Promise<InspectDiagnostic[]> {
+  const diagnostics: InspectDiagnostic[] = [];
+
+  for (const file of files) {
+    if (
+      !file.endsWith(".ts") ||
+      file.endsWith(".test.ts") ||
+      file.endsWith(".d.ts")
+    ) {
+      continue;
+    }
+
+    const isInfraOrServerFile =
+      file.startsWith("infra/") || file.startsWith("server/");
+    const isProviderFile =
+      /(^|\/)provider(s)?\.ts$/.test(file) ||
+      /(^|\/)[^/]*provider[^/]*\.ts$/.test(file);
+    const source = await readFile(path.join(targetDir, file), "utf8");
+
+    if (
+      isInfraOrServerFile &&
+      isProviderFile &&
+      /\bset(?:Interval|Timeout)\s*\(/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "CK_PROVIDER_BACKGROUND_WORK",
+        file,
+        message: `${file} starts timer-based work from provider/server setup. Serverless apps should expose bounded runtime entrypoints such as cron routes, scheduled handlers, job functions, or worker processes instead of provider polling loops.`,
+      });
+    }
+
+    if (
+      isInfraOrServerFile &&
+      isProviderFile &&
+      /\bcreateProvider\s*\(/.test(source) &&
+      /\bdrainOutbox\s*\(/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "CK_PROVIDER_OUTBOX_DRAIN",
+        file,
+        message: `${file} drains the outbox from provider lifecycle code. Move outbox delivery to createOutboxDrainRoute(...) or another bounded runtime entrypoint so imports and serverless cold starts do not run background work.`,
+      });
+    }
+
+    if (
+      file.startsWith("app/api/cron/") &&
+      file.endsWith("/route.ts") &&
+      !/\bauthorization\b/i.test(source) &&
+      !/\bcreateOutboxDrainRoute\s*\(/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "CK_CRON_ROUTE_AUTH_MISSING",
+        file,
+        message: `${file} looks like a cron route without an authorization check. Require a shared secret or use a framework route helper such as createOutboxDrainRoute(...).`,
+      });
+    }
+  }
+
+  if (
+    hasOutboxRegistry(files) &&
+    !(await appHasOutboxDrainEntrypoint(targetDir, files))
+  ) {
+    diagnostics.push({
+      severity: "warning",
+      code: "CK_OUTBOX_DRAIN_MISSING",
+      message:
+        "This app defines an outbox registry but no known drain entrypoint. Add a cron/schedule/job route with createOutboxDrainRoute(...) so durable events and jobs are delivered in serverless deployments.",
+    });
+  }
+
+  return diagnostics;
+}
+
+function hasOutboxRegistry(files: string[]): boolean {
+  return files.some(isOutboxRegistryFile);
+}
+
+function isOutboxRegistryFile(file: string): boolean {
+  return file === "server/outbox.ts";
+}
+
+async function appHasOutboxDrainEntrypoint(
+  targetDir: string,
+  files: string[],
+): Promise<boolean> {
+  for (const file of files) {
+    if (!file.endsWith(".ts") || file.endsWith(".test.ts")) continue;
+    if (
+      !file.startsWith("app/api/") &&
+      !file.startsWith("server/") &&
+      !file.startsWith("infra/")
+    ) {
+      continue;
+    }
+
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    if (
+      /\bcreateOutboxDrainRoute\s*\(/.test(source) ||
+      /\bdrainOutbox\s*\(/.test(source)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 async function inspectPortProviderDrift(
   targetDir: string,
   files: string[],
@@ -875,6 +1191,178 @@ async function inspectPortProviderDrift(
   return diagnostics;
 }
 
+async function inspectDatabaseLifecycleDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  strict: boolean,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const resources = await collectResourceNames(targetDir, files, config);
+  const infrastructurePath = directoryPath(
+    path.dirname(config.paths.infrastructurePorts),
+  );
+  const featuresPath = directoryPath(config.paths.features);
+  const repositoriesPath = path.join(
+    infrastructurePath,
+    "db",
+    "repositories.ts",
+  );
+  const repositoriesSource = files.includes(repositoriesPath)
+    ? await readFile(path.join(targetDir, repositoriesPath), "utf8")
+    : "";
+
+  for (const resource of resources) {
+    const singular = singularize(resource);
+    const pascal = pascalCase(singular);
+    const pluralCamel = camelCase(resource);
+    const infrastructureDir = `${infrastructurePath}/${resource}/`;
+    const hasRepositoryAdapter = hasRepositoryAdapterFile(
+      files,
+      infrastructureDir,
+    );
+    const drizzleRepositoryAdapter = drizzleRepositoryAdapterFile(
+      files,
+      infrastructureDir,
+      singular,
+    );
+
+    const portFile = resourcePortFile(resource, singular, config);
+
+    if (files.includes(portFile) && !hasRepositoryAdapter) {
+      diagnostics.push({
+        severity: "warning",
+        code: "CK_REPOSITORY_ADAPTER_MISSING",
+        file: portFile,
+        message: `${portFile} declares a repository port, but ${infrastructureDir} does not contain a repository adapter. Add an infra adapter such as drizzle-${singular}-repository.ts and wire it through app ports.`,
+      });
+    }
+
+    if (drizzleRepositoryAdapter) {
+      const factoryName = `createDrizzle${pascal}Repository`;
+      if (
+        repositoriesSource &&
+        (!repositoriesSource.includes(factoryName) ||
+          !new RegExp(`\\b${pluralCamel}\\s*:`).test(repositoriesSource))
+      ) {
+        diagnostics.push({
+          severity: "warning",
+          code: "CK_DRIZZLE_REPOSITORY_UNWIRED",
+          file: repositoriesPath,
+          message: `${drizzleRepositoryAdapter} exists, but ${repositoriesPath} does not appear to import and return ${factoryName}(db). Wire the repository through createRepositories(...) so normal and transaction-scoped ports stay aligned.`,
+        });
+      }
+    }
+
+    if (
+      strict &&
+      hasFeatureSeeds(files, featuresPath, resource) &&
+      !hasFeatureFactories(files, featuresPath, resource)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "CK_FACTORY_MISSING",
+        file: `${featuresPath}/${resource}/seeds/`,
+        message: `${resource} defines feature seeds but no feature factory. Add a factory under ${featuresPath}/${resource}/tests/factories/ so seeds and tests share the same app-owned data setup path.`,
+      });
+    }
+  }
+
+  if (
+    hasAnyFeatureSeeds(files, featuresPath) &&
+    !(await packageScriptExists(targetDir, files, "db:seed"))
+  ) {
+    diagnostics.push({
+      severity: "warning",
+      code: "CK_DB_SEED_SCRIPT_MISSING",
+      file: "package.json",
+      message:
+        'This app defines feature seeds, but package.json does not define "db:seed". Add an app-owned db:seed script so beignet db seed can run the seed entrypoint.',
+    });
+  }
+
+  return diagnostics;
+}
+
+function hasRepositoryAdapterFile(
+  files: string[],
+  infrastructureDir: string,
+): boolean {
+  return files.some(
+    (file) =>
+      file.startsWith(infrastructureDir) &&
+      file.endsWith("-repository.ts") &&
+      !file.endsWith(".test.ts"),
+  );
+}
+
+function drizzleRepositoryAdapterFile(
+  files: string[],
+  infrastructureDir: string,
+  singular: string,
+): string | undefined {
+  return files.find(
+    (file) =>
+      file.startsWith(infrastructureDir) &&
+      file.endsWith(`/drizzle-${singular}-repository.ts`),
+  );
+}
+
+function hasFeatureSeeds(
+  files: string[],
+  featuresPath: string,
+  resource: string,
+): boolean {
+  return files.some(
+    (file) =>
+      file.startsWith(`${featuresPath}/${resource}/seeds/`) &&
+      file.endsWith(".ts") &&
+      !file.endsWith("/index.ts"),
+  );
+}
+
+function hasAnyFeatureSeeds(files: string[], featuresPath: string): boolean {
+  return files.some(
+    (file) =>
+      new RegExp(`^${escapeRegExp(featuresPath)}/[^/]+/seeds/`).test(file) &&
+      file.endsWith(".ts") &&
+      !file.endsWith("/index.ts"),
+  );
+}
+
+function hasFeatureFactories(
+  files: string[],
+  featuresPath: string,
+  resource: string,
+): boolean {
+  return files.some(
+    (file) =>
+      file === `${featuresPath}/${resource}/tests/factories.ts` ||
+      (file.startsWith(`${featuresPath}/${resource}/tests/factories/`) &&
+        file.endsWith(".ts") &&
+        !file.endsWith("/index.ts")),
+  );
+}
+
+async function packageScriptExists(
+  targetDir: string,
+  files: string[],
+  script: string,
+): Promise<boolean> {
+  if (!files.includes("package.json")) return false;
+
+  const packageJson = JSON.parse(
+    await readFile(path.join(targetDir, "package.json"), "utf8"),
+  ) as {
+    scripts?: Record<string, string>;
+  };
+
+  return Boolean(packageJson.scripts?.[script]);
+}
+
 const canonicalProviderPorts = [
   {
     packageName: "@beignet/provider-auth-better-auth",
@@ -1128,7 +1616,7 @@ function parseFeatureRouteGroups(
 ): 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;
+    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=\s*defineRouteGroup(?:<[^>]+>)?\(\s*(?:\)\s*\(\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)]
@@ -1745,9 +2233,10 @@ async function isGeneratedResourcePort(
 
   return (
     source.includes(`Create${singularPascal}Input`) &&
-    source.includes(`List${pluralPascal}Input`) &&
     source.includes(`List${pluralPascal}Result`) &&
+    source.includes("OffsetPage") &&
     source.includes(`interface ${singularPascal}Repository`) &&
+    source.includes("list(page: OffsetPage)") &&
     source.includes(`create(input: Create${singularPascal}Input)`)
   );
 }
@@ -1853,7 +2342,7 @@ function resourceDiagnostic(
     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.`,
+    message: `${resource} appears to be a generated feature slice, but ${file} is missing. Re-run make feature ${resource}, restore the missing file, or remove the partial feature wiring.`,
   };
 }
 
@@ -1893,6 +2382,11 @@ function pascalCase(value: string): string {
     .join("");
 }
 
+function camelCase(value: string): string {
+  const pascal = pascalCase(value);
+  return `${pascal.charAt(0).toLowerCase()}${pascal.slice(1)}`;
+}
+
 function singularize(value: string): string {
   if (value.endsWith("ies") && value.length > 3) {
     return `${value.slice(0, -3)}y`;