@supacloud/compiler 0.10.0 → 0.11.0

package/README.md

@@ -257,6 +257,24 @@ bun test
 bun run build
 ```
 
+## Route Contract Policy
+
+Enable `requireRouteContracts: true` in `defineSupacloudConfig(...)` or
+`CompileOptions` to report `route-contract-required` errors in both compile and
+check (including JSON diagnostics). Changing this option invalidates incremental
+results. Combine it with `writeOnError: false` when programmatic compilation must
+not emit files on errors.
+
+`inspectRouteContracts(graph)` lists each route and its missing body, params,
+query, and response declarations. Required inputs are detected from handler
+bindings and controller/route path parameters. Responses always require an
+explicit declaration, including intentional void contracts.
+
+This checks declaration coverage only, not schema quality, handler/schema type
+equivalence, or database authorization. It deliberately does not auto-fix missing
+schemas with `unknown` placeholders. Consumers must define the actual contracts
+and test decoding separately. The policy defaults to false for existing projects.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -4682,6 +4682,39 @@ function isAnyKeyword(node) {
   return node.kind === ts4.SyntaxKind.AnyKeyword;
 }
 
+// src/route-contracts.ts
+function inspectRouteContracts(graph) {
+  return graph.modules.flatMap((module) => module.controllers.flatMap((controller) => controller.routes.map((route) => {
+    const missing = [];
+    if ((route.hasBodyBinding || route.handlerParams?.some((param) => param.kind === "body")) && !route.body)
+      missing.push("body");
+    if ((route.pathParams?.length || route.paramBindings?.length || route.handlerParams?.some((param) => param.kind === "param") || /:[^/]+/.test(`${controller.path}/${route.path}`)) && !route.params)
+      missing.push("params");
+    if ((route.queryBindings?.length || route.handlerParams?.some((param) => param.kind === "query")) && !route.query)
+      missing.push("query");
+    if (!route.response)
+      missing.push("response");
+    return {
+      module: module.name,
+      controller: controller.className,
+      handler: route.handler,
+      method: route.method,
+      path: `${controller.path}${route.path}`,
+      file: controller.file,
+      missing
+    };
+  })));
+}
+function validateRouteContracts(graph) {
+  return inspectRouteContracts(graph).filter((route) => route.missing.length).map((route) => ({
+    severity: "error",
+    code: "route-contract-required",
+    file: route.file,
+    message: `${route.controller}.${route.handler} (${route.method} ${route.path}) is missing contract declarations: ${route.missing.join(", ")}.`,
+    suggestion: "Declare the missing schemas and test actual request/response decoding. An opaque schema is not proof of validation."
+  }));
+}
+
 // src/compile.ts
 async function compileProject(options) {
   const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
@@ -4704,6 +4737,8 @@ async function compileProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -4767,6 +4802,8 @@ async function checkProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -5144,6 +5181,7 @@ function optionsKeyOf(options) {
     allowRouteCommandBindings: options.allowRouteCommandBindings,
     commandCapabilities: options.commandCapabilities,
     disallowControllerDirectDb: options.disallowControllerDirectDb,
+    requireRouteContracts: options.requireRouteContracts,
     detectOrphanModules: options.detectOrphanModules,
     generateClient: options.generateClient,
     generatePermissions: options.generatePermissions,
@@ -5399,6 +5437,7 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   outDir: "generated",
   include: ["**/*.module.ts", "**/*.ts"],
   strict: true,
+  requireRouteContracts: false,
   generateClient: true,
   generatePermissions: true,
   treeShakeUnusedProviders: true,
@@ -5418,6 +5457,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     outDir: resolve5(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
     include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
     strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
+    requireRouteContracts: resolved.requireRouteContracts ?? DEFAULT_SUPACLOUD_CONFIG.requireRouteContracts,
     generateClient: resolved.generateClient ?? DEFAULT_SUPACLOUD_CONFIG.generateClient,
     generatePermissions: resolved.generatePermissions ?? DEFAULT_SUPACLOUD_CONFIG.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset ?? DEFAULT_SUPACLOUD_CONFIG.moduleBoundaryPreset,
@@ -5445,6 +5485,7 @@ function compileOptionsFromConfig(config, cwd = process.cwd()) {
     outDir: resolved.outDir,
     include: resolved.include,
     strict: resolved.strict,
+    requireRouteContracts: resolved.requireRouteContracts,
     generateClient: resolved.generateClient,
     generatePermissions: resolved.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset,

package/dist/config.d.ts

@@ -4,6 +4,7 @@ export interface SupaCloudConfig {
     outDir?: string;
     include?: string[];
     strict?: boolean;
+    requireRouteContracts?: boolean;
     generateClient?: boolean;
     generatePermissions?: boolean;
     moduleBoundaryPreset?: ModuleBoundaryPresetName;
@@ -20,6 +21,7 @@ export declare function resolveSupacloudConfig(config?: SupaCloudConfig, cwd?: s
     outDir: string;
     include: string[];
     strict: boolean;
+    requireRouteContracts: boolean;
     generateClient: boolean;
     generatePermissions: boolean;
     moduleBoundaryPreset: ModuleBoundaryPresetName;

package/dist/index.d.ts

@@ -24,3 +24,4 @@ export type { SupaCloudConfig } from "./config";
 export { camelName } from "./util";
 export { ANGULAR_ENTERPRISE_RULES, CLEAN_ARCHITECTURE_RULES, MODULAR_MONOLITH_RULES, MODULE_BOUNDARY_PROFILES, getModuleBoundaryPreset, getModuleBoundaryProfile, resolveModuleBoundaries, } from "./profiles";
 export type { ApplicationGraph, AspectRefNode, CachedModuleEntry, CheckProjectResult, CommandExecutionCapabilities, CommandNode, CompileOptions, CompileResult, CompileStats, ControllerNode, DependencyGraphCache, DependencyGraphIndex, Diagnostic, DiagnosticFix, ModuleBoundaryPresetName, ModuleBoundaryProfile, ModuleBoundaryRule, ModuleNode, JobNode, ProviderKind, ProviderNode, QueryNode, RouteNode, Scope, TokenKind, TypeSafetyOptions, ValidateOptions, WatchEvent, WatchHandle, WatchOptions, FeatureSpecNode, FeatureTransitionNode, } from "./types";
+export { inspectRouteContracts, validateRouteContracts } from "./route-contracts";

package/dist/index.js

@@ -4863,6 +4863,39 @@ function isAnyKeyword(node) {
   return node.kind === ts5.SyntaxKind.AnyKeyword;
 }
 
+// src/route-contracts.ts
+function inspectRouteContracts(graph) {
+  return graph.modules.flatMap((module) => module.controllers.flatMap((controller) => controller.routes.map((route) => {
+    const missing = [];
+    if ((route.hasBodyBinding || route.handlerParams?.some((param) => param.kind === "body")) && !route.body)
+      missing.push("body");
+    if ((route.pathParams?.length || route.paramBindings?.length || route.handlerParams?.some((param) => param.kind === "param") || /:[^/]+/.test(`${controller.path}/${route.path}`)) && !route.params)
+      missing.push("params");
+    if ((route.queryBindings?.length || route.handlerParams?.some((param) => param.kind === "query")) && !route.query)
+      missing.push("query");
+    if (!route.response)
+      missing.push("response");
+    return {
+      module: module.name,
+      controller: controller.className,
+      handler: route.handler,
+      method: route.method,
+      path: `${controller.path}${route.path}`,
+      file: controller.file,
+      missing
+    };
+  })));
+}
+function validateRouteContracts(graph) {
+  return inspectRouteContracts(graph).filter((route) => route.missing.length).map((route) => ({
+    severity: "error",
+    code: "route-contract-required",
+    file: route.file,
+    message: `${route.controller}.${route.handler} (${route.method} ${route.path}) is missing contract declarations: ${route.missing.join(", ")}.`,
+    suggestion: "Declare the missing schemas and test actual request/response decoding. An opaque schema is not proof of validation."
+  }));
+}
+
 // src/compile.ts
 async function compileProject(options) {
   const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
@@ -4885,6 +4918,8 @@ async function compileProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -4948,6 +4983,8 @@ async function checkProject(options) {
     }
   }
   const typeSafety = resolveTypeSafety(options);
+  if (options.requireRouteContracts)
+    diagnostics.push(...validateRouteContracts(graph));
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
     outDir: options.outDir,
@@ -5132,6 +5169,7 @@ function optionsKeyOf(options) {
     allowRouteCommandBindings: options.allowRouteCommandBindings,
     commandCapabilities: options.commandCapabilities,
     disallowControllerDirectDb: options.disallowControllerDirectDb,
+    requireRouteContracts: options.requireRouteContracts,
     detectOrphanModules: options.detectOrphanModules,
     generateClient: options.generateClient,
     generatePermissions: options.generatePermissions,
@@ -5577,6 +5615,7 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   outDir: "generated",
   include: ["**/*.module.ts", "**/*.ts"],
   strict: true,
+  requireRouteContracts: false,
   generateClient: true,
   generatePermissions: true,
   treeShakeUnusedProviders: true,
@@ -5596,6 +5635,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     outDir: resolve6(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
     include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
     strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
+    requireRouteContracts: resolved.requireRouteContracts ?? DEFAULT_SUPACLOUD_CONFIG.requireRouteContracts,
     generateClient: resolved.generateClient ?? DEFAULT_SUPACLOUD_CONFIG.generateClient,
     generatePermissions: resolved.generatePermissions ?? DEFAULT_SUPACLOUD_CONFIG.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset ?? DEFAULT_SUPACLOUD_CONFIG.moduleBoundaryPreset,
@@ -5623,6 +5663,7 @@ function compileOptionsFromConfig(config, cwd = process.cwd()) {
     outDir: resolved.outDir,
     include: resolved.include,
     strict: resolved.strict,
+    requireRouteContracts: resolved.requireRouteContracts,
     generateClient: resolved.generateClient,
     generatePermissions: resolved.generatePermissions,
     moduleBoundaryPreset: resolved.moduleBoundaryPreset,
@@ -5660,6 +5701,7 @@ export {
   generateFeatureSource,
   getModuleBoundaryPreset,
   getModuleBoundaryProfile,
+  inspectRouteContracts,
   loadSupacloudConfig,
   renderApplication,
   resolveModuleBoundaries,
@@ -5668,5 +5710,6 @@ export {
   scanProductionSource,
   validateFeatureSpec,
   validateGraph,
+  validateRouteContracts,
   watchProject
 };

package/dist/route-contracts.d.ts

@@ -0,0 +1,12 @@
+import type { ApplicationGraph, Diagnostic } from "./types";
+/** Declaration coverage only; runtime decoding and database behavior require separate tests. */
+export declare function inspectRouteContracts(graph: ApplicationGraph): {
+    module: string;
+    controller: string;
+    handler: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+    path: string;
+    file: string;
+    missing: ("query" | "body" | "params" | "response")[];
+}[];
+export declare function validateRouteContracts(graph: ApplicationGraph): Diagnostic[];

package/dist/types.d.ts

@@ -290,6 +290,8 @@ export interface ApplicationGraph {
     };
 }
 export interface CompileOptions {
+    /** Require schemas for bound route inputs and responses. Does not prove runtime validation. */
+    requireRouteContracts?: boolean;
     /** Project root directory (containing tsconfig). */
     rootDir: string;
     /** Glob patterns, defaults to ['**\/*.module.ts', '**\/*.ts']. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",