@supacloud/compiler 0.9.0 → 0.11.0

package/README.md

@@ -12,6 +12,11 @@ bun add @supacloud/compiler
 
 ## 零配置项目
 
+需要完整运行入口时，使用 `supacloud-cli app init --root ./orders --name orders`。
+模板将本包放在 `devDependencies`，预置状态规格、治理能力、类型检查和本地测试。
+编译产物的 HTTP method / scope 保留字面量联合类型，可直接传给 Elysia 适配器；
+跨运行时依赖字典使用构造器/工厂参数类型连接，局部依赖保留类型推断和错误检查。
+
 在项目根目录执行：
 
 ```bash
@@ -252,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

@@ -2264,7 +2264,7 @@ import { access, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
 var HEADER = "// GENERATED BY @supacloud/compiler — do not edit";
 var INTERFACES = `export interface CompiledRoute {
-  method: string;
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
   path: string;
   handler: string;
   body?: unknown;
@@ -2335,7 +2335,7 @@ export type CompiledAspect = (
 export interface CompiledController {
   path: string;
   serviceKey: string;
-  scope: string;
+  scope: "application" | "request" | "job";
   routes: CompiledRoute[];
 }
 
@@ -2949,7 +2949,7 @@ ${indent(item, 2)}`).join(",")}
     switch (provider.kind) {
       case "class": {
         const useClass = this.imports.add(provider.useClass ?? provider.token, provider.importPath, provider.importModule);
-        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const args = provider.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(provider, dep), `ConstructorParameters<typeof ${useClass}>[${index}]`)).join(", ");
         const local = this.localVar(isMulti ? provider.useClass ?? `${provider.token}Item` : provider.token, kind);
         return {
           constLine: `const ${local} = ${this.instantiate(useClass, args, kind, provider.functionalInjects)};`,
@@ -2970,7 +2970,7 @@ ${indent(item, 2)}`).join(",")}
           return { constLine, key, expr: local2 };
         }
         const factory = this.imports.add(provider.useFactoryName ?? "", provider.importPath, provider.importModule);
-        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const args = provider.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(provider, dep), `Parameters<typeof ${factory}>[${index}]`)).join(", ");
         const local = this.localVar(isMulti ? provider.useFactoryName ?? `${provider.token}Item` : provider.token, kind);
         return { constLine: `const ${local} = ${factory}(${args});`, key, expr: local };
       }
@@ -2984,7 +2984,7 @@ ${indent(item, 2)}`).join(",")}
   }
   emitController(controller, kind) {
     const className = this.imports.add(controller.className, controller.importPath);
-    const args = controller.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(controller, dep))).join(", ");
+    const args = controller.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(controller, dep), `ConstructorParameters<typeof ${className}>[${index}]`)).join(", ");
     const key = camelName(controller.className);
     const local = this.localVar(controller.className, kind);
     return {
@@ -3042,6 +3042,13 @@ ${indent(item, 2)}`).join(",")}
       host: "hostDeps" in node ? node.hostDeps?.includes(token) ?? false : false
     };
   }
+  typedDepExpr(token, kind, options, type) {
+    const expression = this.depExpr(token, kind, options);
+    const localProvider = this.module.providers.find((provider) => this.locals[kind].get(provider.token) === expression);
+    if (expression === "undefined" || localProvider && !(localProvider.kind === "factory" && !localProvider.useFactoryName))
+      return expression;
+    return `${expression} as ${type}`;
+  }
   depExpr(token, kind, options = {}) {
     const isOptional = options.optional ?? false;
     const isSelf = options.self ?? false;
@@ -4675,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);
@@ -4697,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,
@@ -4760,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,
@@ -5137,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,
@@ -5392,6 +5437,7 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   outDir: "generated",
   include: ["**/*.module.ts", "**/*.ts"],
   strict: true,
+  requireRouteContracts: false,
   generateClient: true,
   generatePermissions: true,
   treeShakeUnusedProviders: true,
@@ -5411,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,
@@ -5438,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

@@ -2545,7 +2545,7 @@ import { access, mkdir, rename as rename2, unlink as unlink2, writeFile as write
 import { join as join2 } from "node:path";
 var HEADER = "// GENERATED BY @supacloud/compiler — do not edit";
 var INTERFACES = `export interface CompiledRoute {
-  method: string;
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
   path: string;
   handler: string;
   body?: unknown;
@@ -2616,7 +2616,7 @@ export type CompiledAspect = (
 export interface CompiledController {
   path: string;
   serviceKey: string;
-  scope: string;
+  scope: "application" | "request" | "job";
   routes: CompiledRoute[];
 }
 
@@ -3230,7 +3230,7 @@ ${indent(item, 2)}`).join(",")}
     switch (provider.kind) {
       case "class": {
         const useClass = this.imports.add(provider.useClass ?? provider.token, provider.importPath, provider.importModule);
-        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const args = provider.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(provider, dep), `ConstructorParameters<typeof ${useClass}>[${index}]`)).join(", ");
         const local = this.localVar(isMulti ? provider.useClass ?? `${provider.token}Item` : provider.token, kind);
         return {
           constLine: `const ${local} = ${this.instantiate(useClass, args, kind, provider.functionalInjects)};`,
@@ -3251,7 +3251,7 @@ ${indent(item, 2)}`).join(",")}
           return { constLine, key, expr: local2 };
         }
         const factory2 = this.imports.add(provider.useFactoryName ?? "", provider.importPath, provider.importModule);
-        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const args = provider.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(provider, dep), `Parameters<typeof ${factory2}>[${index}]`)).join(", ");
         const local = this.localVar(isMulti ? provider.useFactoryName ?? `${provider.token}Item` : provider.token, kind);
         return { constLine: `const ${local} = ${factory2}(${args});`, key, expr: local };
       }
@@ -3265,7 +3265,7 @@ ${indent(item, 2)}`).join(",")}
   }
   emitController(controller, kind) {
     const className = this.imports.add(controller.className, controller.importPath);
-    const args = controller.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(controller, dep))).join(", ");
+    const args = controller.deps.map((dep, index) => this.typedDepExpr(dep, kind, this.depOptions(controller, dep), `ConstructorParameters<typeof ${className}>[${index}]`)).join(", ");
     const key = camelName(controller.className);
     const local = this.localVar(controller.className, kind);
     return {
@@ -3323,6 +3323,13 @@ ${indent(item, 2)}`).join(",")}
       host: "hostDeps" in node ? node.hostDeps?.includes(token) ?? false : false
     };
   }
+  typedDepExpr(token, kind, options, type) {
+    const expression = this.depExpr(token, kind, options);
+    const localProvider = this.module.providers.find((provider) => this.locals[kind].get(provider.token) === expression);
+    if (expression === "undefined" || localProvider && !(localProvider.kind === "factory" && !localProvider.useFactoryName))
+      return expression;
+    return `${expression} as ${type}`;
+  }
   depExpr(token, kind, options = {}) {
     const isOptional = options.optional ?? false;
     const isSelf = options.self ?? false;
@@ -4856,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);
@@ -4878,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,
@@ -4941,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,
@@ -5125,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,
@@ -5570,6 +5615,7 @@ var DEFAULT_SUPACLOUD_CONFIG = {
   outDir: "generated",
   include: ["**/*.module.ts", "**/*.ts"],
   strict: true,
+  requireRouteContracts: false,
   generateClient: true,
   generatePermissions: true,
   treeShakeUnusedProviders: true,
@@ -5589,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,
@@ -5616,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,
@@ -5653,6 +5701,7 @@ export {
   generateFeatureSource,
   getModuleBoundaryPreset,
   getModuleBoundaryProfile,
+  inspectRouteContracts,
   loadSupacloudConfig,
   renderApplication,
   resolveModuleBoundaries,
@@ -5661,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.9.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",