@supacloud/compiler 0.6.2 → 0.8.0

package/README.md

@@ -10,6 +10,54 @@ SupaCloud 应用静态编译器：读取 `@supacloud/app` 装饰器元数据的
 bun add @supacloud/compiler
 ```
 
+## 零配置项目
+
+在项目根目录执行：
+
+```bash
+bunx supacloud-compiler compile
+bunx supacloud-compiler dev
+```
+
+默认约定如下：
+
+| 配置 | 默认值 |
+| --- | --- |
+| 源码目录 | `src` |
+| 生成目录 | `generated` |
+| 文件发现 | `**/*.module.ts`、`**/*.ts` |
+| strict 类型安全门 | 开启 |
+| typed client | 开启 |
+| permissions manifest | 开启 |
+| module boundary preset | `modular-monolith` |
+| provider tree-shaking | 开启 |
+
+需要覆盖默认值时，在项目根目录添加 `supacloud.config.ts`：
+
+```ts
+import { defineSupacloudConfig } from "@supacloud/compiler";
+
+export default defineSupacloudConfig({
+  root: "src",
+  outDir: "generated",
+  strict: true,
+  generateClient: true,
+  generatePermissions: true,
+  moduleBoundaryPreset: "modular-monolith",
+  commandCapabilities: {
+    permission: true,
+    audit: true,
+    idempotency: true,
+    transaction: true,
+  },
+});
+```
+
+命令行参数优先级高于配置文件。`--no-strict`、`--no-client` 和
+`--no-permissions` 只建议用于本地迁移或调试；生产 CI 应保留默认 strict。
+`commandCapabilities` 用于声明运行时实际支持的命令治理能力；命令声明了
+`permission`、`audit` 或 `idempotency` 时，若对应能力关闭，编译器会失败。
+
 ## API
 
 ```ts

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { resolve as resolve5 } from "node:path";
+import { resolve as resolve6 } from "node:path";
 
 // src/analyze.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -5084,6 +5084,69 @@ function watchProject(options) {
   };
 }
 
+// src/config.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6, resolve as resolve5 } from "node:path";
+import { pathToFileURL } from "node:url";
+var DEFAULT_SUPACLOUD_CONFIG = {
+  root: "src",
+  outDir: "generated",
+  include: ["**/*.module.ts", "**/*.ts"],
+  strict: true,
+  generateClient: true,
+  generatePermissions: true,
+  treeShakeUnusedProviders: true,
+  moduleBoundaryPreset: "modular-monolith"
+};
+function defineSupacloudConfig(config = {}) {
+  return {
+    ...DEFAULT_SUPACLOUD_CONFIG,
+    ...config,
+    include: config.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include]
+  };
+}
+function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
+  const resolved = defineSupacloudConfig(config);
+  return {
+    rootDir: resolve5(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
+    outDir: resolve5(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
+    include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
+    strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
+    generateClient: resolved.generateClient ?? DEFAULT_SUPACLOUD_CONFIG.generateClient,
+    generatePermissions: resolved.generatePermissions ?? DEFAULT_SUPACLOUD_CONFIG.generatePermissions,
+    moduleBoundaryPreset: resolved.moduleBoundaryPreset ?? DEFAULT_SUPACLOUD_CONFIG.moduleBoundaryPreset,
+    commandCapabilities: resolved.commandCapabilities,
+    treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders
+  };
+}
+async function loadSupacloudConfig(cwd = process.cwd()) {
+  const candidates = [
+    join6(cwd, "supacloud.config.ts"),
+    join6(cwd, "supacloud.config.mts"),
+    join6(cwd, "supacloud.config.js"),
+    join6(cwd, "supacloud.config.mjs")
+  ];
+  const configPath = candidates.find((candidate) => existsSync5(candidate));
+  if (!configPath)
+    return defineSupacloudConfig();
+  const imported = await import(pathToFileURL(configPath).href);
+  return defineSupacloudConfig(imported.default ?? {});
+}
+function compileOptionsFromConfig(config, cwd = process.cwd()) {
+  const resolved = resolveSupacloudConfig(config, cwd);
+  return {
+    rootDir: resolved.rootDir,
+    outDir: resolved.outDir,
+    include: resolved.include,
+    strict: resolved.strict,
+    generateClient: resolved.generateClient,
+    generatePermissions: resolved.generatePermissions,
+    moduleBoundaryPreset: resolved.moduleBoundaryPreset,
+    commandCapabilities: resolved.commandCapabilities,
+    treeShakeUnusedProviders: resolved.treeShakeUnusedProviders
+  };
+}
+
 // src/cli.ts
 function isModuleBoundaryPresetName(value) {
   return value === "modular-monolith" || value === "feature-slices" || value === "vertical-slices" || value === "angular-enterprise" || value === "angular" || value === "clean-architecture" || value === "domain-driven";
@@ -5109,11 +5172,14 @@ Commands:
   doctor              Run project and generated-artifact health checks
 
 Options:
-  --root, -r <dir>    Application source root (default: current directory or first positional argument)
-  --out, -o <dir>     Artifact output directory (default: <rootDir>/generated)
-  --strict            Enable type-safety gates and treat all warnings as errors
-  --client            Generate typed API client in client.ts
-  --permissions       Generate typed permissions registry in permissions.ts
+  --root, -r <dir>    Application source root (default: ./src, or first positional argument)
+  --out, -o <dir>     Artifact output directory (default: ./generated)
+  --strict            Enable type-safety gates and treat all warnings as errors (default)
+  --no-strict         Disable strict diagnostics (local migration escape hatch)
+  --client            Generate typed API client in client.ts (default)
+  --no-client         Do not generate client.ts
+  --permissions       Generate typed permissions registry (default)
+  --no-permissions    Do not generate permissions.ts
   --debounce <ms>     Debounce source changes in dev mode (default: 100)
   --json              Print machine-readable output for graph/explain/doctor
   --preset, -p <name> Architecture preset ('modular-monolith' | 'angular-enterprise' | 'clean-architecture')
@@ -5132,11 +5198,11 @@ async function run() {
     printUsage();
     process.exit(1);
   }
-  let rootDir = ".";
+  let rootDir;
   let outDir;
-  let strict = false;
-  let generateClient = false;
-  let generatePermissions = false;
+  let strict;
+  let generateClient;
+  let generatePermissions;
   let preset;
   let debounceMs = 100;
   let query;
@@ -5149,10 +5215,16 @@ async function run() {
       outDir = args[++i];
     } else if (arg === "--strict") {
       strict = true;
+    } else if (arg === "--no-strict") {
+      strict = false;
     } else if (arg === "--client") {
       generateClient = true;
+    } else if (arg === "--no-client") {
+      generateClient = false;
     } else if (arg === "--permissions") {
       generatePermissions = true;
+    } else if (arg === "--no-permissions") {
+      generatePermissions = false;
     } else if (arg === "--debounce") {
       debounceMs = Number(args[++i]);
       if (!Number.isFinite(debounceMs) || debounceMs < 0) {
@@ -5168,7 +5240,7 @@ async function run() {
         process.exit(1);
       }
       preset = presetArg;
-    } else if (!arg.startsWith("-") && rootDir === ".") {
+    } else if (!arg.startsWith("-") && !rootDir) {
       if (command === "explain" && !query)
         query = arg;
       else
@@ -5177,17 +5249,24 @@ async function run() {
       query = arg;
     }
   }
-  const resolvedRoot = resolve5(process.cwd(), rootDir);
-  const resolvedOut = outDir ? resolve5(process.cwd(), outDir) : resolve5(resolvedRoot, "generated");
+  const loadedConfig = await loadSupacloudConfig(process.cwd());
+  const defaults = resolveSupacloudConfig(loadedConfig, process.cwd());
+  const resolvedRoot = rootDir ? resolve6(process.cwd(), rootDir) : defaults.rootDir;
+  const resolvedOut = outDir ? resolve6(process.cwd(), outDir) : defaults.outDir;
+  const configured = compileOptionsFromConfig({
+    ...loadedConfig,
+    root: resolvedRoot,
+    outDir: resolvedOut,
+    strict: strict ?? loadedConfig.strict,
+    generateClient: generateClient ?? loadedConfig.generateClient,
+    generatePermissions: generatePermissions ?? loadedConfig.generatePermissions
+  }, process.cwd());
+  const compileDefaults = {
+    ...configured,
+    moduleBoundaryPreset: preset ?? configured.moduleBoundaryPreset
+  };
   if (command === "compile") {
-    const result = await compileProject({
-      rootDir: resolvedRoot,
-      outDir: resolvedOut,
-      strict,
-      moduleBoundaryPreset: preset,
-      generateClient,
-      generatePermissions
-    });
+    const result = await compileProject(compileDefaults);
     printDiagnostics(result.diagnostics);
     const errors = result.diagnostics.filter((d) => d.severity === "error");
     if (errors.length > 0) {
@@ -5200,14 +5279,7 @@ Compilation succeeded. Generated artifacts:
 ${result.written.map((f) => `  - ${f}`).join(`
 `)}`);
   } else if (command === "check") {
-    const result = await checkProject({
-      rootDir: resolvedRoot,
-      outDir: resolvedOut,
-      strict,
-      moduleBoundaryPreset: preset,
-      generateClient,
-      generatePermissions
-    });
+    const result = await checkProject(compileDefaults);
     printDiagnostics(result.diagnostics);
     const errors = result.diagnostics.filter((d) => d.severity === "error");
     if (errors.length > 0) {
@@ -5227,13 +5299,8 @@ Artifact drift detected:`);
     console.log("Artifact check passed: disk files match compiler output with no drift.");
   } else if (command === "dev") {
     const handle = watchProject({
-      rootDir: resolvedRoot,
-      outDir: resolvedOut,
-      strict,
-      moduleBoundaryPreset: preset,
+      ...compileDefaults,
       debounceMs,
-      generateClient,
-      generatePermissions,
       onEvent: (event) => {
         if (event.type === "compile-start") {
           console.log(event.initial ? `
@@ -5284,12 +5351,7 @@ Source change detected; compiling...`);
       process.exit(1);
     }
   } else {
-    const result = await checkProject({
-      rootDir: resolvedRoot,
-      outDir: resolvedOut,
-      strict,
-      moduleBoundaryPreset: preset
-    });
+    const result = await checkProject(compileDefaults);
     const doctor = doctorProject(resolvedRoot, resolvedOut, result.graph, result.upToDate, result.diagnostics);
     if (json) {
       console.log(JSON.stringify(doctor, null, 2));

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+import type { CommandExecutionCapabilities, CompileOptions, ModuleBoundaryPresetName } from "./types";
+export interface SupaCloudConfig {
+    root?: string;
+    outDir?: string;
+    include?: string[];
+    strict?: boolean;
+    generateClient?: boolean;
+    generatePermissions?: boolean;
+    moduleBoundaryPreset?: ModuleBoundaryPresetName;
+    commandCapabilities?: CommandExecutionCapabilities;
+    treeShakeUnusedProviders?: boolean;
+}
+export declare const DEFAULT_SUPACLOUD_CONFIG: Required<Omit<SupaCloudConfig, "include" | "moduleBoundaryPreset" | "commandCapabilities">> & {
+    include: string[];
+    moduleBoundaryPreset: ModuleBoundaryPresetName;
+};
+export declare function defineSupacloudConfig(config?: SupaCloudConfig): SupaCloudConfig;
+export declare function resolveSupacloudConfig(config?: SupaCloudConfig, cwd?: string): {
+    rootDir: string;
+    outDir: string;
+    include: string[];
+    strict: boolean;
+    generateClient: boolean;
+    generatePermissions: boolean;
+    moduleBoundaryPreset: ModuleBoundaryPresetName;
+    commandCapabilities?: CommandExecutionCapabilities;
+    treeShakeUnusedProviders: boolean;
+};
+export declare function loadSupacloudConfig(cwd?: string): Promise<SupaCloudConfig>;
+export declare function compileOptionsFromConfig(config: SupaCloudConfig, cwd?: string): CompileOptions;

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export type { DoctorResult } from "./inspect";
 export { validateGraph, COMPILER_DIAGNOSTIC_CODES } from "./validate";
 export { scanGeneratedArtifacts, scanProductionSource } from "./type-safety";
 export type { TypeSafetyScanOptions } from "./type-safety";
+export { DEFAULT_SUPACLOUD_CONFIG, compileOptionsFromConfig, defineSupacloudConfig, loadSupacloudConfig, resolveSupacloudConfig, } from "./config";
+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, ModuleBoundaryPresetName, ModuleBoundaryProfile, ModuleBoundaryRule, ModuleNode, JobNode, ProviderKind, ProviderNode, QueryNode, RouteNode, Scope, TokenKind, TypeSafetyOptions, ValidateOptions, WatchEvent, WatchHandle, WatchOptions, } from "./types";

package/dist/index.js

@@ -5075,10 +5075,73 @@ function exportGraphDot(graph) {
   return lines.join(`
 `);
 }
+// src/config.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6, resolve as resolve5 } from "node:path";
+import { pathToFileURL } from "node:url";
+var DEFAULT_SUPACLOUD_CONFIG = {
+  root: "src",
+  outDir: "generated",
+  include: ["**/*.module.ts", "**/*.ts"],
+  strict: true,
+  generateClient: true,
+  generatePermissions: true,
+  treeShakeUnusedProviders: true,
+  moduleBoundaryPreset: "modular-monolith"
+};
+function defineSupacloudConfig(config = {}) {
+  return {
+    ...DEFAULT_SUPACLOUD_CONFIG,
+    ...config,
+    include: config.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include]
+  };
+}
+function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
+  const resolved = defineSupacloudConfig(config);
+  return {
+    rootDir: resolve5(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
+    outDir: resolve5(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
+    include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
+    strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
+    generateClient: resolved.generateClient ?? DEFAULT_SUPACLOUD_CONFIG.generateClient,
+    generatePermissions: resolved.generatePermissions ?? DEFAULT_SUPACLOUD_CONFIG.generatePermissions,
+    moduleBoundaryPreset: resolved.moduleBoundaryPreset ?? DEFAULT_SUPACLOUD_CONFIG.moduleBoundaryPreset,
+    commandCapabilities: resolved.commandCapabilities,
+    treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders
+  };
+}
+async function loadSupacloudConfig(cwd = process.cwd()) {
+  const candidates = [
+    join6(cwd, "supacloud.config.ts"),
+    join6(cwd, "supacloud.config.mts"),
+    join6(cwd, "supacloud.config.js"),
+    join6(cwd, "supacloud.config.mjs")
+  ];
+  const configPath = candidates.find((candidate) => existsSync5(candidate));
+  if (!configPath)
+    return defineSupacloudConfig();
+  const imported = await import(pathToFileURL(configPath).href);
+  return defineSupacloudConfig(imported.default ?? {});
+}
+function compileOptionsFromConfig(config, cwd = process.cwd()) {
+  const resolved = resolveSupacloudConfig(config, cwd);
+  return {
+    rootDir: resolved.rootDir,
+    outDir: resolved.outDir,
+    include: resolved.include,
+    strict: resolved.strict,
+    generateClient: resolved.generateClient,
+    generatePermissions: resolved.generatePermissions,
+    moduleBoundaryPreset: resolved.moduleBoundaryPreset,
+    commandCapabilities: resolved.commandCapabilities,
+    treeShakeUnusedProviders: resolved.treeShakeUnusedProviders
+  };
+}
 export {
   ANGULAR_ENTERPRISE_RULES,
   CLEAN_ARCHITECTURE_RULES,
   COMPILER_DIAGNOSTIC_CODES,
+  DEFAULT_SUPACLOUD_CONFIG,
   MODULAR_MONOLITH_RULES,
   MODULE_BOUNDARY_PROFILES,
   ModuleDependencyGraph,
@@ -5086,11 +5149,13 @@ export {
   analyzeProject,
   camelName,
   checkProject,
+  compileOptionsFromConfig,
   compileProject,
   compileTraits,
   createDependencyGraphCache,
   createIncrementalCompiler,
   createIncrementalProgramSession,
+  defineSupacloudConfig,
   doctorProject,
   explainGraph,
   exportGraphDot,
@@ -5099,8 +5164,10 @@ export {
   generateApplication,
   getModuleBoundaryPreset,
   getModuleBoundaryProfile,
+  loadSupacloudConfig,
   renderApplication,
   resolveModuleBoundaries,
+  resolveSupacloudConfig,
   scanGeneratedArtifacts,
   scanProductionSource,
   validateGraph,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.6.2",
+  "version": "0.8.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",