@supacloud/compiler 0.3.1 → 0.4.1

package/dist/compile.d.ts

@@ -1,6 +1,11 @@
-import type { CompileOptions, CompileResult } from "./types";
+import type { CheckProjectResult, CompileOptions, CompileResult } from "./types";
 /**
- * 完整编译流程：AST 分析 → 校验 → 生成静态工厂代码与 manifest。
- * 即使存在 error 级诊断也会照常写出文件，由调用方根据 diagnostics 决定是否采用。
+ * Complete compilation pipeline: AST analysis -> validation -> generate static factory code and manifest.
+ * Files are emitted even when error-level diagnostics exist; caller decides adoption based on diagnostics.
  */
 export declare function compileProject(options: CompileOptions): Promise<CompileResult>;
+/**
+ * Check generated artifacts without writing files to disk.
+ * Analyze the AST, run governance checks, and compare application.ts and app.manifest.json.
+ */
+export declare function checkProject(options: CompileOptions): Promise<CheckProjectResult>;

package/dist/generate.d.ts

@@ -3,8 +3,14 @@ export interface GenerateOptions {
     rootDir: string;
     outDir: string;
 }
+export interface RenderedArtifacts {
+    applicationCode: string;
+    manifestJson: string;
+}
+/** Render application.ts and app.manifest.json content without file I/O. */
+export declare function renderApplication(graph: ApplicationGraph, options: GenerateOptions): RenderedArtifacts;
 /**
- * 生成静态工厂代码（application.ts）与 app.manifest.json，返回写入的绝对路径。
- * 生成代码只 import 业务类/schema，不 import @supacloud/app，运行期无反射、无容器。
+ * Generate static factory code (application.ts) and app.manifest.json.
+ * Generated code imports only application classes and schemas, with no runtime reflection or container lookup.
  */
 export declare function generateApplication(graph: ApplicationGraph, options: GenerateOptions): Promise<string[]>;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { analyzeProject } from "./analyze";
-export { compileProject } from "./compile";
-export { generateApplication } from "./generate";
-export type { GenerateOptions } from "./generate";
+export { checkProject, compileProject } from "./compile";
+export { generateApplication, renderApplication } from "./generate";
+export type { GenerateOptions, RenderedArtifacts } from "./generate";
 export { validateGraph } from "./validate";
 export { camelName } from "./util";
-export type { ApplicationGraph, CommandNode, CompileOptions, CompileResult, ControllerNode, Diagnostic, ModuleBoundaryRule, ModuleNode, ProviderKind, ProviderNode, QueryNode, RouteNode, Scope, TokenKind, } from "./types";
+export { ANGULAR_ENTERPRISE_RULES, CLEAN_ARCHITECTURE_RULES, MODULAR_MONOLITH_RULES, MODULE_BOUNDARY_PROFILES, getModuleBoundaryPreset, getModuleBoundaryProfile, resolveModuleBoundaries, } from "./profiles";
+export type { ApplicationGraph, CheckProjectResult, CommandExecutionCapabilities, CommandNode, CompileOptions, CompileResult, ControllerNode, Diagnostic, ModuleBoundaryPresetName, ModuleBoundaryProfile, ModuleBoundaryRule, ModuleNode, ProviderKind, ProviderNode, QueryNode, RouteNode, Scope, TokenKind, ValidateOptions, } from "./types";

package/dist/index.js

@@ -12,7 +12,9 @@ var ROUTE_DECORATORS = {
   Post: "POST",
   Put: "PUT",
   Patch: "PATCH",
-  Delete: "DELETE"
+  Delete: "DELETE",
+  Head: "HEAD",
+  Options: "OPTIONS"
 };
 var SCOPES = ["application", "request", "job"];
 async function analyzeProject(rootDir, include) {
@@ -674,7 +676,7 @@ export interface CompiledModule {
   controllers: CompiledController[];
   commands: CompiledCommand[];
 }`;
-async function generateApplication(graph, options) {
+function renderApplication(graph, options) {
   const modules = topoSortModules(graph.modules);
   const imports = new ImportManager;
   const factorySections = [];
@@ -706,12 +708,19 @@ async function generateApplication(graph, options) {
     modules: graph.modules,
     externalTokens: graph.externalTokens
   };
+  return {
+    applicationCode: code,
+    manifestJson: JSON.stringify(manifest, null, 2) + `
+`
+  };
+}
+async function generateApplication(graph, options) {
+  const rendered = renderApplication(graph, options);
   await mkdir(options.outDir, { recursive: true });
   const applicationPath = join2(options.outDir, "application.ts");
   const manifestPath = join2(options.outDir, "app.manifest.json");
-  await writeFile(applicationPath, code, "utf8");
-  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + `
-`, "utf8");
+  await writeFile(applicationPath, rendered.applicationCode, "utf8");
+  await writeFile(manifestPath, rendered.manifestJson, "utf8");
   return [applicationPath, manifestPath];
 }
 function factoryOfScope(scope) {
@@ -1008,6 +1017,173 @@ function orderProviders(providers) {
   return result;
 }
 
+// src/profiles.ts
+var MODULAR_MONOLITH_RULES = [
+  {
+    sourceTag: "type:feature",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:root",
+    onlyDependOnLibsWithTags: ["type:feature", "type:core", "type:shared", "type:domain"]
+  },
+  {
+    sourceTag: "type:app",
+    onlyDependOnLibsWithTags: ["type:feature", "type:core", "type:shared", "type:domain"]
+  },
+  {
+    sourceTag: "type:core",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:shared",
+    bannedDependenciesWithTags: ["type:feature", "type:core", "type:root", "type:app"]
+  }
+];
+var ANGULAR_ENTERPRISE_RULES = [
+  {
+    sourceTag: "type:feature",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:ui",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:data-access",
+    bannedDependenciesWithTags: ["type:feature", "type:ui", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:util",
+    bannedDependenciesWithTags: ["type:feature", "type:ui", "type:data-access", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:shared",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:core",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:root",
+    onlyDependOnLibsWithTags: ["type:feature", "type:ui", "type:data-access", "type:core", "type:shared", "type:util"]
+  },
+  {
+    sourceTag: "type:app",
+    onlyDependOnLibsWithTags: ["type:feature", "type:ui", "type:data-access", "type:core", "type:shared", "type:util"]
+  }
+];
+var CLEAN_ARCHITECTURE_RULES = [
+  {
+    sourceTag: "type:api",
+    onlyDependOnLibsWithTags: ["type:application", "type:domain", "type:shared", "type:common"]
+  },
+  {
+    sourceTag: "type:controller",
+    onlyDependOnLibsWithTags: ["type:application", "type:domain", "type:shared", "type:common"]
+  },
+  {
+    sourceTag: "type:presentation",
+    onlyDependOnLibsWithTags: ["type:application", "type:domain", "type:shared", "type:common"]
+  },
+  {
+    sourceTag: "type:application",
+    onlyDependOnLibsWithTags: ["type:domain", "type:shared", "type:common"]
+  },
+  {
+    sourceTag: "type:service",
+    onlyDependOnLibsWithTags: ["type:domain", "type:shared", "type:common"]
+  },
+  {
+    sourceTag: "type:domain",
+    bannedDependenciesWithTags: [
+      "type:api",
+      "type:controller",
+      "type:presentation",
+      "type:application",
+      "type:service",
+      "type:infrastructure",
+      "type:infra",
+      "type:root",
+      "type:app"
+    ]
+  },
+  {
+    sourceTag: "type:infrastructure",
+    onlyDependOnLibsWithTags: ["type:domain", "type:shared", "type:common"]
+  },
+  {
+    sourceTag: "type:infra",
+    onlyDependOnLibsWithTags: ["type:domain", "type:shared", "type:common"]
+  }
+];
+var MODULE_BOUNDARY_PROFILES = {
+  "modular-monolith": {
+    name: "modular-monolith",
+    description: "Modular monolith / vertical slice preset (blocks cross-feature dependencies and limits root aggregation to feature/core/shared/domain)",
+    rules: MODULAR_MONOLITH_RULES
+  },
+  "feature-slices": {
+    name: "feature-slices",
+    description: "Vertical slice preset (alias for modular-monolith)",
+    rules: MODULAR_MONOLITH_RULES
+  },
+  "vertical-slices": {
+    name: "vertical-slices",
+    description: "Vertical slice architecture preset (alias for modular-monolith)",
+    rules: MODULAR_MONOLITH_RULES
+  },
+  "angular-enterprise": {
+    name: "angular-enterprise",
+    description: "Angular / Nx enterprise monorepo preset (enforces one-way layering across feature, UI, data-access, util, shared, and root modules)",
+    rules: ANGULAR_ENTERPRISE_RULES
+  },
+  angular: {
+    name: "angular",
+    description: "Angular enterprise layering preset (alias for angular-enterprise)",
+    rules: ANGULAR_ENTERPRISE_RULES
+  },
+  "clean-architecture": {
+    name: "clean-architecture",
+    description: "Clean Architecture / DDD layering preset (API/presentation -> application -> domain <- infrastructure)",
+    rules: CLEAN_ARCHITECTURE_RULES
+  },
+  "domain-driven": {
+    name: "domain-driven",
+    description: "DDD layering preset (alias for clean-architecture)",
+    rules: CLEAN_ARCHITECTURE_RULES
+  }
+};
+function getModuleBoundaryProfile(name) {
+  const profile = MODULE_BOUNDARY_PROFILES[name];
+  if (!profile) {
+    throw new Error(`Unknown module boundary preset: '${name}'. Supported presets: ${Object.keys(MODULE_BOUNDARY_PROFILES).join(", ")}`);
+  }
+  return {
+    ...profile,
+    rules: profile.rules.map((rule) => ({
+      ...rule,
+      onlyDependOnLibsWithTags: rule.onlyDependOnLibsWithTags ? [...rule.onlyDependOnLibsWithTags] : undefined,
+      bannedDependenciesWithTags: rule.bannedDependenciesWithTags ? [...rule.bannedDependenciesWithTags] : undefined
+    }))
+  };
+}
+function getModuleBoundaryPreset(name) {
+  return getModuleBoundaryProfile(name).rules;
+}
+function resolveModuleBoundaries(options) {
+  if (!options)
+    return;
+  const { preset, rules } = options;
+  if (!preset && !rules)
+    return;
+  const presetRules = preset ? getModuleBoundaryPreset(preset) : [];
+  const customRules = rules ?? [];
+  const merged = [...presetRules, ...customRules];
+  return merged.length > 0 ? merged : undefined;
+}
+
 // src/validate.ts
 var SCOPE_LIFETIME_RANK = {
   application: 0,
@@ -1016,8 +1192,24 @@ var SCOPE_LIFETIME_RANK = {
 };
 function validateGraph(graph, options = false) {
   const strict = typeof options === "boolean" ? options : options.strict ?? false;
-  const moduleBoundaries = typeof options === "object" ? options.moduleBoundaries : undefined;
   const diagnostics = [];
+  let moduleBoundaries;
+  if (typeof options === "object") {
+    try {
+      moduleBoundaries = resolveModuleBoundaries({
+        preset: options.moduleBoundaryPreset,
+        rules: options.moduleBoundaries
+      });
+    } catch (err) {
+      diagnostics.push({
+        severity: "error",
+        code: "invalid-boundary-preset",
+        message: err instanceof Error ? err.message : String(err),
+        file: graph.modules[0]?.file,
+        line: graph.modules[0]?.line
+      });
+    }
+  }
   const globalProviders = new Map;
   for (const module of graph.modules) {
     for (const provider of module.providers) {
@@ -1079,6 +1271,17 @@ function validateGraph(graph, options = false) {
         if (route.command && !module.commands.some((command) => command.className === route.command)) {
           error("route-command-unresolved", `路由 ${key} 绑定的 command 类 ${route.command} 未在模块 ${module.name} 声明`, controller.file);
         }
+        if (typeof options === "object" && options.allowRouteCommandBindings === false && route.command) {
+          error("route-command-binding-disallowed", `Route ${key} binds command ${route.command}, but route-level command bindings are disabled by policy. Use an application service (${controller.className}.${route.handler}, ${controller.file}).`, controller.file);
+        }
+      }
+      if (typeof options === "object" && options.disallowControllerDirectDb) {
+        for (const dep of controller.deps) {
+          const isDbClient = dep === "DB_CLIENT" || dep === "DatabaseClient" || graph.tokenNames?.[dep] === "supacloud.db-client";
+          if (isDbClient) {
+            error("controller-direct-db-access", `Controller ${controller.className} directly injects database client '${dep}', violating presentation layer separation (${controller.file})`, controller.file);
+          }
+        }
       }
     }
   }
@@ -1115,6 +1318,26 @@ function validateGraph(graph, options = false) {
       if (!command.permission) {
         error("command-missing-permission", `模块 ${module.name} 的 command ${command.name} (${command.className}) 未声明 permission`, module.file, module.line);
       }
+      if (typeof options === "object" && options.commandCapabilities) {
+        const caps = options.commandCapabilities;
+        const location = `${command.className} (${module.file})`;
+        if (command.permission && caps.permission === false) {
+          error("command-permission-unsupported", `Command ${command.name} declares permission, but runtime permission checks are unavailable (${location}).`, module.file, module.line);
+        }
+        if (command.audit && caps.audit === false) {
+          error("command-audit-unsupported", `Command ${command.name} declares audit, but audit persistence is unavailable (${location}).`, module.file, module.line);
+        }
+        if (command.idempotency === "required" && caps.idempotency === false) {
+          error("command-idempotency-unsupported", `Command ${command.name} declares idempotency, but idempotency receipt persistence is unavailable (${location}).`, module.file, module.line);
+        }
+        if (command.transaction === "required") {
+          if (caps.transaction === "rpc-only") {
+            warn2("command-transaction-rpc-only", `Command ${command.name} declares transaction: 'required', but only DB RPC transactions are available; multi-table writes must use one DB RPC (${location}).`, module.file, module.line);
+          } else if (caps.transaction === false) {
+            error("command-transaction-unsupported", `Command ${command.name} declares transaction: 'required', but transaction support is unavailable (${location}).`, module.file, module.line);
+          }
+        }
+      }
     }
   }
   if (moduleBoundaries && moduleBoundaries.length > 0) {
@@ -1147,6 +1370,10 @@ function validateGraph(graph, options = false) {
     }
   }
   diagnostics.push(...detectCycles(graph, resolveDep));
+  diagnostics.push(...detectModuleCycles(graph));
+  if (typeof options === "object" && options.detectOrphanModules) {
+    diagnostics.push(...detectOrphanModules(graph));
+  }
   return diagnostics;
 }
 function joinRoutePaths(prefix, path) {
@@ -1196,15 +1423,102 @@ function detectCycles(graph, resolveDep) {
     visit(ref);
   return diagnostics;
 }
+function detectModuleCycles(graph) {
+  const diagnostics = [];
+  const moduleMap = new Map(graph.modules.map((m) => [m.name, m]));
+  const state = new Map;
+  const stack = [];
+  const reported = new Set;
+  const visit = (name) => {
+    if (state.get(name) === "done")
+      return;
+    if (state.get(name) === "visiting") {
+      const cycleStart = stack.indexOf(name);
+      const cycle = [...stack.slice(cycleStart), name];
+      const cycleKey = [...cycle].sort().join("|");
+      if (!reported.has(cycleKey)) {
+        reported.add(cycleKey);
+        const mod2 = moduleMap.get(name);
+        diagnostics.push({
+          severity: "error",
+          code: "circular-module-import",
+          message: `Module circular import detected: ${cycle.join(" -> ")}`,
+          file: mod2?.file,
+          line: mod2?.line
+        });
+      }
+      return;
+    }
+    state.set(name, "visiting");
+    stack.push(name);
+    const mod = moduleMap.get(name);
+    if (mod) {
+      for (const importName of mod.imports) {
+        if (moduleMap.has(importName)) {
+          visit(importName);
+        }
+      }
+    }
+    stack.pop();
+    state.set(name, "done");
+  };
+  for (const mod of graph.modules) {
+    visit(mod.name);
+  }
+  return diagnostics;
+}
+function detectOrphanModules(graph) {
+  const diagnostics = [];
+  const rootModules = graph.modules.filter((m) => m.tags && (m.tags.includes("type:root") || m.tags.includes("type:app")) || m.name === "app" || m.name === "root");
+  if (rootModules.length === 0)
+    return diagnostics;
+  const reachable = new Set;
+  const moduleMap = new Map(graph.modules.map((m) => [m.name, m]));
+  const queue = rootModules.map((m) => m.name);
+  for (const root of rootModules) {
+    reachable.add(root.name);
+  }
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const mod = moduleMap.get(current);
+    if (!mod)
+      continue;
+    for (const imp of mod.imports) {
+      if (!reachable.has(imp)) {
+        reachable.add(imp);
+        queue.push(imp);
+      }
+    }
+  }
+  for (const mod of graph.modules) {
+    if (!reachable.has(mod.name)) {
+      diagnostics.push({
+        severity: "warn",
+        code: "orphan-module",
+        message: `Module '${mod.name}' is declared but not reachable from any root module (${rootModules.map((r) => r.name).join(", ")})`,
+        file: mod.file,
+        line: mod.line
+      });
+    }
+  }
+  return diagnostics;
+}
 
 // src/compile.ts
+import { existsSync as existsSync2, readFileSync } from "node:fs";
+import { join as join3 } from "node:path";
 async function compileProject(options) {
   const graph = await analyzeProject(options.rootDir, options.include);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, {
       strict: options.strict,
-      moduleBoundaries: options.moduleBoundaries
+      moduleBoundaryPreset: options.moduleBoundaryPreset,
+      moduleBoundaries: options.moduleBoundaries,
+      allowRouteCommandBindings: options.allowRouteCommandBindings,
+      commandCapabilities: options.commandCapabilities,
+      disallowControllerDirectDb: options.disallowControllerDirectDb,
+      detectOrphanModules: options.detectOrphanModules
     })
   ];
   if (options.strict) {
@@ -1219,10 +1533,66 @@ async function compileProject(options) {
   });
   return { diagnostics, graph, written };
 }
+async function checkProject(options) {
+  const graph = await analyzeProject(options.rootDir, options.include);
+  const diagnostics = [
+    ...graph.diagnostics ?? [],
+    ...validateGraph(graph, {
+      strict: options.strict,
+      moduleBoundaryPreset: options.moduleBoundaryPreset,
+      moduleBoundaries: options.moduleBoundaries,
+      allowRouteCommandBindings: options.allowRouteCommandBindings,
+      commandCapabilities: options.commandCapabilities,
+      disallowControllerDirectDb: options.disallowControllerDirectDb,
+      detectOrphanModules: options.detectOrphanModules
+    })
+  ];
+  if (options.strict) {
+    for (const diagnostic of diagnostics) {
+      if (diagnostic.severity === "warn")
+        diagnostic.severity = "error";
+    }
+  }
+  const rendered = renderApplication(graph, {
+    rootDir: options.rootDir,
+    outDir: options.outDir
+  });
+  const expectedFiles = {
+    "application.ts": rendered.applicationCode,
+    "app.manifest.json": rendered.manifestJson
+  };
+  const mismatches = [];
+  for (const [filename, expectedContent] of Object.entries(expectedFiles)) {
+    const diskPath = join3(options.outDir, filename);
+    if (!existsSync2(diskPath)) {
+      mismatches.push(`${filename}: generated artifact is missing from disk`);
+      continue;
+    }
+    const diskContent = readFileSync(diskPath, "utf8");
+    if (diskContent !== expectedContent) {
+      mismatches.push(`${filename}: disk artifact differs from current compiler output`);
+    }
+  }
+  return {
+    upToDate: mismatches.length === 0,
+    mismatches,
+    diagnostics,
+    graph
+  };
+}
 export {
+  ANGULAR_ENTERPRISE_RULES,
+  CLEAN_ARCHITECTURE_RULES,
+  MODULAR_MONOLITH_RULES,
+  MODULE_BOUNDARY_PROFILES,
   analyzeProject,
   camelName,
+  checkProject,
   compileProject,
   generateApplication,
+  getModuleBoundaryPreset,
+  getModuleBoundaryProfile,
+  renderApplication,
+  resolveModuleBoundaries,
   validateGraph
 };

package/dist/profiles.d.ts

@@ -0,0 +1,36 @@
+import type { ModuleBoundaryPresetName, ModuleBoundaryProfile, ModuleBoundaryRule } from "./types";
+/**
+ * Modular monolith / vertical slice architecture rules:
+ * - type:feature slices cannot depend on one another or on root/app modules;
+ * - type:root / type:app entry modules may aggregate feature, core, shared, and domain modules;
+ * - type:core foundational modules cannot depend upward on feature or root/app modules;
+ * - type:shared common utilities/components cannot depend on feature or root/app modules.
+ */
+export declare const MODULAR_MONOLITH_RULES: ModuleBoundaryRule[];
+/**
+ * Angular / Nx enterprise monorepo layering rules:
+ * follows the recommended Nx / Angular enterprise workspace conventions:
+ * - feature slices cannot directly depend on one another;
+ * - ui / data-access / util / shared libraries cannot depend upward on feature or root modules;
+ * - root / app modules serve only as composition entry points.
+ */
+export declare const ANGULAR_ENTERPRISE_RULES: ModuleBoundaryRule[];
+/**
+ * Clean Architecture / DDD layering rules (similar to Spring Boot DDD conventions):
+ * - presentation layers (api/controller/presentation) may depend only on application, domain, and shared layers;
+ * - application layers (application/service) orchestrate use cases and depend only on domain and shared layers;
+ * - the domain layer remains pure and cannot depend on presentation, application, infrastructure, or root modules;
+ * - infrastructure layers (infrastructure/infra) implement domain ports and may depend only on domain and shared layers.
+ */
+export declare const CLEAN_ARCHITECTURE_RULES: ModuleBoundaryRule[];
+/** Registry of built-in module boundary profiles. */
+export declare const MODULE_BOUNDARY_PROFILES: Record<ModuleBoundaryPresetName, ModuleBoundaryProfile>;
+/** Return the architecture governance rules for a preset name. */
+export declare function getModuleBoundaryProfile(name: ModuleBoundaryPresetName): ModuleBoundaryProfile;
+/** Return a copy of the rules included in a preset. */
+export declare function getModuleBoundaryPreset(name: ModuleBoundaryPresetName): ModuleBoundaryRule[];
+/** Resolve and merge preset rules with optional user-defined rules. */
+export declare function resolveModuleBoundaries(options?: {
+    preset?: ModuleBoundaryPresetName;
+    rules?: ModuleBoundaryRule[];
+}): ModuleBoundaryRule[] | undefined;