@supacloud/compiler 0.3.1 → 0.4.1

package/dist/cli.js

@@ -0,0 +1,1698 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { resolve } from "node:path";
+
+// src/analyze.ts
+import { existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import {
+  Node,
+  Project,
+  SyntaxKind
+} from "ts-morph";
+var DEFAULT_INCLUDE = ["**/*.module.ts", "**/*.ts"];
+var ROUTE_DECORATORS = {
+  Get: "GET",
+  Post: "POST",
+  Put: "PUT",
+  Patch: "PATCH",
+  Delete: "DELETE",
+  Head: "HEAD",
+  Options: "OPTIONS"
+};
+var SCOPES = ["application", "request", "job"];
+async function analyzeProject(rootDir, include) {
+  const project = createProject(rootDir);
+  const patterns = (include ?? DEFAULT_INCLUDE).map((glob) => join(rootDir, glob));
+  project.addSourceFilesAtPaths(patterns);
+  const sourceFiles = project.getSourceFiles().filter((sf) => !sf.getFilePath().includes("node_modules") && !sf.isDeclarationFile()).sort((a, b) => a.getFilePath().localeCompare(b.getFilePath()));
+  const ctx = {
+    rootDir,
+    tokensByName: new Map,
+    classesByName: new Map,
+    diagnostics: []
+  };
+  for (const sf of sourceFiles) {
+    indexFile(sf, ctx);
+  }
+  const candidates = [];
+  for (const sf of sourceFiles) {
+    for (const cls of sf.getClasses()) {
+      const moduleDec = findDecorator(cls, "Module");
+      if (!moduleDec)
+        continue;
+      const options = decoratorObjectArg(moduleDec);
+      if (!options)
+        continue;
+      candidates.push({
+        node: cls,
+        options,
+        className: cls.getName() ?? "<anonymous>",
+        file: sf.getFilePath(),
+        line: cls.getStartLineNumber()
+      });
+    }
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      if (call.getExpression().getText() !== "defineModule")
+        continue;
+      const parent = call.getParent();
+      if (!parent || !Node.isVariableDeclaration(parent))
+        continue;
+      const arg = call.getArguments()[0];
+      if (!arg || !Node.isObjectLiteralExpression(arg))
+        continue;
+      candidates.push({
+        node: parent,
+        options: arg,
+        className: parent.getName(),
+        file: sf.getFilePath(),
+        line: parent.getStartLineNumber()
+      });
+    }
+  }
+  const nameByNode = new Map;
+  for (const c of candidates) {
+    nameByNode.set(c.node, stringLiteralProp(c.options, "name") ?? c.className);
+  }
+  const modules = candidates.map((c) => parseModule(c, nameByNode, ctx));
+  const providedTokens = new Set(modules.flatMap((m) => m.providers.map((p) => p.token)));
+  const referenced = new Set;
+  for (const m of modules) {
+    for (const p of m.providers)
+      p.deps.forEach((d) => referenced.add(d));
+    for (const c of m.controllers)
+      c.deps.forEach((d) => referenced.add(d));
+  }
+  const externalTokens = [...referenced].filter((token) => !providedTokens.has(token)).sort();
+  const tokenNames = {};
+  for (const info of ctx.tokensByName.values()) {
+    if (info.stringName)
+      tokenNames[info.name] = info.stringName;
+  }
+  return {
+    modules,
+    externalTokens,
+    diagnostics: ctx.diagnostics,
+    tokenNames
+  };
+}
+function createProject(rootDir) {
+  const tsConfigFilePath = join(rootDir, "tsconfig.json");
+  if (existsSync(tsConfigFilePath)) {
+    return new Project({ tsConfigFilePath, skipAddingFilesFromTsConfig: true });
+  }
+  return new Project({
+    compilerOptions: { experimentalDecorators: true, allowJs: false }
+  });
+}
+function indexFile(sf, ctx) {
+  for (const cls of sf.getClasses()) {
+    const name = cls.getName();
+    if (name && !ctx.classesByName.has(name)) {
+      ctx.classesByName.set(name, { name, decl: cls, file: sf.getFilePath() });
+    }
+  }
+  for (const statement of sf.getVariableStatements()) {
+    for (const decl of statement.getDeclarations()) {
+      const info = parseTokenVariable(decl, sf.getFilePath());
+      if (info && !ctx.tokensByName.has(info.name)) {
+        ctx.tokensByName.set(info.name, info);
+      }
+    }
+  }
+}
+function parseTokenVariable(decl, file) {
+  const init = decl.getInitializer();
+  if (!init || !Node.isNewExpression(init))
+    return;
+  if (init.getExpression().getText() !== "InjectionToken")
+    return;
+  const [nameArg, optionsArg] = init.getArguments();
+  const info = { name: decl.getName(), file };
+  if (nameArg && Node.isStringLiteral(nameArg)) {
+    info.stringName = nameArg.getLiteralText();
+  }
+  if (optionsArg && Node.isObjectLiteralExpression(optionsArg)) {
+    const scope = stringLiteralProp(optionsArg, "scope");
+    if (scope && SCOPES.includes(scope)) {
+      info.scope = scope;
+    }
+  }
+  return info;
+}
+function parseModule(candidate, nameByNode, ctx) {
+  const { options, className, file, line } = candidate;
+  const name = nameByNode.get(candidate.node) ?? className;
+  const tags = arrayProp(options, "tags").map((el) => Node.isStringLiteral(el) ? el.getLiteralText() : el.getText().replace(/['"]/g, "")).filter(Boolean);
+  const imports = arrayProp(options, "imports").map((el) => {
+    const decl = Node.isIdentifier(el) ? resolveDeclaration(el)[0] : undefined;
+    if (decl) {
+      const known = nameByNode.get(decl);
+      if (known)
+        return known;
+      if (Node.isClassDeclaration(decl)) {
+        const dec = findDecorator(decl, "Module");
+        const decOptions = dec && decoratorObjectArg(dec);
+        const decName = decOptions && stringLiteralProp(decOptions, "name");
+        return decName ?? decl.getName() ?? el.getText();
+      }
+      if (Node.isVariableDeclaration(decl))
+        return decl.getName();
+    }
+    return el.getText();
+  }).filter((v, i, arr) => arr.indexOf(v) === i);
+  const exports = arrayProp(options, "exports").map((el) => tokenNameOf(el, ctx).name);
+  const exportsSet = new Set(exports);
+  const providers = [];
+  for (const el of arrayProp(options, "providers")) {
+    const provider = parseProvider(el, exportsSet, ctx);
+    if (provider)
+      providers.push(provider);
+  }
+  const controllers = [];
+  for (const el of arrayProp(options, "controllers")) {
+    const controller = parseController(el, ctx);
+    if (controller)
+      controllers.push(controller);
+  }
+  const handlerClasses = [];
+  const seenHandlers = new Set;
+  const collectHandler = (expr) => {
+    if (!Node.isIdentifier(expr))
+      return;
+    const decl = resolveDeclaration(expr)[0];
+    if (decl && Node.isClassDeclaration(decl) && !seenHandlers.has(decl.getName() ?? "")) {
+      seenHandlers.add(decl.getName() ?? "");
+      handlerClasses.push(decl);
+    }
+  };
+  for (const el of arrayProp(options, "providers")) {
+    if (Node.isIdentifier(el))
+      collectHandler(el);
+    if (Node.isObjectLiteralExpression(el)) {
+      const useClass = getProp(el, "useClass");
+      if (useClass)
+        collectHandler(useClass);
+    }
+  }
+  arrayProp(options, "commands").forEach(collectHandler);
+  arrayProp(options, "queries").forEach(collectHandler);
+  const commands = [];
+  const queries = [];
+  for (const cls of handlerClasses) {
+    const commandDec = findDecorator(cls, "Command");
+    if (commandDec) {
+      const meta = decoratorObjectArg(commandDec);
+      if (meta) {
+        commands.push({
+          className: cls.getName() ?? "<anonymous>",
+          name: stringLiteralProp(meta, "name") ?? cls.getName() ?? "<anonymous>",
+          permission: stringLiteralProp(meta, "permission"),
+          transaction: commandModeProp(meta, "transaction") ?? "none",
+          audit: stringLiteralProp(meta, "audit"),
+          idempotency: commandModeProp(meta, "idempotency") ?? "none"
+        });
+      }
+    }
+    const queryDec = findDecorator(cls, "Query");
+    if (queryDec) {
+      const meta = decoratorObjectArg(queryDec);
+      if (meta) {
+        queries.push({
+          className: cls.getName() ?? "<anonymous>",
+          name: stringLiteralProp(meta, "name") ?? cls.getName() ?? "<anonymous>"
+        });
+      }
+    }
+  }
+  return {
+    name,
+    className,
+    tags: tags.length > 0 ? tags : undefined,
+    file: sourcePath(ctx.rootDir, file),
+    line,
+    imports,
+    providers,
+    controllers,
+    commands,
+    queries,
+    exports
+  };
+}
+function commandModeProp(object, name) {
+  const value = stringLiteralProp(object, name);
+  return value === "required" || value === "none" ? value : undefined;
+}
+function parseProvider(el, exportsSet, ctx) {
+  const file = sourcePath(ctx.rootDir, el.getSourceFile().getFilePath());
+  const line = el.getStartLineNumber();
+  if (Node.isIdentifier(el)) {
+    const decl = resolveDeclaration(el)[0];
+    const cls = decl && Node.isClassDeclaration(decl) ? decl : undefined;
+    const className = cls?.getName() ?? el.getText();
+    const { deps, missing } = cls ? classDeps(cls, ctx) : { deps: [], missing: false };
+    if (missing) {
+      warn(ctx, "missing-deps", `provider ${className} 的部分构造依赖无法静态解析`, file, line);
+    }
+    return {
+      token: className,
+      tokenKind: "class",
+      kind: "class",
+      useClass: className,
+      scope: resolveScope({ cls, tokenName: className }, ctx),
+      deps,
+      exported: exportsSet.has(className),
+      file,
+      line,
+      importPath: cls ? modulePath(ctx.rootDir, cls.getSourceFile().getFilePath()) : undefined
+    };
+  }
+  if (!Node.isObjectLiteralExpression(el))
+    return;
+  const provideExpr = getProp(el, "provide");
+  if (!provideExpr)
+    return;
+  const { name: token, kind: tokenKind } = tokenNameOf(provideExpr, ctx);
+  const explicitScope = parseScopeProp(el);
+  const explicitDeps = arrayProp(el, "deps").map((d) => tokenNameOf(d, ctx).name);
+  const useClassExpr = getProp(el, "useClass");
+  const useValueExpr = getProp(el, "useValue");
+  const useFactoryExpr = getProp(el, "useFactory");
+  const useExistingExpr = getProp(el, "useExisting");
+  if (useClassExpr) {
+    const decl = Node.isIdentifier(useClassExpr) ? resolveDeclaration(useClassExpr)[0] : undefined;
+    const cls = decl && Node.isClassDeclaration(decl) ? decl : undefined;
+    const useClass = cls?.getName() ?? useClassExpr.getText();
+    let deps = explicitDeps;
+    if (deps.length === 0 && cls) {
+      const result = classDeps(cls, ctx);
+      deps = result.deps;
+      if (result.missing) {
+        warn(ctx, "missing-deps", `provider ${token} (useClass ${useClass}) 的部分构造依赖无法静态解析`, file, line);
+      }
+    }
+    return {
+      token,
+      tokenKind,
+      kind: "class",
+      useClass,
+      scope: resolveScope({ explicit: explicitScope, cls, tokenName: token }, ctx),
+      deps,
+      exported: exportsSet.has(token),
+      file,
+      line,
+      importPath: cls ? modulePath(ctx.rootDir, cls.getSourceFile().getFilePath()) : undefined
+    };
+  }
+  if (useValueExpr) {
+    return {
+      token,
+      tokenKind,
+      kind: "value",
+      useValueExpr: useValueExpr.getText(),
+      scope: resolveScope({ explicit: explicitScope, tokenName: token }, ctx),
+      deps: [],
+      exported: exportsSet.has(token),
+      file,
+      line,
+      importPath: Node.isIdentifier(useValueExpr) ? importPathOf(useValueExpr, ctx) : undefined
+    };
+  }
+  if (useFactoryExpr) {
+    const factoryName = Node.isIdentifier(useFactoryExpr) ? (() => {
+      const decl = resolveDeclaration(useFactoryExpr)[0];
+      return decl && (Node.isFunctionDeclaration(decl) || Node.isVariableDeclaration(decl)) ? decl.getName() ?? useFactoryExpr.getText() : useFactoryExpr.getText();
+    })() : useFactoryExpr.getText();
+    return {
+      token,
+      tokenKind,
+      kind: "factory",
+      useFactoryName: factoryName,
+      scope: resolveScope({ explicit: explicitScope, tokenName: token }, ctx),
+      deps: explicitDeps,
+      exported: exportsSet.has(token),
+      file,
+      line,
+      importPath: Node.isIdentifier(useFactoryExpr) ? importPathOf(useFactoryExpr, ctx) : undefined
+    };
+  }
+  if (useExistingExpr) {
+    const target = tokenNameOf(useExistingExpr, ctx).name;
+    return {
+      token,
+      tokenKind,
+      kind: "existing",
+      useExisting: target,
+      scope: resolveScope({ explicit: explicitScope, tokenName: token }, ctx),
+      deps: [target],
+      exported: exportsSet.has(token),
+      file,
+      line
+    };
+  }
+  return;
+}
+function parseController(el, ctx) {
+  if (!Node.isIdentifier(el))
+    return;
+  const decl = resolveDeclaration(el)[0];
+  if (!decl || !Node.isClassDeclaration(decl))
+    return;
+  const controllerDec = findDecorator(decl, "Controller");
+  if (!controllerDec)
+    return;
+  const pathArg = controllerDec.getArguments()[0];
+  const path = pathArg && Node.isStringLiteral(pathArg) ? pathArg.getLiteralText() : "/";
+  const { deps, missing } = classDeps(decl, ctx);
+  const file = sourcePath(ctx.rootDir, decl.getSourceFile().getFilePath());
+  if (missing) {
+    warn(ctx, "missing-deps", `controller ${decl.getName()} 的部分构造依赖无法静态解析`, file, decl.getStartLineNumber());
+  }
+  const injectable = parseInjectableOptions(decl, ctx);
+  const routes = [];
+  const schemaImports = {};
+  for (const method of decl.getMethods()) {
+    for (const dec of method.getDecorators()) {
+      const name = decoratorName(dec);
+      const httpMethod = name ? ROUTE_DECORATORS[name] : undefined;
+      if (!httpMethod)
+        continue;
+      const args = dec.getArguments();
+      const pathArg2 = args[0];
+      const route = {
+        method: httpMethod,
+        path: pathArg2 && Node.isStringLiteral(pathArg2) ? pathArg2.getLiteralText() : "/",
+        handler: method.getName()
+      };
+      const optionsArg = args[1];
+      if (optionsArg && Node.isObjectLiteralExpression(optionsArg)) {
+        for (const field of ["body", "params", "query", "response"]) {
+          const schemaExpr = getProp(optionsArg, field);
+          if (schemaExpr && Node.isIdentifier(schemaExpr)) {
+            route[field] = schemaExpr.getText();
+            const importPath = importPathOf(schemaExpr, ctx);
+            if (importPath)
+              schemaImports[schemaExpr.getText()] = importPath;
+          }
+        }
+        const commandExpr = getProp(optionsArg, "command");
+        if (commandExpr && Node.isIdentifier(commandExpr)) {
+          const commandDecl = resolveDeclaration(commandExpr)[0];
+          route.command = commandDecl && Node.isClassDeclaration(commandDecl) ? commandDecl.getName() ?? commandExpr.getText() : commandExpr.getText();
+        }
+      }
+      routes.push(route);
+    }
+  }
+  return {
+    className: decl.getName() ?? "<anonymous>",
+    path,
+    scope: injectable?.scope ?? "request",
+    deps,
+    routes,
+    file,
+    importPath: modulePath(ctx.rootDir, decl.getSourceFile().getFilePath()),
+    schemaImports: Object.keys(schemaImports).length > 0 ? schemaImports : undefined
+  };
+}
+function classDeps(cls, ctx) {
+  const injectable = parseInjectableOptions(cls, ctx);
+  if (injectable?.deps)
+    return { deps: injectable.deps, missing: false };
+  const ctor = cls.getConstructors()[0];
+  if (!ctor || ctor.getParameters().length === 0)
+    return { deps: [], missing: false };
+  const injectParams = parseInjectParams(cls);
+  const deps = [];
+  let missing = false;
+  ctor.getParameters().forEach((param, index) => {
+    const injected = injectParams.get(index);
+    if (injected) {
+      deps.push(injected);
+      return;
+    }
+    const byType = paramTypeTokenName(param, ctx);
+    if (byType) {
+      deps.push(byType);
+    } else {
+      missing = true;
+    }
+  });
+  return { deps, missing };
+}
+function paramTypeTokenName(param, ctx) {
+  const typeNode = param.getTypeNode();
+  if (!typeNode)
+    return;
+  const text = typeNode.getText().replace(/<.*>$/, "").replace(/\[\]$/, "").trim();
+  if (ctx.classesByName.has(text))
+    return text;
+  if (ctx.tokensByName.has(text))
+    return text;
+  return;
+}
+function parseInjectableOptions(cls, ctx) {
+  const dec = findDecorator(cls, "Injectable");
+  if (!dec)
+    return;
+  const obj = decoratorObjectArg(dec);
+  if (!obj)
+    return {};
+  const scope = stringLiteralProp(obj, "scope");
+  const depsExpr = getProp(obj, "deps");
+  return {
+    scope: scope && SCOPES.includes(scope) ? scope : undefined,
+    deps: depsExpr ? arrayProp(obj, "deps").map((el) => ctx ? tokenNameOf(el, ctx).name : el.getText()) : undefined
+  };
+}
+function parseInjectParams(cls) {
+  const result = new Map;
+  const ctor = cls.getConstructors()[0];
+  if (!ctor)
+    return result;
+  ctor.getParameters().forEach((param, index) => {
+    for (const dec of param.getDecorators()) {
+      if (decoratorName(dec) !== "Inject")
+        continue;
+      const arg = dec.getArguments()[0];
+      if (arg)
+        result.set(index, tokenText(arg));
+    }
+  });
+  return result;
+}
+function tokenText(expr) {
+  if (Node.isIdentifier(expr)) {
+    const decl = resolveDeclaration(expr)[0];
+    if (decl && Node.isClassDeclaration(decl))
+      return decl.getName() ?? expr.getText();
+    if (decl && Node.isVariableDeclaration(decl))
+      return decl.getName();
+  }
+  return expr.getText();
+}
+function resolveScope(input, ctx) {
+  if (input.explicit)
+    return input.explicit;
+  if (input.cls) {
+    const injectable = parseInjectableOptions(input.cls, ctx);
+    if (injectable?.scope)
+      return injectable.scope;
+  }
+  const token = ctx.tokensByName.get(input.tokenName);
+  if (token?.scope)
+    return token.scope;
+  return "application";
+}
+function tokenNameOf(expr, ctx) {
+  if (Node.isIdentifier(expr)) {
+    const decl = resolveDeclaration(expr)[0];
+    if (decl && Node.isClassDeclaration(decl)) {
+      return { name: decl.getName() ?? expr.getText(), kind: "class" };
+    }
+    if (decl && Node.isVariableDeclaration(decl)) {
+      const name = decl.getName();
+      return { name, kind: ctx.tokensByName.has(name) ? "injection-token" : "class" };
+    }
+    if (ctx.tokensByName.has(expr.getText())) {
+      return { name: expr.getText(), kind: "injection-token" };
+    }
+  }
+  return { name: expr.getText(), kind: "class" };
+}
+function resolveDeclaration(id) {
+  let symbol = id.getSymbol();
+  if (!symbol)
+    return [];
+  let declarations = symbol.getDeclarations();
+  for (let guard = 0;guard < 4; guard += 1) {
+    const isAlias = declarations.some((d) => Node.isImportSpecifier(d) || Node.isImportClause(d) || Node.isNamespaceImport(d));
+    if (!isAlias)
+      break;
+    const aliased = symbol.getAliasedSymbol();
+    if (!aliased)
+      break;
+    symbol = aliased;
+    declarations = aliased.getDeclarations();
+  }
+  return declarations;
+}
+function importPathOf(id, ctx) {
+  const symbol = id.getSymbol();
+  const first = symbol?.getDeclarations()[0];
+  if (first && (Node.isImportSpecifier(first) || Node.isImportClause(first))) {
+    const importDecl = first.getFirstAncestorByKind(SyntaxKind.ImportDeclaration);
+    const target = importDecl?.getModuleSpecifierSourceFile();
+    if (target)
+      return modulePath(ctx.rootDir, target.getFilePath());
+  }
+  const decl = resolveDeclaration(id)[0];
+  if (decl)
+    return modulePath(ctx.rootDir, decl.getSourceFile().getFilePath());
+  return;
+}
+function findDecorator(cls, name) {
+  return cls.getDecorators().find((dec) => decoratorName(dec) === name);
+}
+function decoratorName(dec) {
+  const expr = dec.getExpression();
+  if (Node.isCallExpression(expr)) {
+    return expr.getExpression().getText().split(".").pop();
+  }
+  if (Node.isIdentifier(expr))
+    return expr.getText();
+  return;
+}
+function decoratorObjectArg(dec) {
+  const expr = dec.getExpression();
+  if (!Node.isCallExpression(expr))
+    return;
+  const arg = expr.getArguments()[0];
+  return arg && Node.isObjectLiteralExpression(arg) ? arg : undefined;
+}
+function getProp(obj, name) {
+  const prop = obj.getProperty(name);
+  if (prop && Node.isPropertyAssignment(prop))
+    return prop.getInitializer();
+  return;
+}
+function stringLiteralProp(obj, name) {
+  const expr = getProp(obj, name);
+  return expr && Node.isStringLiteral(expr) ? expr.getLiteralText() : undefined;
+}
+function arrayProp(obj, name) {
+  const expr = getProp(obj, name);
+  return expr && Node.isArrayLiteralExpression(expr) ? expr.getElements() : [];
+}
+function parseScopeProp(obj) {
+  const scope = stringLiteralProp(obj, "scope");
+  return scope && SCOPES.includes(scope) ? scope : undefined;
+}
+function modulePath(rootDir, absFile) {
+  return sourcePath(rootDir, absFile).replace(/\.(ts|tsx|js|mts|cts)$/, "");
+}
+function sourcePath(rootDir, absFile) {
+  return relative(rootDir, absFile).split(sep).join("/");
+}
+function warn(ctx, code, message, file, line) {
+  ctx.diagnostics.push({ severity: "warn", code, message, file, line });
+}
+
+// src/generate.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+
+// src/util.ts
+function camelName(token) {
+  const isConstantCase = token.includes("_") || !/[a-z]/.test(token);
+  if (isConstantCase) {
+    return token.toLowerCase().split("_").filter((part) => part.length > 0).map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  }
+  return token.charAt(0).toLowerCase() + token.slice(1);
+}
+function relativeImportPath(fromDir, toFile) {
+  const fromParts = fromDir.split("/").filter(Boolean);
+  const toParts = toFile.split("/").filter(Boolean);
+  let common = 0;
+  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
+    common += 1;
+  }
+  const ups = fromParts.length - common;
+  const downs = toParts.slice(common);
+  const last = downs[downs.length - 1]?.replace(/\.(ts|tsx|js|mts|cts)$/, "") ?? "";
+  const segments = [...Array(ups).fill(".."), ...downs.slice(0, -1), last];
+  const joined = segments.join("/");
+  return joined.startsWith("..") ? joined : `./${joined}`;
+}
+var REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context";
+var JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
+function isRequestContextToken(token, tokenNames) {
+  return token === "REQUEST_CONTEXT" || tokenNames?.[token] === REQUEST_CONTEXT_TOKEN_NAME;
+}
+function isJobContextToken(token, tokenNames) {
+  return token === "JOB_CONTEXT" || tokenNames?.[token] === JOB_CONTEXT_TOKEN_NAME;
+}
+
+// src/generate.ts
+var HEADER = "// GENERATED BY @supacloud/compiler — do not edit";
+var INTERFACES = `export interface CompiledRoute {
+  method: string;
+  path: string;
+  handler: string;
+  body?: unknown;
+  params?: unknown;
+  query?: unknown;
+  response?: unknown;
+  command?: string;
+}
+
+export interface CompiledCommand {
+  className: string;
+  name: string;
+  permission: string;
+  transaction: "required" | "none";
+  audit?: string;
+  idempotency: "required" | "none";
+}
+
+export interface CompiledController {
+  path: string;
+  serviceKey: string;
+  scope: string;
+  routes: CompiledRoute[];
+}
+
+export interface CompiledModule {
+  name: string;
+  createServices(
+    deps: Record<string, unknown>,
+    imported: Record<string, Record<string, unknown>>,
+  ): Record<string, unknown>;
+  createRequestScope?(
+    services: Record<string, unknown>,
+    ctx: unknown,
+    imported?: Record<string, Record<string, unknown>>,
+  ): Record<string, unknown>;
+  createJobScope?(
+    services: Record<string, unknown>,
+    ctx: unknown,
+    imported?: Record<string, Record<string, unknown>>,
+  ): Record<string, unknown>;
+  controllers: CompiledController[];
+  commands: CompiledCommand[];
+}`;
+function renderApplication(graph, options) {
+  const modules = topoSortModules(graph.modules);
+  const imports = new ImportManager;
+  const factorySections = [];
+  const descriptorEntries = [];
+  for (const module of modules) {
+    const gen = new ModuleGenerator(graph, module, imports);
+    factorySections.push(...gen.renderFactories());
+    descriptorEntries.push(gen.renderDescriptor());
+  }
+  const code = [
+    HEADER,
+    "",
+    ...imports.render(options.rootDir, options.outDir),
+    ...imports.size > 0 ? [""] : [],
+    INTERFACES,
+    "",
+    "export function createCompiledModules(): CompiledModule[] {",
+    "  return [",
+    ...descriptorEntries.map((entry) => indent(entry, 4) + ","),
+    "  ];",
+    "}",
+    "",
+    ...factorySections,
+    ""
+  ].join(`
+`);
+  const manifest = {
+    version: 1,
+    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, rendered.applicationCode, "utf8");
+  await writeFile(manifestPath, rendered.manifestJson, "utf8");
+  return [applicationPath, manifestPath];
+}
+function factoryOfScope(scope) {
+  return scope === "application" ? "services" : scope;
+}
+function topoSortModules(modules) {
+  const byName = new Map(modules.map((m) => [m.name, m]));
+  const visited = new Set;
+  const result = [];
+  const visit = (module) => {
+    if (visited.has(module.name))
+      return;
+    visited.add(module.name);
+    for (const importName of module.imports) {
+      const dep = byName.get(importName);
+      if (dep && dep !== module)
+        visit(dep);
+    }
+    result.push(module);
+  };
+  for (const module of modules)
+    visit(module);
+  return result;
+}
+function pascalName(name) {
+  const joined = name.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  return joined || "App";
+}
+function indent(text, spaces) {
+  const pad = " ".repeat(spaces);
+  return text.split(`
+`).map((line) => line.length > 0 ? pad + line : line).join(`
+`);
+}
+
+class ImportManager {
+  entries = new Map;
+  get size() {
+    return this.entries.size;
+  }
+  add(exported, importPath) {
+    if (!importPath)
+      return exported;
+    for (const [local2, entry] of this.entries) {
+      if (entry.path === importPath && entry.exported === exported)
+        return local2;
+    }
+    let local = exported;
+    let counter = 2;
+    while (this.entries.has(local)) {
+      local = `${exported}${counter}`;
+      counter += 1;
+    }
+    this.entries.set(local, { path: importPath, exported });
+    return local;
+  }
+  render(rootDir, outDir) {
+    const byPath = new Map;
+    for (const [local, entry] of this.entries) {
+      const list = byPath.get(entry.path) ?? [];
+      list.push({ exported: entry.exported, local });
+      byPath.set(entry.path, list);
+    }
+    return [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([path, symbols]) => {
+      const spec = relativeImportPath(outDir, join2(rootDir, `${path}.ts`));
+      const names = symbols.sort((a, b) => a.exported.localeCompare(b.exported)).map((s) => s.local === s.exported ? s.exported : `${s.exported} as ${s.local}`).join(", ");
+      return `import { ${names} } from "${spec}";`;
+    });
+  }
+}
+
+class ModuleGenerator {
+  graph;
+  module;
+  imports;
+  pascal;
+  locals = {
+    services: new Map,
+    request: new Map,
+    job: new Map
+  };
+  constructor(graph, module, imports) {
+    this.graph = graph;
+    this.module = module;
+    this.imports = imports;
+    this.pascal = pascalName(module.name);
+  }
+  renderFactories() {
+    const sections = [this.renderServicesFactory()];
+    if (this.hasFactoryContent("request")) {
+      sections.push(this.renderScopeFactory("request"));
+    }
+    if (this.hasFactoryContent("job")) {
+      sections.push(this.renderScopeFactory("job"));
+    }
+    return sections;
+  }
+  renderDescriptor() {
+    const lines = [
+      `{`,
+      `  name: ${JSON.stringify(this.module.name)},`,
+      `  createServices: create${this.pascal}Services,`
+    ];
+    if (this.hasFactoryContent("request")) {
+      lines.push(`  createRequestScope: create${this.pascal}RequestScope,`);
+    }
+    if (this.hasFactoryContent("job")) {
+      lines.push(`  createJobScope: create${this.pascal}JobScope,`);
+    }
+    lines.push(`  controllers: ${this.renderControllers()},`);
+    lines.push(`  commands: ${JSON.stringify(this.module.commands)},`);
+    lines.push(`}`);
+    return lines.join(`
+`);
+  }
+  hasFactoryContent(kind) {
+    return this.module.providers.some((p) => factoryOfScope(p.scope) === kind) || this.module.controllers.some((c) => factoryOfScope(c.scope) === kind);
+  }
+  renderControllers() {
+    if (this.module.controllers.length === 0)
+      return "[]";
+    const items = this.module.controllers.map((controller) => {
+      const routes = controller.routes.map((route) => {
+        const fields = [
+          `method: ${JSON.stringify(route.method)}`,
+          `path: ${JSON.stringify(route.path)}`,
+          `handler: ${JSON.stringify(route.handler)}`
+        ];
+        for (const field of ["body", "params", "query", "response"]) {
+          const symbol = route[field];
+          if (symbol) {
+            const local = this.imports.add(symbol, controller.schemaImports?.[symbol]);
+            fields.push(`${field}: ${local}`);
+          }
+        }
+        if (route.command)
+          fields.push(`command: ${JSON.stringify(route.command)}`);
+        return `{ ${fields.join(", ")} }`;
+      });
+      return [
+        `{`,
+        `  path: ${JSON.stringify(controller.path)},`,
+        `  serviceKey: ${JSON.stringify(camelName(controller.className))},`,
+        `  scope: ${JSON.stringify(controller.scope)},`,
+        `  routes: [${routes.join(", ")}],`,
+        `}`
+      ].join(`
+`);
+    });
+    return `[${items.map((item) => `
+${indent(item, 2)}`).join(",")}
+]`;
+  }
+  renderServicesFactory() {
+    return [
+      `function create${this.pascal}Services(`,
+      `  deps: Record<string, unknown>,`,
+      `  imported: Record<string, Record<string, unknown>>,`,
+      `): Record<string, unknown> {`,
+      indent(this.renderFactoryBody("services"), 2),
+      `}`
+    ].join(`
+`);
+  }
+  renderScopeFactory(kind) {
+    const suffix = kind === "request" ? "RequestScope" : "JobScope";
+    return [
+      `function create${this.pascal}${suffix}(`,
+      `  services: Record<string, unknown>,`,
+      `  ctx: unknown,`,
+      `  imported: Record<string, Record<string, unknown>> = {},`,
+      `): Record<string, unknown> {`,
+      indent(this.renderFactoryBody(kind), 2),
+      `}`
+    ].join(`
+`);
+  }
+  renderFactoryBody(kind) {
+    const providers = orderProviders(this.module.providers.filter((p) => factoryOfScope(p.scope) === kind));
+    const controllers = this.module.controllers.filter((c) => factoryOfScope(c.scope) === kind);
+    const lines = [];
+    const returns = new Map;
+    for (const provider of providers) {
+      const emitted = this.emitProvider(provider, kind);
+      if (emitted.constLine)
+        lines.push(emitted.constLine);
+      returns.set(emitted.key, emitted.expr);
+    }
+    for (const controller of controllers) {
+      const emitted = this.emitController(controller, kind);
+      lines.push(emitted.constLine);
+      returns.set(emitted.key, emitted.expr);
+    }
+    const entries = [...returns.entries()].map(([key, expr]) => key === expr ? key : `${key}: ${expr}`);
+    lines.push(`return { ${entries.join(", ")} };`);
+    return lines.join(`
+`);
+  }
+  emitProvider(provider, kind) {
+    const key = camelName(provider.token);
+    switch (provider.kind) {
+      case "class": {
+        const useClass = this.imports.add(provider.useClass ?? provider.token, provider.importPath);
+        const args = provider.deps.map((dep) => this.depExpr(dep, kind)).join(", ");
+        const local = this.localVar(provider.token, kind);
+        return { constLine: `const ${local} = new ${useClass}(${args});`, key, expr: local };
+      }
+      case "value": {
+        const expr = provider.importPath ? this.imports.add(provider.useValueExpr ?? "undefined", provider.importPath) : provider.useValueExpr ?? "undefined";
+        const local = this.localVar(provider.token, kind);
+        return { constLine: `const ${local} = ${expr};`, key, expr: local };
+      }
+      case "factory": {
+        const factory = this.imports.add(provider.useFactoryName ?? "", provider.importPath);
+        const args = provider.deps.map((dep) => this.depExpr(dep, kind)).join(", ");
+        const local = this.localVar(provider.token, kind);
+        return { constLine: `const ${local} = ${factory}(${args});`, key, expr: local };
+      }
+      case "existing": {
+        return { key, expr: this.depExpr(provider.useExisting ?? provider.token, kind) };
+      }
+    }
+  }
+  emitController(controller, kind) {
+    const className = this.imports.add(controller.className, controller.importPath);
+    const args = controller.deps.map((dep) => this.depExpr(dep, kind)).join(", ");
+    const key = camelName(controller.className);
+    const local = this.localVar(controller.className, kind);
+    return { constLine: `const ${local} = new ${className}(${args});`, key, expr: local };
+  }
+  localVar(token, kind) {
+    const locals = this.locals[kind];
+    const existing = locals.get(token);
+    if (existing)
+      return existing;
+    const base = camelName(token);
+    let local = base;
+    let counter = 2;
+    while ([...locals.values()].includes(local)) {
+      local = `${base}${counter}`;
+      counter += 1;
+    }
+    locals.set(token, local);
+    return local;
+  }
+  depExpr(token, kind) {
+    if (kind === "request" && isRequestContextToken(token, this.graph.tokenNames))
+      return "ctx";
+    if (kind === "job" && isJobContextToken(token, this.graph.tokenNames))
+      return "ctx";
+    const own = this.module.providers.find((p) => p.token === token);
+    if (own) {
+      if (factoryOfScope(own.scope) === kind && own.kind !== "existing") {
+        return this.locals[kind].get(token) ?? camelName(token);
+      }
+      if (own.kind === "existing" && factoryOfScope(own.scope) === kind) {
+        return this.depExpr(own.useExisting ?? token, kind);
+      }
+      if (kind === "services") {
+        return `services.${camelName(token)}`;
+      }
+      return `services.${camelName(token)}`;
+    }
+    for (const importName of this.module.imports) {
+      const imported = this.graph.modules.find((m) => m.name === importName);
+      if (!imported?.exports.includes(token))
+        continue;
+      if (kind === "services")
+        return `imported.${importName}.${camelName(token)}`;
+      return `imported.${importName}.${camelName(token)}`;
+    }
+    if (kind === "services")
+      return `deps.${camelName(token)}`;
+    return `services.${camelName(token)}`;
+  }
+}
+function orderProviders(providers) {
+  const remaining = [...providers];
+  const emitted = new Set;
+  const result = [];
+  while (remaining.length > 0) {
+    const index = remaining.findIndex((p) => p.deps.every((dep) => {
+      const depProvider = providers.find((x) => x.token === dep);
+      return !depProvider || emitted.has(dep);
+    }));
+    if (index === -1) {
+      result.push(...remaining.splice(0));
+      break;
+    }
+    const [provider] = remaining.splice(index, 1);
+    emitted.add(provider.token);
+    result.push(provider);
+  }
+  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,
+  request: 1,
+  job: 1
+};
+function validateGraph(graph, options = false) {
+  const strict = typeof options === "boolean" ? options : options.strict ?? false;
+  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) {
+      if (!globalProviders.has(provider.token)) {
+        globalProviders.set(provider.token, { module, provider });
+      }
+    }
+  }
+  function resolveDep(module, token) {
+    const own = module.providers.find((p) => p.token === token);
+    if (own)
+      return { module, provider: own };
+    for (const importName of module.imports) {
+      const imported = graph.modules.find((m) => m.name === importName);
+      if (!imported || !imported.exports.includes(token))
+        continue;
+      const provider = imported.providers.find((p) => p.token === token);
+      if (provider)
+        return { module: imported, provider };
+    }
+    return;
+  }
+  const error = (code, message, file, line) => {
+    diagnostics.push({ severity: "error", code, message, file, line });
+  };
+  const warn2 = (code, message, file, line) => {
+    diagnostics.push({ severity: strict ? "error" : "warn", code, message, file, line });
+  };
+  const modulesByName = new Map;
+  const commandsByName = new Map;
+  const routesByKey = new Map;
+  for (const module of graph.modules) {
+    const previousModule = modulesByName.get(module.name);
+    if (previousModule) {
+      error("duplicate-module", `模块名 ${module.name} 重复（首次声明于 ${previousModule.file}:${previousModule.line}）`, module.file, module.line);
+    } else {
+      modulesByName.set(module.name, module);
+    }
+    for (const command of module.commands) {
+      const previousName = commandsByName.get(command.name);
+      if (previousName) {
+        error("duplicate-command", `command 名 ${command.name} 重复（首次由模块 ${previousName.module.name} 的 ${previousName.className} 声明）`, module.file, module.line);
+      } else {
+        commandsByName.set(command.name, { module, className: command.className });
+      }
+    }
+  }
+  for (const module of graph.modules) {
+    for (const controller of module.controllers) {
+      for (const route of controller.routes) {
+        const fullPath = joinRoutePaths(controller.path, route.path);
+        const key = `${route.method} ${fullPath}`;
+        const previous = routesByKey.get(key);
+        if (previous) {
+          error("duplicate-route", `路由 ${key} 重复（首次声明于模块 ${previous.module.name} 的 ${previous.controller.className}）`, controller.file);
+        } else {
+          routesByKey.set(key, { module, controller });
+        }
+        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);
+          }
+        }
+      }
+    }
+  }
+  for (const module of graph.modules) {
+    const seen = new Map;
+    for (const provider of module.providers) {
+      const first = seen.get(provider.token);
+      if (first) {
+        error("duplicate-token", `模块 ${module.name} 重复注册 token ${provider.token}（首次注册于 ${first.file}:${first.line}）`, provider.file, provider.line);
+      } else {
+        seen.set(provider.token, provider);
+      }
+    }
+    for (const provider of module.providers) {
+      for (const dep of provider.deps) {
+        const resolved = resolveDep(module, dep);
+        if (!resolved) {
+          if (!graph.externalTokens.includes(dep)) {
+            if (globalProviders.has(dep)) {
+              const owner = globalProviders.get(dep);
+              error("module-boundary", `模块 ${module.name} 的 provider ${provider.token} 依赖 ${dep}，该 token 由模块 ${owner.module.name} 提供但未被 import`, provider.file, provider.line);
+            } else {
+              error("unresolved-token", `模块 ${module.name} 的 provider ${provider.token} 依赖的 token ${dep} 无法解析`, provider.file, provider.line);
+            }
+          }
+          continue;
+        }
+        if (SCOPE_LIFETIME_RANK[resolved.provider.scope] > SCOPE_LIFETIME_RANK[provider.scope]) {
+          error("scope-violation", `模块 ${module.name} 的 ${provider.scope} provider ${provider.token} 不能依赖 ${resolved.provider.scope} provider ${dep}`, provider.file, provider.line);
+        }
+      }
+    }
+    for (const command of module.commands) {
+      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) {
+    for (const module of graph.modules) {
+      const sourceTags = module.tags ?? [];
+      for (const importName of module.imports) {
+        const targetModule = graph.modules.find((m) => m.name === importName);
+        if (!targetModule)
+          continue;
+        const targetTags = targetModule.tags ?? [];
+        for (const rule of moduleBoundaries) {
+          const matchesSource = rule.sourceTag === "*" || sourceTags.includes(rule.sourceTag);
+          if (!matchesSource)
+            continue;
+          if (rule.bannedDependenciesWithTags) {
+            for (const bannedTag of rule.bannedDependenciesWithTags) {
+              if (targetTags.includes(bannedTag)) {
+                error("module-boundary-violation", `模块 ${module.name} (tags: [${sourceTags.join(", ")}]) 禁止依赖带有标签 '${bannedTag}' 的模块 ${targetModule.name} (tags: [${targetTags.join(", ")}])`, module.file, module.line);
+              }
+            }
+          }
+          if (rule.onlyDependOnLibsWithTags && rule.onlyDependOnLibsWithTags.length > 0) {
+            const hasAllowed = targetTags.some((t) => rule.onlyDependOnLibsWithTags.includes(t));
+            if (!hasAllowed && targetTags.length > 0) {
+              error("module-boundary-violation", `模块 ${module.name} (tags: [${sourceTags.join(", ")}]) 仅允许依赖带有 [${rule.onlyDependOnLibsWithTags.join(", ")}] 标签的模块，但模块 ${targetModule.name} 的标签为 [${targetTags.join(", ")}]`, module.file, module.line);
+            }
+          }
+        }
+      }
+    }
+  }
+  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) {
+  const joined = `${prefix}/${path}`.replace(/\/{2,}/g, "/");
+  const normalized = joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
+  return normalized.replace(/:[^/]+/g, ":param");
+}
+function detectCycles(graph, resolveDep) {
+  const diagnostics = [];
+  const nodeId = (ref) => `${ref.module.name}:${ref.provider.token}`;
+  const nodes = graph.modules.flatMap((module) => module.providers.map((provider) => ({ module, provider })));
+  const state = new Map;
+  const stack = [];
+  const reported = new Set;
+  const visit = (ref) => {
+    const id = nodeId(ref);
+    if (state.get(id) === "done")
+      return;
+    if (state.get(id) === "visiting") {
+      const cycleStart = stack.findIndex((item) => nodeId(item) === id);
+      const cycle = [...stack.slice(cycleStart), ref];
+      const path = cycle.map((item) => item.provider.token).join(" -> ");
+      const cycleKey = cycle.map((item) => nodeId(item)).sort().join("|");
+      if (!reported.has(cycleKey)) {
+        reported.add(cycleKey);
+        diagnostics.push({
+          severity: "error",
+          code: "circular-dependency",
+          message: `provider 循环依赖: ${path}`,
+          file: ref.provider.file,
+          line: ref.provider.line
+        });
+      }
+      return;
+    }
+    state.set(id, "visiting");
+    stack.push(ref);
+    for (const dep of ref.provider.deps) {
+      const resolved = resolveDep(ref.module, dep);
+      if (resolved)
+        visit(resolved);
+    }
+    stack.pop();
+    state.set(id, "done");
+  };
+  for (const ref of nodes)
+    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,
+      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 written = await generateApplication(graph, {
+    rootDir: options.rootDir,
+    outDir: options.outDir
+  });
+  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
+  };
+}
+
+// src/cli.ts
+function printUsage() {
+  console.log(`
+@supacloud/compiler CLI
+
+Usage:
+  supacloud-compiler compile [rootDir] [options]
+  supacloud-compiler check   [rootDir] [options]
+
+Commands:
+  compile             Compile application modules and generate artifacts
+  check               Check artifact drift and run governance gates
+
+Options:
+  --root, -r <dir>    Application source root (default: current directory or first positional argument)
+  --out, -o <dir>     Artifact output directory (default: <rootDir>/generated)
+  --strict            Treat all warnings as errors
+  --preset, -p <name> Architecture preset ('modular-monolith' | 'angular-enterprise' | 'clean-architecture')
+  --help, -h          Show this help
+`);
+}
+async function run() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    process.exit(0);
+  }
+  const command = args[0];
+  if (command !== "compile" && command !== "check") {
+    console.error(`Error: unknown command "${command}"`);
+    printUsage();
+    process.exit(1);
+  }
+  let rootDir = ".";
+  let outDir;
+  let strict = false;
+  let preset;
+  for (let i = 1;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--root" || arg === "-r") {
+      rootDir = args[++i];
+    } else if (arg === "--out" || arg === "-o") {
+      outDir = args[++i];
+    } else if (arg === "--strict") {
+      strict = true;
+    } else if (arg === "--preset" || arg === "-p") {
+      preset = args[++i];
+    } else if (!arg.startsWith("-") && rootDir === ".") {
+      rootDir = arg;
+    }
+  }
+  const resolvedRoot = resolve(process.cwd(), rootDir);
+  const resolvedOut = outDir ? resolve(process.cwd(), outDir) : resolve(resolvedRoot, "generated");
+  if (command === "compile") {
+    const result = await compileProject({
+      rootDir: resolvedRoot,
+      outDir: resolvedOut,
+      strict,
+      moduleBoundaryPreset: preset
+    });
+    for (const diag of result.diagnostics) {
+      const loc = diag.file ? ` ${diag.file}${diag.line ? `:${diag.line}` : ""}` : "";
+      const log = diag.severity === "error" ? console.error : console.warn;
+      log(`[${diag.severity}] ${diag.code}${loc}: ${diag.message}`);
+    }
+    const errors = result.diagnostics.filter((d) => d.severity === "error");
+    if (errors.length > 0) {
+      console.error(`
+Compilation failed with ${errors.length} error(s).`);
+      process.exit(1);
+    }
+    console.log(`
+Compilation succeeded. Generated artifacts:
+${result.written.map((f) => `  - ${f}`).join(`
+`)}`);
+  } else {
+    const result = await checkProject({
+      rootDir: resolvedRoot,
+      outDir: resolvedOut,
+      strict,
+      moduleBoundaryPreset: preset
+    });
+    for (const diag of result.diagnostics) {
+      const loc = diag.file ? ` ${diag.file}${diag.line ? `:${diag.line}` : ""}` : "";
+      const log = diag.severity === "error" ? console.error : console.warn;
+      log(`[${diag.severity}] ${diag.code}${loc}: ${diag.message}`);
+    }
+    const errors = result.diagnostics.filter((d) => d.severity === "error");
+    if (errors.length > 0) {
+      console.error(`
+Governance checks failed with ${errors.length} error(s).`);
+      process.exit(1);
+    }
+    if (!result.upToDate) {
+      console.error(`
+Artifact drift detected:`);
+      for (const mismatch of result.mismatches) {
+        console.error(`  - ${mismatch}`);
+      }
+      console.error("Run the compile command and commit the updated generated artifacts.");
+      process.exit(1);
+    }
+    console.log("Artifact check passed: disk files match compiler output with no drift.");
+  }
+}
+run().catch((err) => {
+  console.error("Unhandled error:", err);
+  process.exit(1);
+});