@supacloud/compiler 0.4.1 → 0.6.0

package/dist/index.js

@@ -1,11 +1,330 @@
 // src/analyze.ts
-import { existsSync } from "node:fs";
-import { join, relative, sep } from "node:path";
-import {
-  Node,
-  Project,
-  SyntaxKind
-} from "ts-morph";
+import { createHash as createHash3 } from "node:crypto";
+import { relative, resolve as resolvePath, sep } from "node:path";
+import * as ts3 from "@typescript/typescript6";
+
+// src/program.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import * as ts2 from "@typescript/typescript6";
+
+// src/traits.ts
+import { createHash } from "node:crypto";
+import * as ts from "@typescript/typescript6";
+class TraitCompiler {
+  handlers;
+  constructor(handlers = createDefaultTraitHandlers()) {
+    this.handlers = handlers;
+  }
+  compile(program, previous, changedFiles) {
+    const byFile = new Map;
+    for (const sourceFile of program.getSourceFiles()) {
+      if (sourceFile.isDeclarationFile || sourceFile.fileName.includes("/node_modules/"))
+        continue;
+      const previousTraits = previous?.byFile.get(sourceFile.fileName);
+      if (previousTraits && !changedFiles.has(sourceFile.fileName)) {
+        byFile.set(sourceFile.fileName, previousTraits);
+        continue;
+      }
+      byFile.set(sourceFile.fileName, this.compileSourceFile(sourceFile));
+    }
+    const all = [...byFile.values()].flat().sort((a, b) => a.file.localeCompare(b.file) || a.start - b.start || a.kind.localeCompare(b.kind));
+    return { byFile, all };
+  }
+  compileSourceFile(sourceFile) {
+    const traits = [];
+    const visit = (node) => {
+      for (const handler of this.handlers) {
+        const name = handler.detect(node);
+        if (name)
+          traits.push(record(handler.kind, name, sourceFile, node));
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return traits;
+  }
+}
+function compileTraits(program, previous, changedFiles) {
+  return new TraitCompiler().compile(program, previous, changedFiles);
+}
+function record(kind, name, sourceFile, node) {
+  const text = node.getText(sourceFile);
+  return {
+    kind,
+    name,
+    file: sourceFile.fileName,
+    start: node.getStart(sourceFile),
+    end: node.end,
+    fingerprint: createHash("sha1").update(`${kind}:${text}`).digest("hex")
+  };
+}
+function decoratorName(decorator) {
+  return expressionName(ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression);
+}
+function expressionName(expression) {
+  if (ts.isIdentifier(expression))
+    return expression.text;
+  if (ts.isPropertyAccessExpression(expression))
+    return expression.name.text;
+  return "";
+}
+function createDefaultTraitHandlers() {
+  return [
+    {
+      kind: "module",
+      detect: decoratedDeclaration("Module")
+    },
+    {
+      kind: "injectable",
+      detect: decoratedDeclaration("Injectable")
+    },
+    {
+      kind: "controller",
+      detect: decoratedDeclaration("Controller")
+    },
+    {
+      kind: "command",
+      detect: decoratedDeclaration("Command")
+    },
+    {
+      kind: "query",
+      detect: decoratedDeclaration("Query")
+    },
+    {
+      kind: "defineModule",
+      detect: (node) => {
+        if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name))
+          return;
+        const initializer = node.initializer;
+        return initializer && ts.isCallExpression(initializer) && expressionName(initializer.expression) === "defineModule" ? node.name.text : undefined;
+      }
+    },
+    {
+      kind: "injectionToken",
+      detect: (node) => {
+        if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name))
+          return;
+        const initializer = node.initializer;
+        return initializer && ts.isNewExpression(initializer) && expressionName(initializer.expression) === "InjectionToken" ? node.name.text : undefined;
+      }
+    }
+  ];
+}
+function decoratedDeclaration(decorator) {
+  return (node) => {
+    if (!ts.isClassDeclaration(node) || !node.name)
+      return;
+    return (ts.getDecorators(node) ?? []).some((item) => decoratorName(item) === decorator) ? node.name.text : undefined;
+  };
+}
+
+// src/program.ts
+function createIncrementalProgramSession(projectRoot) {
+  const rootDir = resolve(projectRoot);
+  let projectConfig = readProjectConfig(rootDir);
+  let projectConfigKey = configKey(projectConfig);
+  let builder;
+  let traits;
+  const sourceFileCache = new Map;
+  return {
+    getProgram() {
+      if (!builder) {
+        throw new Error("incremental TypeScript program has not been initialized");
+      }
+      return builder.getProgram();
+    },
+    getTypeChecker() {
+      return this.getProgram().getTypeChecker();
+    },
+    update(rootNames, changedPaths = rootNames) {
+      const oldProgram = builder?.getProgram();
+      const oldSourceFiles = new Map(oldProgram?.getSourceFiles().map((sourceFile) => [canonical(sourceFile.fileName), sourceFile]) ?? []);
+      const nextProjectConfig = readProjectConfig(rootDir);
+      const nextProjectConfigKey = configKey(nextProjectConfig);
+      const configChanged = nextProjectConfigKey !== projectConfigKey;
+      const previousBuilder = configChanged ? undefined : builder;
+      if (configChanged) {
+        sourceFileCache.clear();
+        traits = undefined;
+      }
+      projectConfig = nextProjectConfig;
+      projectConfigKey = nextProjectConfigKey;
+      const normalizedRoots = [...new Set(rootNames.map((file) => resolve(rootDir, file)))].sort();
+      const normalizedChanged = [...new Set(changedPaths.map((file) => resolve(rootDir, file)))];
+      const invalidatedPaths = new Set(normalizedChanged.map(canonical));
+      for (const sourceFile of oldSourceFiles.values()) {
+        if (sourceVersion(sourceFile.fileName) !== sourceFileVersion(sourceFile)) {
+          invalidatedPaths.add(canonical(sourceFile.fileName));
+        }
+      }
+      const invalidateAllResolutions = configChanged || [...invalidatedPaths].some((fileName) => {
+        const wasInProgram = oldSourceFiles.has(fileName);
+        return wasInProgram !== existsSync(fileName);
+      });
+      for (const fileName of normalizedChanged) {
+        if (!existsSync(fileName))
+          sourceFileCache.delete(canonical(fileName));
+      }
+      const host = createHost(projectConfig.options, rootDir, sourceFileCache, invalidatedPaths, invalidateAllResolutions);
+      builder = ts2.createEmitAndSemanticDiagnosticsBuilderProgram(normalizedRoots, projectConfig.options, host, previousBuilder, projectConfig.errors, projectConfig.projectReferences);
+      const program = builder.getProgram();
+      const changedFiles = [];
+      const reusedFiles = [];
+      const currentPaths = new Set(program.getSourceFiles().map((file) => canonical(file.fileName)));
+      for (const sourceFile of program.getSourceFiles()) {
+        if (sourceFile.isDeclarationFile)
+          continue;
+        const previous = oldSourceFiles.get(canonical(sourceFile.fileName));
+        if (previous && previous === sourceFile) {
+          reusedFiles.push(sourceFile.fileName);
+        } else {
+          changedFiles.push(sourceFile.fileName);
+        }
+      }
+      for (const [path, sourceFile] of oldSourceFiles) {
+        if (!sourceFile.isDeclarationFile && !currentPaths.has(path)) {
+          changedFiles.push(sourceFile.fileName);
+        }
+      }
+      for (const path of sourceFileCache.keys()) {
+        if (!currentPaths.has(path))
+          sourceFileCache.delete(path);
+      }
+      traits = compileTraits(program, traits, new Set(changedFiles));
+      return { changedFiles, reusedFiles, program };
+    },
+    getTraits() {
+      return traits?.all ?? [];
+    },
+    getDiagnostics() {
+      if (!builder)
+        return projectConfig.errors;
+      const program = builder.getProgram();
+      return [
+        ...projectConfig.errors,
+        ...program.getSyntacticDiagnostics()
+      ];
+    },
+    emit() {
+      if (!builder) {
+        throw new Error("incremental TypeScript program has not been initialized");
+      }
+      return builder.emit();
+    },
+    reset() {
+      builder = undefined;
+      projectConfig = readProjectConfig(rootDir);
+      projectConfigKey = configKey(projectConfig);
+      traits = undefined;
+      sourceFileCache.clear();
+    }
+  };
+}
+function createHost(options, rootDir, sourceFileCache, invalidatedPaths, invalidateAllResolutions) {
+  const host = ts2.createIncrementalCompilerHost(options, {
+    ...ts2.sys,
+    getCurrentDirectory: () => rootDir
+  });
+  host.hasInvalidatedResolutions = (filePath) => invalidateAllResolutions || invalidatedPaths.has(canonical(filePath));
+  const originalGetSourceFile = host.getSourceFile.bind(host);
+  host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
+    const key = canonical(fileName);
+    const text = host.readFile(fileName);
+    if (text === undefined) {
+      sourceFileCache.delete(key);
+      return originalGetSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    }
+    const version = hashText(text);
+    const parseKey = sourceFileParseKey(languageVersion);
+    const cached = sourceFileCache.get(key);
+    if (!shouldCreateNewSourceFile && cached?.version === version && cached.parseKey === parseKey) {
+      return cached.sourceFile;
+    }
+    const sourceFile = originalGetSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    if (sourceFile) {
+      sourceFileCache.set(key, { sourceFile, version: hashText(sourceFile.text), parseKey });
+    } else {
+      sourceFileCache.delete(key);
+    }
+    return sourceFile;
+  };
+  return host;
+}
+function canonical(fileName) {
+  const normalized = resolve(fileName);
+  return ts2.sys.useCaseSensitiveFileNames ? normalized : normalized.toLowerCase();
+}
+function sourceFileParseKey(languageVersion) {
+  return typeof languageVersion === "number" ? `target:${languageVersion}` : JSON.stringify({
+    languageVersion: languageVersion.languageVersion,
+    impliedNodeFormat: languageVersion.impliedNodeFormat,
+    jsDocParsingMode: languageVersion.jsDocParsingMode
+  });
+}
+function configKey(config) {
+  return JSON.stringify({
+    options: config.options,
+    projectReferences: config.projectReferences,
+    configFingerprint: config.configFingerprint
+  });
+}
+function hashText(text) {
+  return createHash2("sha1").update(text).digest("hex");
+}
+function sourceVersion(fileName) {
+  try {
+    return hashText(readFileSync(fileName, "utf8"));
+  } catch {
+    return "missing";
+  }
+}
+function sourceFileVersion(sourceFile) {
+  const descriptor = Object.getOwnPropertyDescriptor(sourceFile, "version");
+  return typeof descriptor?.value === "string" ? descriptor.value : undefined;
+}
+function readProjectConfig(rootDir) {
+  const configPath = join(rootDir, "tsconfig.json");
+  if (!existsSync(configPath)) {
+    return {
+      options: {
+        target: ts2.ScriptTarget.ES2022,
+        module: ts2.ModuleKind.ESNext,
+        moduleResolution: ts2.ModuleResolutionKind.Bundler,
+        experimentalDecorators: true,
+        allowJs: false,
+        skipLibCheck: true
+      },
+      errors: [],
+      projectReferences: undefined,
+      configFingerprint: "defaults"
+    };
+  }
+  const configReads = new Map;
+  const readConfig = (fileName) => {
+    const text = ts2.sys.readFile(fileName);
+    configReads.set(canonical(fileName), text === undefined ? "missing" : hashText(text));
+    return text;
+  };
+  const config = ts2.readConfigFile(configPath, readConfig);
+  if (config.error) {
+    return {
+      options: {},
+      errors: [config.error],
+      configFingerprint: JSON.stringify([...configReads])
+    };
+  }
+  const parsed = ts2.parseJsonConfigFileContent(config.config, { ...ts2.sys, readFile: readConfig }, dirname(configPath));
+  return {
+    options: parsed.options,
+    errors: parsed.errors,
+    projectReferences: parsed.projectReferences,
+    configFingerprint: JSON.stringify([...configReads])
+  };
+}
+
+// src/analyze.ts
 var DEFAULT_INCLUDE = ["**/*.module.ts", "**/*.ts"];
 var ROUTE_DECORATORS = {
   Get: "GET",
@@ -17,60 +336,321 @@ var ROUTE_DECORATORS = {
   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()));
+function isScope(value) {
+  return SCOPES.some((scope) => scope === value);
+}
+function nodeText(node) {
+  return node.getText(node.getSourceFile());
+}
+function lineOf(node) {
+  const sourceFile = node.getSourceFile();
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}
+function variableName(decl) {
+  return ts3.isIdentifier(decl.name) ? decl.name.text : nodeText(decl.name);
+}
+function propertyName(name) {
+  if (ts3.isIdentifier(name) || ts3.isPrivateIdentifier(name))
+    return name.text;
+  if (ts3.isStringLiteral(name) || ts3.isNumericLiteral(name))
+    return name.text;
+  return nodeText(name);
+}
+function parameterName(param) {
+  return ts3.isIdentifier(param.name) ? param.name.text : nodeText(param.name);
+}
+function decoratorsOf(node) {
+  return ts3.canHaveDecorators(node) ? ts3.getDecorators(node) ?? [] : [];
+}
+function decoratorArguments(dec) {
+  return ts3.isCallExpression(dec.expression) ? dec.expression.arguments : [];
+}
+function hasMethod(cls, name) {
+  return cls.members.some((member) => (ts3.isMethodDeclaration(member) || ts3.isGetAccessorDeclaration(member) || ts3.isSetAccessorDeclaration(member)) && member.name !== undefined && propertyName(member.name) === name);
+}
+function hasDestroyHook(cls) {
+  return hasMethod(cls, "onDestroy") || hasMethod(cls, "ngOnDestroy");
+}
+function descendantsOfKind(root, predicate) {
+  const result = [];
+  const visit = (node) => {
+    if (predicate(node))
+      result.push(node);
+    ts3.forEachChild(node, visit);
+  };
+  visit(root);
+  return result;
+}
+async function analyzeProject(rootDir, include, cache, changedPaths) {
+  const session = cache?.programSession ?? createIncrementalProgramSession(rootDir);
+  if (cache)
+    cache.programSession = session;
+  const rootNames = ts3.sys.readDirectory(rootDir, [".ts", ".tsx"], ["node_modules", "dist"], include ?? DEFAULT_INCLUDE);
+  const update = session.update(rootNames, changedPaths);
+  const program = update.program;
+  const checker = program.getTypeChecker();
+  const sourceFiles = program.getSourceFiles().filter((sf) => !sf.isDeclarationFile && !sf.fileName.includes("/node_modules/") && !sf.fileName.includes("/dist/") && isProjectSourceFile(sf, rootDir)).sort((a, b) => a.fileName.localeCompare(b.fileName));
   const ctx = {
     rootDir,
+    program,
+    checker,
     tokensByName: new Map,
     classesByName: new Map,
     diagnostics: []
   };
+  const nativeTraitFiles = new Map;
+  for (const diagnostic of session.getDiagnostics()) {
+    ctx.diagnostics.push(toCompilerDiagnostic(diagnostic, rootDir));
+  }
+  for (const trait of session.getTraits()) {
+    const kinds = nativeTraitFiles.get(trait.file) ?? new Set;
+    kinds.add(trait.kind);
+    nativeTraitFiles.set(trait.file, kinds);
+  }
   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()
-      });
+    const traits = nativeTraitFiles.get(sf.fileName);
+    if (!cache || traits?.has("module")) {
+      for (const cls of sf.statements.filter(ts3.isClassDeclaration)) {
+        const moduleDec = findDecorator(cls, "Module");
+        if (!moduleDec)
+          continue;
+        const options = decoratorObjectArg(moduleDec);
+        if (!options)
+          continue;
+        candidates.push({
+          node: cls,
+          options,
+          className: cls.name?.text ?? "<anonymous>",
+          file: sf.fileName,
+          line: lineOf(cls)
+        });
+      }
     }
-    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()
-      });
+    if (!cache || traits?.has("defineModule")) {
+      for (const call of descendantsOfKind(sf, ts3.isCallExpression)) {
+        if (nodeText(call.expression) !== "defineModule")
+          continue;
+        const parent = call.parent;
+        if (!parent || !ts3.isVariableDeclaration(parent))
+          continue;
+        const arg = call.arguments[0];
+        if (!arg || !ts3.isObjectLiteralExpression(arg))
+          continue;
+        candidates.push({
+          node: parent,
+          options: arg,
+          className: variableName(parent),
+          file: sf.fileName,
+          line: lineOf(parent)
+        });
+      }
     }
   }
   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));
+  let modules = [];
+  let reusedModules = [];
+  let reanalyzedModules = [];
+  if (cache) {
+    const currentFileHashes = new Map;
+    for (const sf of sourceFiles) {
+      const rel = sourcePath(rootDir, sf.fileName);
+      const hash = createHash3("sha256").update(sf.getFullText()).digest("hex");
+      currentFileHashes.set(rel, hash);
+    }
+    const changedFiles = new Set;
+    for (const [file, hash] of currentFileHashes.entries()) {
+      if (cache.fileHashes.get(file) !== hash) {
+        changedFiles.add(file);
+      }
+    }
+    for (const file of cache.fileHashes.keys()) {
+      if (!currentFileHashes.has(file)) {
+        changedFiles.add(file);
+      }
+    }
+    const modulesToKeep = new Map;
+    const finalModules = [];
+    const finalDiagnostics = [...ctx.diagnostics];
+    const affectedModuleNames = cache.dependencyGraph && typeof cache.dependencyGraph.getAffectedModules === "function" ? new Set(cache.dependencyGraph.getAffectedModules(Array.from(changedFiles))) : new Set;
+    for (const [modName, entry] of cache.modules.entries()) {
+      const hasChangedFile = entry.ownedFiles.some((f) => changedFiles.has(f));
+      const moduleFileExists = currentFileHashes.has(entry.module.file);
+      const isAffectedByDep = affectedModuleNames.has(modName);
+      if (!hasChangedFile && !isAffectedByDep && moduleFileExists) {
+        modulesToKeep.set(modName, entry);
+        reusedModules.push(modName);
+        finalModules.push(entry.module);
+        if (entry.diagnostics)
+          finalDiagnostics.push(...entry.diagnostics);
+      }
+    }
+    for (const c of candidates) {
+      const modName = nameByNode.get(c.node) ?? c.className;
+      if (modulesToKeep.has(modName)) {
+        continue;
+      }
+      const diagBefore = ctx.diagnostics.length;
+      const parsed = parseModule(c, nameByNode, ctx);
+      const moduleDiagnostics = ctx.diagnostics.slice(diagBefore);
+      const ownedFiles = collectModuleSourceClosure(parsed, ctx);
+      const fileHashes = {};
+      for (const f of ownedFiles) {
+        fileHashes[f] = currentFileHashes.get(f) ?? "";
+      }
+      cache.modules.set(parsed.name, {
+        module: parsed,
+        ownedFiles: [...ownedFiles],
+        fileHashes,
+        diagnostics: moduleDiagnostics
+      });
+      reanalyzedModules.push(parsed.name);
+      finalModules.push(parsed);
+      finalDiagnostics.push(...moduleDiagnostics);
+    }
+    for (const modName of [...cache.modules.keys()]) {
+      if (!modulesToKeep.has(modName) && !reanalyzedModules.includes(modName)) {
+        cache.modules.delete(modName);
+      }
+    }
+    cache.fileHashes = currentFileHashes;
+    cache.lastStats = { reusedModules, reanalyzedModules };
+    ctx.diagnostics = finalDiagnostics;
+    modules = finalModules;
+  } else {
+    modules = candidates.map((c) => parseModule(c, nameByNode, ctx));
+  }
+  modules.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+  const allRegisteredClasses = new Set;
+  const allRegisteredControllers = new Set;
+  const allRegisteredCommands = new Set;
+  for (const m of modules) {
+    for (const p of m.providers) {
+      if (p.useClass)
+        allRegisteredClasses.add(p.useClass);
+      if (p.kind === "class")
+        allRegisteredClasses.add(p.token);
+    }
+    for (const c of m.controllers) {
+      allRegisteredControllers.add(c.className);
+    }
+    for (const cmd of m.commands) {
+      allRegisteredCommands.add(cmd.className);
+    }
+  }
+  const rootProviders = [];
+  const standaloneControllers = [];
+  const standaloneCommands = [];
+  for (const [name, classInfo] of ctx.classesByName.entries()) {
+    if (!allRegisteredClasses.has(name)) {
+      const injectable = parseInjectableOptions(classInfo.decl, ctx);
+      if (injectable?.providedIn === "root") {
+        const { deps, optionalDeps, selfDeps, skipSelfDeps, hostDeps, functionalInjects, missing } = classDeps(classInfo.decl, ctx);
+        const file = sourcePath(ctx.rootDir, classInfo.file);
+        const line = lineOf(classInfo.decl);
+        if (missing) {
+          warn(ctx, "missing-deps", `root provider ${name} 的部分构造依赖无法静态解析`, file, line);
+        }
+        rootProviders.push({
+          token: name,
+          tokenKind: "class",
+          kind: "class",
+          useClass: name,
+          scope: injectable.scope ?? "application",
+          deps,
+          optionalDeps: optionalDeps.length > 0 ? optionalDeps : undefined,
+          selfDeps: selfDeps.length > 0 ? selfDeps : undefined,
+          skipSelfDeps: skipSelfDeps.length > 0 ? skipSelfDeps : undefined,
+          hostDeps: hostDeps.length > 0 ? hostDeps : undefined,
+          functionalInjects: functionalInjects.length > 0 ? functionalInjects : undefined,
+          providedIn: "root",
+          hasOnDestroy: hasDestroyHook(classInfo.decl) || undefined,
+          exported: true,
+          file,
+          line,
+          importPath: modulePath(ctx.rootDir, classInfo.file)
+        });
+      }
+    }
+    if (!allRegisteredControllers.has(name)) {
+      const controllerDec = findDecorator(classInfo.decl, "Controller");
+      if (controllerDec) {
+        const arg = decoratorArguments(controllerDec)[0];
+        const isStandalone = arg && ts3.isObjectLiteralExpression(arg) && booleanProp(arg, "standalone");
+        if (isStandalone) {
+          const ctrl = parseController(classInfo.decl, ctx);
+          if (ctrl)
+            standaloneControllers.push(ctrl);
+        }
+      }
+    }
+    if (!allRegisteredCommands.has(name)) {
+      const commandDec = findDecorator(classInfo.decl, "Command");
+      if (commandDec) {
+        const meta = decoratorObjectArg(commandDec);
+        if (meta && booleanProp(meta, "standalone")) {
+          standaloneCommands.push({
+            className: classInfo.decl.name?.text ?? name,
+            name: stringLiteralProp(meta, "name") ?? classInfo.decl.name?.text ?? name,
+            permission: stringLiteralProp(meta, "permission"),
+            transaction: commandModeProp(meta, "transaction") ?? "none",
+            audit: stringLiteralProp(meta, "audit"),
+            idempotency: commandModeProp(meta, "idempotency") ?? "none",
+            standalone: true,
+            aspects: parseAspectRefs(getProp(meta, "aspects"), ctx, `command ${classInfo.decl.name?.text ?? name}`)
+          });
+        }
+      }
+    }
+  }
+  for (const [name, tokenInfo] of ctx.tokensByName.entries()) {
+    if (tokenInfo.providedIn === "root" && !allRegisteredClasses.has(name)) {
+      rootProviders.push({
+        token: name,
+        tokenKind: "injection-token",
+        kind: "factory",
+        scope: tokenInfo.scope ?? "application",
+        deps: [],
+        providedIn: "root",
+        exported: true,
+        file: sourcePath(ctx.rootDir, tokenInfo.file),
+        line: tokenInfo.line ?? 1,
+        importPath: modulePath(ctx.rootDir, tokenInfo.file)
+      });
+    }
+  }
+  if (rootProviders.length > 0 || standaloneControllers.length > 0 || standaloneCommands.length > 0) {
+    const existingRoot = modules.find((m) => m.name === "root" || m.name === "app");
+    if (existingRoot) {
+      modules = modules.map((module) => module === existingRoot ? {
+        ...module,
+        providers: [...module.providers, ...rootProviders],
+        controllers: [...module.controllers, ...standaloneControllers],
+        commands: [...module.commands, ...standaloneCommands],
+        exports: [...new Set([...module.exports, ...rootProviders.map((provider) => provider.token)])]
+      } : module);
+    } else {
+      const fallbackFile = rootProviders[0]?.file ?? standaloneControllers[0]?.file ?? "root.ts";
+      modules.unshift({
+        name: "root",
+        className: "RootModule",
+        file: fallbackFile,
+        line: 1,
+        imports: [],
+        providers: rootProviders,
+        controllers: standaloneControllers,
+        commands: standaloneCommands,
+        queries: [],
+        exports: rootProviders.map((p) => p.token)
+      });
+    }
+  }
   const providedTokens = new Set(modules.flatMap((m) => m.providers.map((p) => p.token)));
   const referenced = new Set;
   for (const m of modules) {
@@ -89,28 +669,76 @@ async function analyzeProject(rootDir, include) {
     modules,
     externalTokens,
     diagnostics: ctx.diagnostics,
-    tokenNames
+    tokenNames,
+    cacheStats: cache ? { reusedModules, reanalyzedModules } : undefined
   };
 }
-function createProject(rootDir) {
-  const tsConfigFilePath = join(rootDir, "tsconfig.json");
-  if (existsSync(tsConfigFilePath)) {
-    return new Project({ tsConfigFilePath, skipAddingFilesFromTsConfig: true });
+function collectModuleSourceClosure(module, ctx) {
+  const seeds = new Set;
+  const addRelativeModule = (path) => {
+    if (!path)
+      return;
+    const withExtension = /\.(tsx?|mts|cts|js)$/.test(path) ? path : `${path}.ts`;
+    seeds.add(resolveSourcePath(ctx.rootDir, withExtension));
+  };
+  addRelativeModule(module.file);
+  for (const provider of module.providers)
+    addRelativeModule(provider.importPath);
+  for (const controller of module.controllers)
+    addRelativeModule(controller.importPath);
+  const ownedFiles = new Set;
+  const queue = [...seeds];
+  while (queue.length > 0) {
+    const fileName = queue.shift();
+    if (!fileName)
+      continue;
+    const sourceFile = ctx.program.getSourceFile(fileName);
+    if (!sourceFile || sourceFile.isDeclarationFile || !isProjectSourceFile(sourceFile, ctx.rootDir))
+      continue;
+    const relativeFile = sourcePath(ctx.rootDir, sourceFile.fileName);
+    if (ownedFiles.has(relativeFile))
+      continue;
+    ownedFiles.add(relativeFile);
+    for (const statement of sourceFile.statements) {
+      let moduleName;
+      if (ts3.isImportDeclaration(statement) && ts3.isStringLiteral(statement.moduleSpecifier)) {
+        moduleName = statement.moduleSpecifier.text;
+      } else if (ts3.isExportDeclaration(statement) && statement.moduleSpecifier && ts3.isStringLiteral(statement.moduleSpecifier)) {
+        moduleName = statement.moduleSpecifier.text;
+      } else if (ts3.isImportEqualsDeclaration(statement) && ts3.isExternalModuleReference(statement.moduleReference) && ts3.isStringLiteral(statement.moduleReference.expression)) {
+        moduleName = statement.moduleReference.expression.text;
+      }
+      if (!moduleName || moduleName.startsWith("node:"))
+        continue;
+      const resolved = ts3.resolveModuleName(moduleName, sourceFile.fileName, ctx.program.getCompilerOptions(), ts3.sys).resolvedModule?.resolvedFileName;
+      if (resolved && isProjectSourcePath(resolved, ctx.rootDir))
+        queue.push(resolved);
+    }
   }
-  return new Project({
-    compilerOptions: { experimentalDecorators: true, allowJs: false }
-  });
+  return ownedFiles;
+}
+function resolveSourcePath(rootDir, file) {
+  const normalized = file.replace(/\\/g, "/");
+  return resolvePath(rootDir, normalized);
+}
+function isProjectSourcePath(fileName, rootDir) {
+  const normalized = fileName.replace(/\\/g, "/");
+  const root = rootDir.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized === root || normalized.startsWith(`${root}/`);
+}
+function isProjectSourceFile(sourceFile, rootDir) {
+  return isProjectSourcePath(sourceFile.fileName, rootDir) && /\.(tsx?|mts|cts)$/.test(sourceFile.fileName);
 }
 function indexFile(sf, ctx) {
-  for (const cls of sf.getClasses()) {
-    const name = cls.getName();
+  for (const cls of sf.statements.filter(ts3.isClassDeclaration)) {
+    const name = cls.name?.text;
     if (name && !ctx.classesByName.has(name)) {
-      ctx.classesByName.set(name, { name, decl: cls, file: sf.getFilePath() });
+      ctx.classesByName.set(name, { name, decl: cls, file: sf.fileName });
     }
   }
-  for (const statement of sf.getVariableStatements()) {
-    for (const decl of statement.getDeclarations()) {
-      const info = parseTokenVariable(decl, sf.getFilePath());
+  for (const statement of sf.statements.filter(ts3.isVariableStatement)) {
+    for (const decl of statement.declarationList.declarations) {
+      const info = parseTokenVariable(decl, sf.fileName);
       if (info && !ctx.tokensByName.has(info.name)) {
         ctx.tokensByName.set(info.name, info);
       }
@@ -118,53 +746,105 @@ function indexFile(sf, ctx) {
   }
 }
 function parseTokenVariable(decl, file) {
-  const init = decl.getInitializer();
-  if (!init || !Node.isNewExpression(init))
+  const init = decl.initializer;
+  if (!init || !ts3.isNewExpression(init))
     return;
-  if (init.getExpression().getText() !== "InjectionToken")
+  if (nodeText(init.expression) !== "InjectionToken")
     return;
-  const [nameArg, optionsArg] = init.getArguments();
-  const info = { name: decl.getName(), file };
-  if (nameArg && Node.isStringLiteral(nameArg)) {
-    info.stringName = nameArg.getLiteralText();
+  const [nameArg, optionsArg] = init.arguments ?? [];
+  const info = { name: variableName(decl), file, line: lineOf(decl) };
+  if (nameArg && ts3.isStringLiteral(nameArg)) {
+    info.stringName = nameArg.text;
   }
-  if (optionsArg && Node.isObjectLiteralExpression(optionsArg)) {
+  if (optionsArg && ts3.isObjectLiteralExpression(optionsArg)) {
     const scope = stringLiteralProp(optionsArg, "scope");
-    if (scope && SCOPES.includes(scope)) {
+    if (scope && isScope(scope)) {
       info.scope = scope;
     }
+    const providedIn = stringLiteralProp(optionsArg, "providedIn");
+    if (providedIn === "root") {
+      info.providedIn = "root";
+    }
+    const factory = getProp(optionsArg, "factory");
+    if (factory) {
+      info.hasFactory = true;
+    }
   }
   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 tags = arrayProp(options, "tags").map((el) => ts3.isStringLiteral(el) ? el.text : nodeText(el).replace(/['"]/g, "")).filter(Boolean);
+  const aspects = parseAspectRefs(getProp(options, "aspects"), ctx, `module ${name}`);
   const imports = arrayProp(options, "imports").map((el) => {
-    const decl = Node.isIdentifier(el) ? resolveDeclaration(el)[0] : undefined;
+    const unwrapped = unwrapForwardRef(el);
+    const decl = ts3.isIdentifier(unwrapped) ? resolveDeclaration(unwrapped, ctx)[0] : undefined;
     if (decl) {
       const known = nameByNode.get(decl);
       if (known)
         return known;
-      if (Node.isClassDeclaration(decl)) {
+      if (ts3.isClassDeclaration(decl)) {
         const dec = findDecorator(decl, "Module");
         const decOptions = dec && decoratorObjectArg(dec);
         const decName = decOptions && stringLiteralProp(decOptions, "name");
-        return decName ?? decl.getName() ?? el.getText();
+        return decName ?? decl.name?.text ?? nodeText(el);
       }
-      if (Node.isVariableDeclaration(decl))
-        return decl.getName();
+      if (ts3.isVariableDeclaration(decl))
+        return variableName(decl);
     }
-    return el.getText();
+    return nodeText(el);
   }).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")) {
+  for (const el of expandProviderExpressions(arrayProp(options, "providers"), ctx)) {
+    const parsedProviders = parseFunctionalProvider(el, exportsSet, ctx);
+    if (parsedProviders) {
+      providers.push(...parsedProviders);
+      continue;
+    }
+    if (ts3.isCallExpression(el)) {
+      const helper = nodeText(el.expression).split(".").pop() ?? nodeText(el.expression);
+      warn(ctx, "unsupported-provider-helper", `无法静态展开 provider helper '${helper}'；请改用显式 Provider 或实现编译器支持的 helper`, sourcePath(ctx.rootDir, el.getSourceFile().fileName), lineOf(el));
+      continue;
+    }
     const provider = parseProvider(el, exportsSet, ctx);
     if (provider)
       providers.push(provider);
   }
+  for (const el of arrayProp(options, "jobs")) {
+    if (!ts3.isIdentifier(el))
+      continue;
+    const decl = resolveDeclaration(el, ctx)[0];
+    if (!decl || !ts3.isClassDeclaration(decl))
+      continue;
+    const className2 = decl.name?.text ?? el.text;
+    const registeredProvider = providers.find((provider) => provider.token === className2);
+    if (registeredProvider)
+      continue;
+    const deps = classDeps(decl, ctx);
+    const injectable = parseInjectableOptions(decl, ctx);
+    const scope = injectable?.scope === "application" ? "application" : "job";
+    providers.push({
+      token: className2,
+      tokenKind: "class",
+      kind: "class",
+      useClass: className2,
+      scope,
+      deps: deps.deps,
+      optionalDeps: deps.optionalDeps.length > 0 ? deps.optionalDeps : undefined,
+      selfDeps: deps.selfDeps.length > 0 ? deps.selfDeps : undefined,
+      skipSelfDeps: deps.skipSelfDeps.length > 0 ? deps.skipSelfDeps : undefined,
+      hostDeps: deps.hostDeps.length > 0 ? deps.hostDeps : undefined,
+      functionalInjects: deps.functionalInjects.length > 0 ? deps.functionalInjects : undefined,
+      hasOnDestroy: hasDestroyHook(decl) || undefined,
+      exported: exportsSet.has(className2),
+      file: sourcePath(ctx.rootDir, decl.getSourceFile().fileName),
+      line: lineOf(decl),
+      importPath: modulePath(ctx.rootDir, decl.getSourceFile().fileName)
+    });
+  }
   const controllers = [];
   for (const el of arrayProp(options, "controllers")) {
     const controller = parseController(el, ctx);
@@ -174,39 +854,59 @@ function parseModule(candidate, nameByNode, ctx) {
   const handlerClasses = [];
   const seenHandlers = new Set;
   const collectHandler = (expr) => {
-    if (!Node.isIdentifier(expr))
+    if (!ts3.isIdentifier(expr))
       return;
-    const decl = resolveDeclaration(expr)[0];
-    if (decl && Node.isClassDeclaration(decl) && !seenHandlers.has(decl.getName() ?? "")) {
-      seenHandlers.add(decl.getName() ?? "");
+    const decl = resolveDeclaration(expr, ctx)[0];
+    if (decl && ts3.isClassDeclaration(decl) && !seenHandlers.has(decl.name?.text ?? "")) {
+      seenHandlers.add(decl.name?.text ?? "");
       handlerClasses.push(decl);
     }
   };
   for (const el of arrayProp(options, "providers")) {
-    if (Node.isIdentifier(el))
+    if (ts3.isIdentifier(el))
       collectHandler(el);
-    if (Node.isObjectLiteralExpression(el)) {
+    if (ts3.isObjectLiteralExpression(el)) {
       const useClass = getProp(el, "useClass");
       if (useClass)
         collectHandler(useClass);
     }
   }
   arrayProp(options, "commands").forEach(collectHandler);
+  arrayProp(options, "jobs").forEach(collectHandler);
   arrayProp(options, "queries").forEach(collectHandler);
   const commands = [];
+  const jobs = [];
   const queries = [];
   for (const cls of handlerClasses) {
     const commandDec = findDecorator(cls, "Command");
     if (commandDec) {
       const meta = decoratorObjectArg(commandDec);
       if (meta) {
+        const aspects2 = parseAspectRefs(getProp(meta, "aspects"), ctx, `command ${cls.name?.text ?? "<anonymous>"}`);
         commands.push({
-          className: cls.getName() ?? "<anonymous>",
-          name: stringLiteralProp(meta, "name") ?? cls.getName() ?? "<anonymous>",
+          className: cls.name?.text ?? "<anonymous>",
+          name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>",
           permission: stringLiteralProp(meta, "permission"),
           transaction: commandModeProp(meta, "transaction") ?? "none",
           audit: stringLiteralProp(meta, "audit"),
-          idempotency: commandModeProp(meta, "idempotency") ?? "none"
+          idempotency: commandModeProp(meta, "idempotency") ?? "none",
+          ...booleanProp(meta, "standalone") ? { standalone: true } : {},
+          ...aspects2.length > 0 ? { aspects: aspects2 } : {}
+        });
+      }
+    }
+    const jobDec = findDecorator(cls, "Job");
+    if (jobDec) {
+      const meta = decoratorObjectArg(jobDec);
+      if (meta) {
+        const injectable = parseInjectableOptions(cls, ctx);
+        const provider = providers.find((candidate2) => candidate2.token === (cls.name?.text ?? "<anonymous>"));
+        const aspects2 = parseAspectRefs(getProp(meta, "aspects"), ctx, `job ${cls.name?.text ?? "<anonymous>"}`);
+        jobs.push({
+          className: cls.name?.text ?? "<anonymous>",
+          name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>",
+          scope: provider?.scope ?? (injectable?.scope === "application" ? "application" : "job"),
+          ...aspects2.length > 0 ? { aspects: aspects2 } : {}
         });
       }
     }
@@ -215,8 +915,8 @@ function parseModule(candidate, nameByNode, ctx) {
       const meta = decoratorObjectArg(queryDec);
       if (meta) {
         queries.push({
-          className: cls.getName() ?? "<anonymous>",
-          name: stringLiteralProp(meta, "name") ?? cls.getName() ?? "<anonymous>"
+          className: cls.name?.text ?? "<anonymous>",
+          name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>"
         });
       }
     }
@@ -231,7 +931,9 @@ function parseModule(candidate, nameByNode, ctx) {
     providers,
     controllers,
     commands,
+    jobs,
     queries,
+    ...aspects.length > 0 ? { aspects } : {},
     exports
   };
 }
@@ -240,13 +942,15 @@ function commandModeProp(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 };
+  const file = sourcePath(ctx.rootDir, el.getSourceFile().fileName);
+  const line = lineOf(el);
+  const unwrappedEl = unwrapForwardRef(el);
+  if (ts3.isIdentifier(unwrappedEl)) {
+    const decl = resolveDeclaration(unwrappedEl, ctx)[0];
+    const cls = decl && ts3.isClassDeclaration(decl) ? decl : undefined;
+    const className = cls?.name?.text ?? unwrappedEl.text;
+    const { deps, optionalDeps, selfDeps, skipSelfDeps, hostDeps, functionalInjects, missing } = cls ? classDeps(cls, ctx) : { deps: [], optionalDeps: [], selfDeps: [], skipSelfDeps: [], hostDeps: [], functionalInjects: [], missing: false };
+    const injectable = cls ? parseInjectableOptions(cls, ctx) : undefined;
     if (missing) {
       warn(ctx, "missing-deps", `provider ${className} 的部分构造依赖无法静态解析`, file, line);
     }
@@ -257,13 +961,20 @@ function parseProvider(el, exportsSet, ctx) {
       useClass: className,
       scope: resolveScope({ cls, tokenName: className }, ctx),
       deps,
+      optionalDeps: optionalDeps.length > 0 ? optionalDeps : undefined,
+      selfDeps: selfDeps.length > 0 ? selfDeps : undefined,
+      skipSelfDeps: skipSelfDeps.length > 0 ? skipSelfDeps : undefined,
+      hostDeps: hostDeps.length > 0 ? hostDeps : undefined,
+      functionalInjects: functionalInjects.length > 0 ? functionalInjects : undefined,
+      providedIn: injectable?.providedIn,
+      hasOnDestroy: cls ? hasDestroyHook(cls) || undefined : undefined,
       exported: exportsSet.has(className),
       file,
       line,
-      importPath: cls ? modulePath(ctx.rootDir, cls.getSourceFile().getFilePath()) : undefined
+      importPath: cls ? modulePath(ctx.rootDir, cls.getSourceFile().fileName) : undefined
     };
   }
-  if (!Node.isObjectLiteralExpression(el))
+  if (!ts3.isObjectLiteralExpression(el))
     return;
   const provideExpr = getProp(el, "provide");
   if (!provideExpr)
@@ -271,22 +982,43 @@ function parseProvider(el, exportsSet, ctx) {
   const { name: token, kind: tokenKind } = tokenNameOf(provideExpr, ctx);
   const explicitScope = parseScopeProp(el);
   const explicitDeps = arrayProp(el, "deps").map((d) => tokenNameOf(d, ctx).name);
+  const multi = booleanProp(el, "multi");
   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();
+    const unwrappedClass = unwrapForwardRef(useClassExpr);
+    const decl = ts3.isIdentifier(unwrappedClass) ? resolveDeclaration(unwrappedClass, ctx)[0] : undefined;
+    const cls = decl && ts3.isClassDeclaration(decl) ? decl : undefined;
+    const useClass = cls?.name?.text ?? nodeText(unwrappedClass);
     let deps = explicitDeps;
-    if (deps.length === 0 && cls) {
+    let optionalDeps = [];
+    let selfDeps = [];
+    let skipSelfDeps = [];
+    let hostDeps = [];
+    let functionalInjects = [];
+    if (cls) {
       const result = classDeps(cls, ctx);
-      deps = result.deps;
+      if (deps.length === 0) {
+        deps = result.deps;
+        optionalDeps = result.optionalDeps;
+        selfDeps = result.selfDeps;
+        skipSelfDeps = result.skipSelfDeps;
+        hostDeps = result.hostDeps;
+      } else {
+        optionalDeps = result.optionalDeps.filter((dep) => deps.includes(dep));
+        selfDeps = result.selfDeps.filter((dep) => deps.includes(dep));
+        skipSelfDeps = result.skipSelfDeps.filter((dep) => deps.includes(dep));
+        hostDeps = result.hostDeps.filter((dep) => deps.includes(dep));
+      }
+      functionalInjects = result.functionalInjects;
       if (result.missing) {
         warn(ctx, "missing-deps", `provider ${token} (useClass ${useClass}) 的部分构造依赖无法静态解析`, file, line);
       }
     }
+    const injectable = cls ? parseInjectableOptions(cls, ctx) : undefined;
+    validateProviderCompatibility(provideExpr, useClassExpr, "class", token, ctx, file, line);
     return {
       token,
       tokenKind,
@@ -294,31 +1026,42 @@ function parseProvider(el, exportsSet, ctx) {
       useClass,
       scope: resolveScope({ explicit: explicitScope, cls, tokenName: token }, ctx),
       deps,
+      optionalDeps: optionalDeps.length > 0 ? optionalDeps : undefined,
+      selfDeps: selfDeps.length > 0 ? selfDeps : undefined,
+      skipSelfDeps: skipSelfDeps.length > 0 ? skipSelfDeps : undefined,
+      hostDeps: hostDeps.length > 0 ? hostDeps : undefined,
+      functionalInjects: functionalInjects.length > 0 ? functionalInjects : undefined,
+      multi: multi ?? undefined,
+      providedIn: injectable?.providedIn,
+      hasOnDestroy: cls ? hasMethod(cls, "onDestroy") || undefined : undefined,
       exported: exportsSet.has(token),
       file,
       line,
-      importPath: cls ? modulePath(ctx.rootDir, cls.getSourceFile().getFilePath()) : undefined
+      importPath: cls ? modulePath(ctx.rootDir, cls.getSourceFile().fileName) : undefined
     };
   }
   if (useValueExpr) {
+    validateProviderCompatibility(provideExpr, useValueExpr, "value", token, ctx, file, line);
     return {
       token,
       tokenKind,
       kind: "value",
-      useValueExpr: useValueExpr.getText(),
+      useValueExpr: nodeText(useValueExpr),
       scope: resolveScope({ explicit: explicitScope, tokenName: token }, ctx),
       deps: [],
+      multi: multi ?? undefined,
       exported: exportsSet.has(token),
       file,
       line,
-      importPath: Node.isIdentifier(useValueExpr) ? importPathOf(useValueExpr, ctx) : undefined
+      importPath: ts3.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();
+    const factoryName = ts3.isIdentifier(useFactoryExpr) ? (() => {
+      const decl = resolveDeclaration(useFactoryExpr, ctx)[0];
+      return decl && (ts3.isFunctionDeclaration(decl) || ts3.isVariableDeclaration(decl)) ? (ts3.isFunctionDeclaration(decl) ? decl.name?.text : variableName(decl)) ?? useFactoryExpr.text : useFactoryExpr.text;
+    })() : nodeText(useFactoryExpr);
+    validateProviderCompatibility(provideExpr, useFactoryExpr, "factory", token, ctx, file, line);
     return {
       token,
       tokenKind,
@@ -326,14 +1069,16 @@ function parseProvider(el, exportsSet, ctx) {
       useFactoryName: factoryName,
       scope: resolveScope({ explicit: explicitScope, tokenName: token }, ctx),
       deps: explicitDeps,
+      multi: multi ?? undefined,
       exported: exportsSet.has(token),
       file,
       line,
-      importPath: Node.isIdentifier(useFactoryExpr) ? importPathOf(useFactoryExpr, ctx) : undefined
+      importPath: ts3.isIdentifier(useFactoryExpr) ? importPathOf(useFactoryExpr, ctx) : undefined
     };
   }
   if (useExistingExpr) {
     const target = tokenNameOf(useExistingExpr, ctx).name;
+    validateProviderCompatibility(provideExpr, useExistingExpr, "existing", token, ctx, file, line);
     return {
       token,
       tokenKind,
@@ -341,6 +1086,7 @@ function parseProvider(el, exportsSet, ctx) {
       useExisting: target,
       scope: resolveScope({ explicit: explicitScope, tokenName: token }, ctx),
       deps: [target],
+      multi: multi ?? undefined,
       exported: exportsSet.has(token),
       file,
       line
@@ -348,99 +1094,654 @@ function parseProvider(el, exportsSet, ctx) {
   }
   return;
 }
-function parseController(el, ctx) {
-  if (!Node.isIdentifier(el))
+function expandProviderExpressions(expressions, ctx, seen = new Set) {
+  const result = [];
+  for (const expression of expressions) {
+    if (ts3.isSpreadElement(expression)) {
+      result.push(...expandProviderExpressions([expression.expression], ctx, seen));
+      continue;
+    }
+    if (ts3.isIdentifier(expression)) {
+      const declaration = resolveDeclaration(expression, ctx)[0];
+      if (declaration && ts3.isVariableDeclaration(declaration) && declaration.initializer) {
+        const key = `${declaration.getSourceFile().fileName}:${declaration.pos}`;
+        if (seen.has(key))
+          continue;
+        const initializer = declaration.initializer;
+        if (ts3.isCallExpression(initializer) && isProviderHelper(initializer, "makeEnvironmentProviders")) {
+          const nested = initializer.arguments[0];
+          if (nested && ts3.isArrayLiteralExpression(nested)) {
+            seen.add(key);
+            result.push(...expandProviderExpressions([...nested.elements], ctx, seen));
+            seen.delete(key);
+            continue;
+          }
+        }
+      }
+    }
+    if (ts3.isCallExpression(expression) && isProviderHelper(expression, "makeEnvironmentProviders")) {
+      const nested = expression.arguments[0];
+      if (nested && ts3.isArrayLiteralExpression(nested)) {
+        result.push(...expandProviderExpressions([...nested.elements], ctx, seen));
+        continue;
+      }
+    }
+    result.push(expression);
+  }
+  return result;
+}
+function isProviderHelper(expression, name) {
+  return nodeText(expression.expression).split(".").pop() === name;
+}
+function parseFunctionalProvider(expression, exportsSet, ctx) {
+  if (!ts3.isCallExpression(expression))
+    return;
+  const helper = nodeText(expression.expression).split(".").pop();
+  const args = expression.arguments;
+  const file = sourcePath(ctx.rootDir, expression.getSourceFile().fileName);
+  const line = lineOf(expression);
+  if (helper === "provideToken") {
+    const tokenExpr = args[0];
+    const valueExpr = args[1];
+    if (!tokenExpr || !valueExpr)
+      return [];
+    const { name: token, kind: tokenKind } = tokenNameOf(tokenExpr, ctx);
+    validateProviderCompatibility(tokenExpr, valueExpr, "value", token, ctx, file, line);
+    return [{
+      token,
+      tokenKind,
+      kind: "value",
+      useValueExpr: nodeText(valueExpr),
+      scope: resolveScope({ tokenName: token }, ctx),
+      deps: [],
+      exported: exportsSet.has(token),
+      file,
+      line,
+      importPath: ts3.isIdentifier(valueExpr) ? importPathOf(valueExpr, ctx) : undefined
+    }];
+  }
+  if (helper === "provideAppInitializer" || helper === "provideEnvironmentInitializer") {
+    const initializer = args[0];
+    if (!initializer)
+      return [];
+    const token = helper === "provideAppInitializer" ? "APP_INITIALIZER" : "ENVIRONMENT_INITIALIZER";
+    return [{
+      token,
+      tokenKind: "injection-token",
+      kind: "value",
+      useValueExpr: nodeText(initializer),
+      scope: "application",
+      deps: [],
+      multi: true,
+      exported: false,
+      file,
+      line,
+      importPath: ts3.isIdentifier(initializer) ? importPathOf(initializer, ctx) : undefined
+    }];
+  }
+  if (helper === "provideRouter") {
+    const providers = [];
+    const routes = args[0];
+    if (routes) {
+      providers.push({
+        token: "ROUTE_CONFIG",
+        tokenKind: "injection-token",
+        kind: "value",
+        useValueExpr: nodeText(routes),
+        scope: "application",
+        deps: [],
+        exported: false,
+        file,
+        line,
+        importPath: ts3.isIdentifier(routes) ? importPathOf(routes, ctx) : undefined
+      });
+    }
+    for (const feature of args.slice(1)) {
+      if (!ts3.isCallExpression(feature))
+        continue;
+      const featureName = nodeText(feature.expression).split(".").pop();
+      if (featureName === "withRouterConfig" && feature.arguments[0]) {
+        providers.push({
+          token: "ROUTER_CONFIGURATION",
+          tokenKind: "injection-token",
+          kind: "value",
+          useValueExpr: nodeText(feature.arguments[0]),
+          scope: "application",
+          deps: [],
+          exported: false,
+          file,
+          line
+        });
+      } else if (featureName === "withTitleStrategy" && feature.arguments[0]) {
+        const strategy = feature.arguments[0];
+        const isClass = ts3.isIdentifier(strategy) && Boolean(resolveDeclaration(strategy, ctx).find((declaration) => ts3.isClassDeclaration(declaration)));
+        providers.push({
+          token: "TITLE_STRATEGY",
+          tokenKind: "injection-token",
+          kind: isClass ? "class" : "value",
+          ...isClass ? { useClass: nodeText(strategy) } : { useValueExpr: nodeText(strategy) },
+          scope: "application",
+          deps: [],
+          exported: false,
+          file,
+          line,
+          importPath: ts3.isIdentifier(strategy) ? importPathOf(strategy, ctx) : undefined
+        });
+      }
+    }
+    return providers;
+  }
+  if (helper === "provideHttpClient") {
+    const providers = [{
+      token: "HttpClient",
+      tokenKind: "class",
+      kind: "class",
+      useClass: "HttpClient",
+      scope: "application",
+      deps: ["HTTP_CLIENT_CONFIG", "HTTP_INTERCEPTORS"],
+      optionalDeps: ["HTTP_CLIENT_CONFIG", "HTTP_INTERCEPTORS"],
+      exported: false,
+      file,
+      line,
+      importModule: "@supacloud/app"
+    }];
+    for (const feature of args) {
+      if (!ts3.isCallExpression(feature))
+        continue;
+      const featureName = nodeText(feature.expression).split(".").pop();
+      if (featureName === "withInterceptors") {
+        for (const interceptorArg of feature.arguments) {
+          const values = ts3.isArrayLiteralExpression(interceptorArg) ? [...interceptorArg.elements] : [interceptorArg];
+          for (const value of values) {
+            providers.push({
+              token: "HTTP_INTERCEPTORS",
+              tokenKind: "injection-token",
+              kind: "value",
+              useValueExpr: nodeText(value),
+              scope: "application",
+              deps: [],
+              multi: true,
+              exported: false,
+              file,
+              line,
+              importPath: ts3.isIdentifier(value) ? importPathOf(value, ctx) : undefined
+            });
+          }
+        }
+      } else if (featureName === "withFetch" && feature.arguments.length > 0) {
+        warn(ctx, "unsupported-provider-helper", "provideHttpClient(withFetch(customFetch)) 需要显式声明 HTTP_CLIENT_CONFIG provider 才能保持静态生成", file, line);
+      }
+    }
+    return providers;
+  }
+  return;
+}
+function validateProviderCompatibility(provideExpr, implementationExpr, kind, tokenName, ctx, file, line) {
+  const expected = providerTokenValueType(provideExpr, ctx);
+  const actual = providerImplementationType(implementationExpr, kind, ctx);
+  if (!expected || !actual || isUnknownOrAny(expected) || isUnknownOrAny(actual))
     return;
-  const decl = resolveDeclaration(el)[0];
-  if (!decl || !Node.isClassDeclaration(decl))
+  if (ctx.checker.isTypeAssignableTo(actual, expected))
+    return;
+  const providerKind = kind === "class" ? "useClass" : `use${kind.charAt(0).toUpperCase()}${kind.slice(1)}`;
+  ctx.diagnostics.push({
+    severity: "error",
+    code: "provider-type-mismatch",
+    message: `Provider '${tokenName}' 的 ${providerKind} 类型不满足 Token 契约：需要 ${ctx.checker.typeToString(expected, provideExpr)}，实际为 ${ctx.checker.typeToString(actual, implementationExpr)}`,
+    file,
+    line,
+    errorCode: "SC2010",
+    docsUrl: "https://supacloud.dev/errors/SC2010"
+  });
+}
+function providerTokenValueType(expr, ctx) {
+  const type = ctx.checker.getTypeAtLocation(expr);
+  const typeArguments = typeArgumentsOf(type, ctx);
+  if (typeArguments.length > 0)
+    return typeArguments[0];
+  if (ts3.isIdentifier(expr)) {
+    const declaration = resolveDeclaration(expr, ctx)[0];
+    if (declaration && ts3.isClassDeclaration(declaration)) {
+      return declaredClassType(declaration, ctx);
+    }
+  }
+  return;
+}
+function providerImplementationType(expr, kind, ctx) {
+  if (kind === "class" || kind === "existing") {
+    if (ts3.isIdentifier(expr)) {
+      const declaration = resolveDeclaration(expr, ctx)[0];
+      if (declaration && ts3.isClassDeclaration(declaration)) {
+        return declaredClassType(declaration, ctx);
+      }
+    }
+    const type = ctx.checker.getTypeAtLocation(expr);
+    const typeArguments = typeArgumentsOf(type, ctx);
+    return typeArguments.length > 0 ? typeArguments[0] : undefined;
+  }
+  if (kind === "factory") {
+    const type = ctx.checker.getTypeAtLocation(expr);
+    const signature = ctx.checker.getSignaturesOfType(type, ts3.SignatureKind.Call)[0];
+    return signature?.getReturnType();
+  }
+  return ctx.checker.getTypeAtLocation(expr);
+}
+function declaredClassType(declaration, ctx) {
+  const name = declaration.name;
+  if (!name)
+    return;
+  const symbol = ctx.checker.getSymbolAtLocation(name);
+  return symbol ? ctx.checker.getDeclaredTypeOfSymbol(symbol) : undefined;
+}
+function typeArgumentsOf(type, ctx) {
+  return isTypeReference(type) ? ctx.checker.getTypeArguments(type) : [];
+}
+function isTypeReference(type) {
+  return "target" in type;
+}
+function isUnknownOrAny(type) {
+  return (type.flags & (ts3.TypeFlags.Any | ts3.TypeFlags.Unknown)) !== 0;
+}
+function parseController(input, ctx) {
+  let decl;
+  if (ts3.isClassDeclaration(input)) {
+    decl = input;
+  } else {
+    const unwrapped = unwrapForwardRef(input);
+    const resolved = ts3.isIdentifier(unwrapped) ? resolveDeclaration(unwrapped, ctx)[0] : undefined;
+    if (resolved && ts3.isClassDeclaration(resolved)) {
+      decl = resolved;
+    }
+  }
+  if (!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());
+  let path = "/";
+  let standalone;
+  const pathArg = decoratorArguments(controllerDec)[0];
+  if (pathArg) {
+    if (ts3.isStringLiteral(pathArg)) {
+      path = pathArg.text;
+    } else if (ts3.isObjectLiteralExpression(pathArg)) {
+      const p = stringLiteralProp(pathArg, "path");
+      if (p)
+        path = p;
+      standalone = booleanProp(pathArg, "standalone");
+    }
+  }
+  const { deps, optionalDeps, selfDeps, skipSelfDeps, hostDeps, functionalInjects, missing } = classDeps(decl, ctx);
+  const file = sourcePath(ctx.rootDir, decl.getSourceFile().fileName);
   if (missing) {
-    warn(ctx, "missing-deps", `controller ${decl.getName()} 的部分构造依赖无法静态解析`, file, decl.getStartLineNumber());
+    warn(ctx, "missing-deps", `controller ${decl.name?.text} 的部分构造依赖无法静态解析`, file, lineOf(decl));
   }
   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 classGuards = [];
+  for (const dec of decoratorsOf(decl)) {
+    if (decoratorName2(dec) === "UseGuards") {
+      for (const gArg of decoratorArguments(dec)) {
+        classGuards.push(tokenText(gArg, ctx));
+      }
+    }
+  }
+  for (const method of decl.members.filter(ts3.isMethodDeclaration)) {
+    for (const dec of decoratorsOf(method)) {
+      const name = decoratorName2(dec);
       const httpMethod = name ? ROUTE_DECORATORS[name] : undefined;
       if (!httpMethod)
         continue;
-      const args = dec.getArguments();
+      const args = decoratorArguments(dec);
       const pathArg2 = args[0];
+      const routePath = pathArg2 && ts3.isStringLiteral(pathArg2) ? pathArg2.text : "/";
       const route = {
         method: httpMethod,
-        path: pathArg2 && Node.isStringLiteral(pathArg2) ? pathArg2.getLiteralText() : "/",
-        handler: method.getName()
+        path: routePath,
+        handler: propertyName(method.name)
       };
+      const pathParams = [];
+      const paramRegex = /:([a-zA-Z0-9_]+)/g;
+      let match;
+      while ((match = paramRegex.exec(routePath)) !== null) {
+        pathParams.push(match[1]);
+      }
+      if (pathParams.length > 0)
+        route.pathParams = pathParams;
+      const paramBindings = [];
+      const queryBindings = [];
+      const paramTransforms = {};
+      const paramDefaults = {};
+      const queryTransforms = {};
+      const queryDefaults = {};
+      let hasBodyBinding = false;
+      const handlerParams = [];
+      for (const p of method.parameters) {
+        const pName = parameterName(p);
+        let hasBindingDecorator = false;
+        let paramNode;
+        for (const pDec of decoratorsOf(p)) {
+          const dName = decoratorName2(pDec);
+          const dArgs = decoratorArguments(pDec);
+          if (dName === "Param") {
+            hasBindingDecorator = true;
+            const parsed = parseBindingOptions(dArgs, pName);
+            paramBindings.push(parsed.name);
+            if (parsed.transform)
+              paramTransforms[parsed.name] = parsed.transform;
+            if (parsed.default !== undefined)
+              paramDefaults[parsed.name] = parsed.default;
+            paramNode = {
+              name: pName,
+              kind: "param",
+              bindingName: parsed.name,
+              transform: parsed.transform,
+              default: parsed.default
+            };
+          } else if (dName === "Query") {
+            hasBindingDecorator = true;
+            const parsed = parseBindingOptions(dArgs, pName);
+            queryBindings.push(parsed.name);
+            if (parsed.transform)
+              queryTransforms[parsed.name] = parsed.transform;
+            if (parsed.default !== undefined)
+              queryDefaults[parsed.name] = parsed.default;
+            paramNode = {
+              name: pName,
+              kind: "query",
+              bindingName: parsed.name,
+              transform: parsed.transform,
+              default: parsed.default
+            };
+          } else if (dName === "Body") {
+            hasBindingDecorator = true;
+            hasBodyBinding = true;
+            paramNode = { name: pName, kind: "body" };
+          } else if (dName === "Headers") {
+            hasBindingDecorator = true;
+            paramNode = { name: pName, kind: "headers" };
+          }
+        }
+        if (!hasBindingDecorator && pathParams.includes(pName)) {
+          paramBindings.push(pName);
+          const typeText = p.type ? nodeText(p.type) : "";
+          let inferredTransform;
+          if (typeText === "number") {
+            paramTransforms[pName] = "number";
+            inferredTransform = "number";
+          } else if (typeText === "boolean") {
+            paramTransforms[pName] = "boolean";
+            inferredTransform = "boolean";
+          }
+          paramNode = {
+            name: pName,
+            kind: "param",
+            bindingName: pName,
+            transform: inferredTransform
+          };
+        } else if (!hasBindingDecorator) {
+          if (pName === "req" || pName === "ctx" || pName === "context") {
+            paramNode = { name: pName, kind: "context" };
+          } else {
+            paramNode = { name: pName, kind: "unknown" };
+          }
+        }
+        if (paramNode)
+          handlerParams.push(paramNode);
+      }
+      if (paramBindings.length > 0)
+        route.paramBindings = paramBindings;
+      if (queryBindings.length > 0)
+        route.queryBindings = queryBindings;
+      if (Object.keys(paramTransforms).length > 0)
+        route.paramTransforms = paramTransforms;
+      if (Object.keys(paramDefaults).length > 0)
+        route.paramDefaults = paramDefaults;
+      if (Object.keys(queryTransforms).length > 0)
+        route.queryTransforms = queryTransforms;
+      if (Object.keys(queryDefaults).length > 0)
+        route.queryDefaults = queryDefaults;
+      if (hasBodyBinding)
+        route.hasBodyBinding = true;
+      if (handlerParams.length > 0)
+        route.handlerParams = handlerParams;
+      const routeGuards = [...classGuards];
+      const routeCanDeactivate = [];
+      for (const mDec of decoratorsOf(method)) {
+        const dName = decoratorName2(mDec);
+        const mArgs = decoratorArguments(mDec);
+        if (dName === "UseGuards") {
+          for (const gArg of mArgs) {
+            routeGuards.push(tokenText(gArg, ctx));
+          }
+        } else if (dName === "CanDeactivate") {
+          for (const gArg of mArgs) {
+            routeCanDeactivate.push(tokenText(gArg, ctx));
+          }
+        } else if (dName === "Title") {
+          const tArg = mArgs[0];
+          if (tArg && ts3.isStringLiteral(tArg)) {
+            route.title = tArg.text;
+          }
+        } else if (dName === "Data") {
+          const dArg = mArgs[0];
+          if (dArg && ts3.isObjectLiteralExpression(dArg)) {
+            route.data = { ...route.data, ...parseObjectLiteralValues(dArg) };
+          }
+        } else if (dName === "Resolve") {
+          const rArg = mArgs[0];
+          if (rArg && ts3.isObjectLiteralExpression(rArg)) {
+            const resolvers = route.resolvers ?? {};
+            for (const prop of rArg.properties) {
+              if (ts3.isPropertyAssignment(prop)) {
+                const rName = propertyName(prop.name);
+                const init = prop.initializer;
+                if (init)
+                  resolvers[rName] = tokenText(init, ctx);
+              }
+            }
+            if (Object.keys(resolvers).length > 0) {
+              route.resolvers = resolvers;
+            }
+          }
+        }
+      }
       const optionsArg = args[1];
-      if (optionsArg && Node.isObjectLiteralExpression(optionsArg)) {
+      if (optionsArg && ts3.isObjectLiteralExpression(optionsArg)) {
         for (const field of ["body", "params", "query", "response"]) {
           const schemaExpr = getProp(optionsArg, field);
-          if (schemaExpr && Node.isIdentifier(schemaExpr)) {
-            route[field] = schemaExpr.getText();
+          if (schemaExpr && ts3.isIdentifier(schemaExpr)) {
+            route[field] = nodeText(schemaExpr);
             const importPath = importPathOf(schemaExpr, ctx);
             if (importPath)
-              schemaImports[schemaExpr.getText()] = importPath;
+              schemaImports[schemaExpr.text] = 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();
+        if (commandExpr && ts3.isIdentifier(commandExpr)) {
+          const commandDecl = resolveDeclaration(commandExpr, ctx)[0];
+          route.command = commandDecl && ts3.isClassDeclaration(commandDecl) ? commandDecl.name?.text ?? commandExpr.text : commandExpr.text;
+        }
+        const guardsExpr = getProp(optionsArg, "guards");
+        if (guardsExpr && ts3.isArrayLiteralExpression(guardsExpr)) {
+          for (const el of guardsExpr.elements) {
+            routeGuards.push(tokenText(el, ctx));
+          }
+        }
+        const canMatchExpr = getProp(optionsArg, "canMatch");
+        if (canMatchExpr && ts3.isArrayLiteralExpression(canMatchExpr)) {
+          const canMatchList = [];
+          for (const el of canMatchExpr.elements) {
+            canMatchList.push(tokenText(el, ctx));
+          }
+          if (canMatchList.length > 0) {
+            route.canMatch = canMatchList;
+          }
+        }
+        const canDeactivateExpr = getProp(optionsArg, "canDeactivate");
+        if (canDeactivateExpr && ts3.isArrayLiteralExpression(canDeactivateExpr)) {
+          for (const el of canDeactivateExpr.elements) {
+            routeCanDeactivate.push(tokenText(el, ctx));
+          }
         }
+        const resolversExpr = getProp(optionsArg, "resolvers");
+        if (resolversExpr && ts3.isObjectLiteralExpression(resolversExpr)) {
+          const resolvers = {};
+          for (const prop of resolversExpr.properties) {
+            if (ts3.isPropertyAssignment(prop)) {
+              const rName = propertyName(prop.name);
+              const init = prop.initializer;
+              if (init)
+                resolvers[rName] = tokenText(init, ctx);
+            }
+          }
+          if (Object.keys(resolvers).length > 0) {
+            route.resolvers = resolvers;
+          }
+        }
+        const redirectToExpr = getProp(optionsArg, "redirectTo");
+        if (redirectToExpr && ts3.isStringLiteral(redirectToExpr)) {
+          route.redirectTo = redirectToExpr.text;
+        }
+        const pathMatchExpr = getProp(optionsArg, "pathMatch");
+        if (pathMatchExpr && ts3.isStringLiteral(pathMatchExpr)) {
+          const val = pathMatchExpr.text;
+          if (val === "full" || val === "prefix") {
+            route.pathMatch = val;
+          }
+        }
+        const titleExpr = getProp(optionsArg, "title");
+        if (titleExpr && ts3.isStringLiteral(titleExpr)) {
+          route.title = titleExpr.text;
+        }
+        const dataExpr = getProp(optionsArg, "data");
+        if (dataExpr && ts3.isObjectLiteralExpression(dataExpr)) {
+          route.data = { ...route.data, ...parseObjectLiteralValues(dataExpr) };
+        }
+        const aspects = parseAspectRefs(getProp(optionsArg, "aspects"), ctx, `route ${httpMethod} ${routePath}`);
+        if (aspects.length > 0)
+          route.aspects = aspects;
+      }
+      if (routeGuards.length > 0) {
+        route.guards = routeGuards;
+      }
+      if (routeCanDeactivate.length > 0) {
+        route.canDeactivate = routeCanDeactivate;
       }
       routes.push(route);
     }
   }
   return {
-    className: decl.getName() ?? "<anonymous>",
+    className: decl.name?.text ?? "<anonymous>",
     path,
     scope: injectable?.scope ?? "request",
     deps,
+    hasOnDestroy: hasDestroyHook(decl) || undefined,
+    optionalDeps: optionalDeps.length > 0 ? optionalDeps : undefined,
+    selfDeps: selfDeps.length > 0 ? selfDeps : undefined,
+    skipSelfDeps: skipSelfDeps.length > 0 ? skipSelfDeps : undefined,
+    hostDeps: hostDeps.length > 0 ? hostDeps : undefined,
+    functionalInjects: functionalInjects.length > 0 ? functionalInjects : undefined,
+    standalone: standalone || undefined,
     routes,
     file,
-    importPath: modulePath(ctx.rootDir, decl.getSourceFile().getFilePath()),
+    importPath: modulePath(ctx.rootDir, decl.getSourceFile().fileName),
     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 = [];
+  const ctor = cls.members.find(ts3.isConstructorDeclaration);
+  const deps = injectable?.deps ? [...injectable.deps] : [];
+  const optionalDeps = [];
+  const selfDeps = [];
+  const skipSelfDeps = [];
+  const hostDeps = [];
+  const functionalInjects = [];
   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;
+  if (!injectable?.deps && ctor && ctor.parameters.length > 0) {
+    const injectParams = parseInjectParams(cls, ctx);
+    const optionalIndices = parseOptionalParams(cls);
+    const selfIndices = parseModifierParams(cls, "Self");
+    const skipSelfIndices = parseModifierParams(cls, "SkipSelf");
+    const hostIndices = parseModifierParams(cls, "Host");
+    ctor.parameters.forEach((param, index) => {
+      const isOptional = optionalIndices.has(index);
+      const injected = injectParams.get(index);
+      const tokenName = injected ?? paramTypeTokenName(param, ctx);
+      if (tokenName) {
+        deps.push(tokenName);
+        if (isOptional)
+          optionalDeps.push(tokenName);
+        if (selfIndices.has(index))
+          selfDeps.push(tokenName);
+        if (skipSelfIndices.has(index))
+          skipSelfDeps.push(tokenName);
+        if (hostIndices.has(index))
+          hostDeps.push(tokenName);
+      } else {
+        if (!isOptional)
+          missing = true;
+      }
+    });
+  }
+  for (const prop of cls.members.filter(ts3.isPropertyDeclaration)) {
+    const init = prop.initializer;
+    if (init && ts3.isCallExpression(init)) {
+      const callName = nodeText(init.expression).split(".").pop();
+      if (callName === "inject") {
+        const [tokenArg, optionsArg] = init.arguments;
+        if (tokenArg) {
+          const tokenName = tokenText(tokenArg, ctx);
+          const unwrappedToken = unwrapForwardRef(tokenArg);
+          const known = ts3.isStringLiteral(unwrappedToken) || ts3.isIdentifier(unwrappedToken) && (ctx.tokensByName.has(tokenName) || ctx.classesByName.has(tokenName));
+          if (!known) {
+            missing = true;
+            continue;
+          }
+          if (!deps.includes(tokenName))
+            deps.push(tokenName);
+          const options = optionsArg && ts3.isObjectLiteralExpression(optionsArg) ? {
+            optional: booleanProp(optionsArg, "optional") ?? false,
+            self: booleanProp(optionsArg, "self") ?? false,
+            skipSelf: booleanProp(optionsArg, "skipSelf") ?? false,
+            host: booleanProp(optionsArg, "host") ?? false
+          } : { optional: false, self: false, skipSelf: false, host: false };
+          if (options.optional && !optionalDeps.includes(tokenName))
+            optionalDeps.push(tokenName);
+          if (options.self && !selfDeps.includes(tokenName))
+            selfDeps.push(tokenName);
+          if (options.skipSelf && !skipSelfDeps.includes(tokenName))
+            skipSelfDeps.push(tokenName);
+          if (options.host && !hostDeps.includes(tokenName))
+            hostDeps.push(tokenName);
+          if (!functionalInjects.some((entry) => entry.token === tokenName)) {
+            functionalInjects.push({
+              token: tokenName,
+              expression: nodeText(unwrappedToken),
+              importPath: ts3.isIdentifier(unwrappedToken) ? (() => {
+                const declaration = resolveDeclaration(unwrappedToken, ctx)[0];
+                return declaration && isProjectSourcePath(declaration.getSourceFile().fileName, ctx.rootDir) ? modulePath(ctx.rootDir, declaration.getSourceFile().fileName) : undefined;
+              })() : undefined,
+              importModule: ts3.isIdentifier(unwrappedToken) ? (() => {
+                const declaration = resolveDeclaration(unwrappedToken, ctx)[0];
+                return declaration && !isProjectSourcePath(declaration.getSourceFile().fileName, ctx.rootDir) ? importModuleOf(unwrappedToken, ctx) : undefined;
+              })() : undefined,
+              ...options
+            });
+          }
+        }
+      }
     }
-  });
-  return { deps, missing };
+  }
+  return { deps, optionalDeps, selfDeps, skipSelfDeps, hostDeps, functionalInjects, missing };
 }
 function paramTypeTokenName(param, ctx) {
-  const typeNode = param.getTypeNode();
+  const typeNode = param.type;
   if (!typeNode)
     return;
-  const text = typeNode.getText().replace(/<.*>$/, "").replace(/\[\]$/, "").trim();
+  const text = nodeText(typeNode).replace(/<.*>$/, "").replace(/\[\]$/, "").trim();
   if (ctx.classesByName.has(text))
     return text;
   if (ctx.tokensByName.has(text))
@@ -455,37 +1756,85 @@ function parseInjectableOptions(cls, ctx) {
   if (!obj)
     return {};
   const scope = stringLiteralProp(obj, "scope");
+  const providedIn = stringLiteralProp(obj, "providedIn");
   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
+    scope: scope && isScope(scope) ? scope : undefined,
+    providedIn: providedIn === "root" ? "root" : undefined,
+    deps: depsExpr ? arrayProp(obj, "deps").map((el) => ctx ? tokenNameOf(el, ctx).name : nodeText(el)) : undefined
   };
 }
-function parseInjectParams(cls) {
+function parseInjectParams(cls, ctx) {
   const result = new Map;
-  const ctor = cls.getConstructors()[0];
+  const ctor = cls.members.find(ts3.isConstructorDeclaration);
   if (!ctor)
     return result;
-  ctor.getParameters().forEach((param, index) => {
-    for (const dec of param.getDecorators()) {
-      if (decoratorName(dec) !== "Inject")
+  ctor.parameters.forEach((param, index) => {
+    for (const dec of decoratorsOf(param)) {
+      if (decoratorName2(dec) !== "Inject")
         continue;
-      const arg = dec.getArguments()[0];
+      const arg = decoratorArguments(dec)[0];
       if (arg)
-        result.set(index, tokenText(arg));
+        result.set(index, tokenText(arg, ctx));
+    }
+  });
+  return result;
+}
+function parseOptionalParams(cls) {
+  const result = new Set;
+  const ctor = cls.members.find(ts3.isConstructorDeclaration);
+  if (!ctor)
+    return result;
+  ctor.parameters.forEach((param, index) => {
+    for (const dec of decoratorsOf(param)) {
+      if (decoratorName2(dec) === "Optional")
+        result.add(index);
+    }
+    if (param.questionToken)
+      result.add(index);
+  });
+  return result;
+}
+function parseModifierParams(cls, modifierName) {
+  const result = new Set;
+  const ctor = cls.members.find(ts3.isConstructorDeclaration);
+  if (!ctor)
+    return result;
+  ctor.parameters.forEach((param, index) => {
+    for (const dec of decoratorsOf(param)) {
+      if (decoratorName2(dec) === modifierName)
+        result.add(index);
     }
   });
   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();
+function unwrapForwardRef(expr) {
+  if (ts3.isCallExpression(expr)) {
+    const exprText = nodeText(expr.expression);
+    if (exprText === "forwardRef" || exprText.endsWith(".forwardRef")) {
+      const arg = expr.arguments[0];
+      if (arg && (ts3.isArrowFunction(arg) || ts3.isFunctionExpression(arg))) {
+        const body = arg.body;
+        if (body && ts3.isExpression(body)) {
+          return unwrapForwardRef(body);
+        }
+      }
+    }
+  }
+  return expr;
+}
+function tokenText(expr, ctx) {
+  const unwrapped = unwrapForwardRef(expr);
+  if (ts3.isStringLiteral(unwrapped))
+    return unwrapped.text;
+  if (ts3.isIdentifier(unwrapped)) {
+    const decl = resolveDeclaration(unwrapped, ctx)[0];
+    if (decl && ts3.isClassDeclaration(decl))
+      return decl.name?.text ?? unwrapped.text;
+    if (decl && ts3.isVariableDeclaration(decl))
+      return variableName(decl);
   }
-  return expr.getText();
+  return nodeText(unwrapped);
 }
 function resolveScope(input, ctx) {
   if (input.explicit)
@@ -501,88 +1850,252 @@ function resolveScope(input, ctx) {
   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" };
+  const unwrapped = unwrapForwardRef(expr);
+  if (ts3.isIdentifier(unwrapped)) {
+    const decl = resolveDeclaration(unwrapped, ctx)[0];
+    if (decl && ts3.isClassDeclaration(decl)) {
+      return { name: decl.name?.text ?? nodeText(expr), kind: "class" };
     }
-    if (decl && Node.isVariableDeclaration(decl)) {
-      const name = decl.getName();
+    if (decl && ts3.isVariableDeclaration(decl)) {
+      const name = variableName(decl);
       return { name, kind: ctx.tokensByName.has(name) ? "injection-token" : "class" };
     }
-    if (ctx.tokensByName.has(expr.getText())) {
-      return { name: expr.getText(), kind: "injection-token" };
+    if (ctx.tokensByName.has(unwrapped.text)) {
+      return { name: unwrapped.text, kind: "injection-token" };
     }
   }
-  return { name: expr.getText(), kind: "class" };
+  return { name: nodeText(expr), kind: "class" };
 }
-function resolveDeclaration(id) {
-  let symbol = id.getSymbol();
+function resolveDeclaration(id, ctx) {
+  let symbol = ctx.checker.getSymbolAtLocation(id);
   if (!symbol)
     return [];
-  let declarations = symbol.getDeclarations();
+  let declarations = symbol.declarations ?? [];
   for (let guard = 0;guard < 4; guard += 1) {
-    const isAlias = declarations.some((d) => Node.isImportSpecifier(d) || Node.isImportClause(d) || Node.isNamespaceImport(d));
+    const isAlias = declarations.some((d) => ts3.isImportSpecifier(d) || ts3.isImportClause(d) || ts3.isNamespaceImport(d));
     if (!isAlias)
       break;
-    const aliased = symbol.getAliasedSymbol();
-    if (!aliased)
+    if (!(symbol.flags & ts3.SymbolFlags.Alias))
       break;
+    const aliased = ctx.checker.getAliasedSymbol(symbol);
     symbol = aliased;
-    declarations = aliased.getDeclarations();
+    declarations = aliased.declarations ?? [];
   }
   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];
+  const decl = resolveDeclaration(id, ctx)[0];
   if (decl)
-    return modulePath(ctx.rootDir, decl.getSourceFile().getFilePath());
+    return modulePath(ctx.rootDir, decl.getSourceFile().fileName);
+  return;
+}
+function importModuleOf(id, ctx) {
+  const symbol = ctx.checker.getSymbolAtLocation(id);
+  const declarations = symbol?.declarations ?? [];
+  for (const declaration of declarations) {
+    let current = declaration;
+    while (current) {
+      if (ts3.isImportDeclaration(current)) {
+        const moduleSpecifier = current.moduleSpecifier;
+        return ts3.isStringLiteral(moduleSpecifier) ? moduleSpecifier.text : undefined;
+      }
+      current = current.parent;
+    }
+  }
   return;
 }
 function findDecorator(cls, name) {
-  return cls.getDecorators().find((dec) => decoratorName(dec) === name);
+  return decoratorsOf(cls).find((dec) => decoratorName2(dec) === name);
 }
-function decoratorName(dec) {
-  const expr = dec.getExpression();
-  if (Node.isCallExpression(expr)) {
-    return expr.getExpression().getText().split(".").pop();
+function decoratorName2(dec) {
+  const expr = dec.expression;
+  if (ts3.isCallExpression(expr)) {
+    return nodeText(expr.expression).split(".").pop();
+  }
+  if (ts3.isIdentifier(expr))
+    return expr.text;
+  return;
+}
+function decoratorObjectArg(dec) {
+  const expr = dec.expression;
+  if (!ts3.isCallExpression(expr))
+    return;
+  const arg = expr.arguments[0];
+  return arg && ts3.isObjectLiteralExpression(arg) ? arg : undefined;
+}
+function getProp(obj, name) {
+  const prop = obj.properties.find((item) => (ts3.isPropertyAssignment(item) || ts3.isShorthandPropertyAssignment(item)) && propertyName(item.name) === name);
+  if (!prop)
+    return;
+  if (ts3.isPropertyAssignment(prop))
+    return prop.initializer;
+  if (ts3.isShorthandPropertyAssignment(prop))
+    return prop.name;
+  return;
+}
+function toCompilerDiagnostic(diagnostic, rootDir) {
+  const file = diagnostic.file;
+  const position = file && diagnostic.start !== undefined ? file.getLineAndCharacterOfPosition(diagnostic.start) : undefined;
+  return {
+    severity: diagnostic.category === ts3.DiagnosticCategory.Error ? "error" : "warn",
+    code: `typescript-${diagnostic.code}`,
+    errorCode: `TS${diagnostic.code}`,
+    message: ts3.flattenDiagnosticMessageText(diagnostic.messageText, `
+`),
+    file: file ? sourcePath(rootDir, file.fileName) : undefined,
+    line: position ? position.line + 1 : undefined
+  };
+}
+function stringLiteralProp(obj, name) {
+  const expr = getProp(obj, name);
+  return expr && ts3.isStringLiteral(expr) ? expr.text : undefined;
+}
+function arrayProp(obj, name) {
+  const expr = getProp(obj, name);
+  return expr && ts3.isArrayLiteralExpression(expr) ? [...expr.elements] : [];
+}
+function parseAspectRefs(expression, ctx, owner) {
+  if (!expression)
+    return [];
+  if (!ts3.isArrayLiteralExpression(expression)) {
+    ctx.diagnostics.push({
+      severity: "error",
+      code: "dynamic-aspect-reference",
+      message: `${owner} 的 aspects 必须是显式数组字面量，并且每一项必须是可解析的函数引用`,
+      file: sourcePath(ctx.rootDir, expression.getSourceFile().fileName),
+      line: lineOf(expression),
+      suggestion: "使用 aspects: [auditAspect, transactionAspect]，不要使用变量、调用表达式或字符串 pointcut。",
+      errorCode: "SC4010",
+      docsUrl: "https://supacloud.dev/errors/SC4010"
+    });
+    return [];
+  }
+  const refs = [];
+  for (const element of expression.elements) {
+    if (ts3.isSpreadElement(element) || !ts3.isIdentifier(element)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        code: "dynamic-aspect-reference",
+        message: `${owner} 的 aspects 只能包含显式的函数标识符引用，无法静态编译 '${nodeText(element)}'`,
+        file: sourcePath(ctx.rootDir, element.getSourceFile().fileName),
+        line: lineOf(element),
+        suggestion: "将 aspect 直接写入数组，例如 aspects: [auditAspect]。",
+        errorCode: "SC4010",
+        docsUrl: "https://supacloud.dev/errors/SC4010"
+      });
+      continue;
+    }
+    const declaration = resolveDeclaration(element, ctx).find((candidate) => ts3.isFunctionDeclaration(candidate) || ts3.isVariableDeclaration(candidate) && candidate.initializer !== undefined && (ts3.isArrowFunction(candidate.initializer) || ts3.isFunctionExpression(candidate.initializer)));
+    if (!declaration) {
+      ctx.diagnostics.push({
+        severity: "error",
+        code: "invalid-aspect-reference",
+        message: `${owner} 引用了 '${element.text}'，但它不是可静态解析的 aspect 函数`,
+        file: sourcePath(ctx.rootDir, element.getSourceFile().fileName),
+        line: lineOf(element),
+        suggestion: "aspect 必须是函数声明、箭头函数或函数表达式的直接引用。",
+        errorCode: "SC4011",
+        docsUrl: "https://supacloud.dev/errors/SC4011"
+      });
+      continue;
+    }
+    const name = ts3.isFunctionDeclaration(declaration) ? declaration.name?.text : ts3.isVariableDeclaration(declaration) ? variableName(declaration) : undefined;
+    if (!name)
+      continue;
+    const declaredFile = declaration.getSourceFile().fileName;
+    const projectLocal = isProjectSourcePath(declaredFile, ctx.rootDir);
+    refs.push({
+      name,
+      expression: element.text,
+      importPath: projectLocal ? modulePath(ctx.rootDir, declaredFile) : undefined,
+      importModule: projectLocal ? undefined : importModuleOf(element, ctx)
+    });
   }
-  if (Node.isIdentifier(expr))
-    return expr.getText();
-  return;
+  return refs;
 }
-function decoratorObjectArg(dec) {
-  const expr = dec.getExpression();
-  if (!Node.isCallExpression(expr))
+function booleanProp(obj, name) {
+  const expr = getProp(obj, name);
+  if (!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();
+  if (expr.kind === ts3.SyntaxKind.TrueKeyword)
+    return true;
+  if (expr.kind === ts3.SyntaxKind.FalseKeyword)
+    return false;
   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;
+  return scope && isScope(scope) ? scope : undefined;
+}
+function parseBindingOptions(args, defaultName) {
+  let name = defaultName;
+  let transform;
+  let defaultValue;
+  const first = args[0];
+  const second = args[1];
+  if (first && ts3.isStringLiteral(first)) {
+    name = first.text;
+  } else if (first && ts3.isObjectLiteralExpression(first)) {
+    const nameProp = getProp(first, "name");
+    if (nameProp && ts3.isStringLiteral(nameProp)) {
+      name = nameProp.text;
+    }
+    const trProp = getProp(first, "transform");
+    if (trProp && ts3.isStringLiteral(trProp)) {
+      const val = trProp.text;
+      if (val === "number" || val === "boolean" || val === "string") {
+        transform = val;
+      }
+    }
+    const defProp = getProp(first, "default");
+    if (defProp) {
+      defaultValue = parseLiteralValue(defProp);
+    }
+  }
+  if (second && ts3.isObjectLiteralExpression(second)) {
+    const trProp = getProp(second, "transform");
+    if (trProp && ts3.isStringLiteral(trProp)) {
+      const val = trProp.text;
+      if (val === "number" || val === "boolean" || val === "string") {
+        transform = val;
+      }
+    }
+    const defProp = getProp(second, "default");
+    if (defProp) {
+      defaultValue = parseLiteralValue(defProp);
+    }
+  }
+  return { name, transform, default: defaultValue };
+}
+function parseLiteralValue(node) {
+  if (ts3.isStringLiteral(node))
+    return node.text;
+  if (ts3.isNumericLiteral(node))
+    return Number(node.text);
+  if (node.kind === ts3.SyntaxKind.TrueKeyword)
+    return true;
+  if (node.kind === ts3.SyntaxKind.FalseKeyword)
+    return false;
+  if (ts3.isArrayLiteralExpression(node)) {
+    return node.elements.map(parseLiteralValue);
+  }
+  if (ts3.isObjectLiteralExpression(node)) {
+    return parseObjectLiteralValues(node);
+  }
+  return;
+}
+function parseObjectLiteralValues(obj) {
+  const result = {};
+  for (const prop of obj.properties) {
+    if (ts3.isPropertyAssignment(prop)) {
+      const name = propertyName(prop.name);
+      const init = prop.initializer;
+      if (init) {
+        result[name] = parseLiteralValue(init);
+      }
+    }
+  }
+  return result;
 }
 function modulePath(rootDir, absFile) {
   return sourcePath(rootDir, absFile).replace(/\.(ts|tsx|js|mts|cts)$/, "");
@@ -594,7 +2107,8 @@ 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 { createHash as createHash4 } from "node:crypto";
+import { access, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
 
 // src/util.ts
@@ -627,6 +2141,28 @@ function isRequestContextToken(token, tokenNames) {
 function isJobContextToken(token, tokenNames) {
   return token === "JOB_CONTEXT" || tokenNames?.[token] === JOB_CONTEXT_TOKEN_NAME;
 }
+function joinRoutePaths(prefix, path) {
+  const joined = `${prefix}/${path}`.replace(/\/{2,}/g, "/");
+  const normalized = joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
+  return normalized;
+}
+function findClosestMatch(target, candidates) {
+  if (candidates.length === 0)
+    return;
+  if (candidates.length === 1)
+    return candidates[0];
+  const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+  const targetNorm = norm(target);
+  for (const c of candidates) {
+    if (norm(c) === targetNorm)
+      return c;
+  }
+  for (const c of candidates) {
+    if (norm(c).includes(targetNorm) || targetNorm.includes(norm(c)))
+      return c;
+  }
+  return candidates[0];
+}
 
 // src/generate.ts
 var HEADER = "// GENERATED BY @supacloud/compiler — do not edit";
@@ -639,6 +2175,29 @@ var INTERFACES = `export interface CompiledRoute {
   query?: unknown;
   response?: unknown;
   command?: string;
+  guards?: string[];
+  canMatch?: string[];
+  canDeactivate?: string[];
+  resolvers?: Record<string, string>;
+  redirectTo?: string;
+  pathMatch?: "full" | "prefix";
+  paramTransforms?: Record<string, "number" | "boolean" | "string">;
+  paramDefaults?: Record<string, unknown>;
+  queryTransforms?: Record<string, "number" | "boolean" | "string">;
+  queryDefaults?: Record<string, unknown>;
+  title?: string;
+  data?: Record<string, unknown>;
+  aspects?: CompiledAspect[];
+  invoker?: (
+    controller: unknown,
+    request: {
+      params?: Record<string, unknown>;
+      query?: Record<string, unknown>;
+      body?: unknown;
+      headers?: Record<string, unknown>;
+      context?: unknown;
+    },
+  ) => Promise<unknown> | unknown;
 }
 
 export interface CompiledCommand {
@@ -648,8 +2207,34 @@ export interface CompiledCommand {
   transaction: "required" | "none";
   audit?: string;
   idempotency: "required" | "none";
+  standalone?: boolean;
+  aspects?: CompiledAspect[];
+}
+
+export interface CompiledJob {
+  className: string;
+  name: string;
+  serviceKey: string;
+  scope: "application" | "request" | "job";
+  aspects?: CompiledAspect[];
+}
+
+export interface CompiledAspectContext {
+  kind: "route" | "command" | "job";
+  name: string;
+  input: unknown;
+  request?: Request;
+  requestContext?: unknown;
+  scope?: Record<string, unknown>;
+  services?: Record<string, unknown>;
+  metadata?: unknown;
 }
 
+export type CompiledAspect = (
+  context: CompiledAspectContext,
+  next: () => unknown | Promise<unknown>,
+) => unknown | Promise<unknown>;
+
 export interface CompiledController {
   path: string;
   serviceKey: string;
@@ -668,16 +2253,102 @@ export interface CompiledModule {
     ctx: unknown,
     imported?: Record<string, Record<string, unknown>>,
   ): Record<string, unknown>;
+  destroyRequestScope?(scope: Record<string, unknown>): Promise<void>;
   createJobScope?(
     services: Record<string, unknown>,
     ctx: unknown,
     imported?: Record<string, Record<string, unknown>>,
   ): Record<string, unknown>;
+  destroyJobScope?(scope: Record<string, unknown>): Promise<void>;
   controllers: CompiledController[];
   commands: CompiledCommand[];
+  jobs: CompiledJob[];
+  aspects?: CompiledAspect[];
+}`;
+var TYPE_GUARDS = `function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isFunction(value: unknown): value is (...args: unknown[]) => unknown {
+  return typeof value === "function";
+}
+
+function resolveFactoryValue(value: unknown): unknown {
+  if (!isRecord(value) || !isFunction(value.factory)) return undefined;
+  return value.factory();
+}
+
+const scopeDestructions = new WeakMap<object, Promise<void>>();
+
+function destroyScopeInstances(
+  scope: Record<string, unknown>,
+  plan: readonly { key: string; index?: number }[],
+): Promise<void> {
+  const pending = scopeDestructions.get(scope);
+  if (pending) return pending;
+  const destruction = Promise.resolve().then(async () => {
+    const errors: unknown[] = [];
+    const seen = new Set<unknown>();
+    for (const entry of [...plan].reverse()) {
+      const value = scope[entry.key];
+      const instance = entry.index === undefined ? value
+        : Array.isArray(value) ? value[entry.index] : undefined;
+      if (seen.has(instance)) continue;
+      seen.add(instance);
+      try {
+        if (isRecord(instance) && isFunction(instance.onDestroy)) {
+          await instance.onDestroy();
+        } else if (isRecord(instance) && isFunction(instance.ngOnDestroy)) {
+          await instance.ngOnDestroy();
+        }
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length > 0) throw new AggregateError(errors, "Scope destruction failed");
+  });
+  scopeDestructions.set(scope, destruction);
+  return destruction;
 }`;
 function renderApplication(graph, options) {
-  const modules = topoSortModules(graph.modules);
+  let modules = topoSortModules(graph.modules);
+  if (options.treeShakeUnusedProviders) {
+    const referencedTokens = new Set;
+    for (const mod of graph.modules) {
+      for (const exp of mod.exports)
+        referencedTokens.add(exp);
+      for (const ctrl of mod.controllers) {
+        for (const d of ctrl.deps)
+          referencedTokens.add(d);
+        for (const d of ctrl.optionalDeps ?? [])
+          referencedTokens.add(d);
+        for (const d of ctrl.selfDeps ?? [])
+          referencedTokens.add(d);
+        for (const d of ctrl.skipSelfDeps ?? [])
+          referencedTokens.add(d);
+        for (const d of ctrl.hostDeps ?? [])
+          referencedTokens.add(d);
+      }
+      for (const p of mod.providers) {
+        for (const d of p.deps ?? [])
+          referencedTokens.add(d);
+        for (const d of p.optionalDeps ?? [])
+          referencedTokens.add(d);
+        for (const d of p.selfDeps ?? [])
+          referencedTokens.add(d);
+        for (const d of p.skipSelfDeps ?? [])
+          referencedTokens.add(d);
+        for (const d of p.hostDeps ?? [])
+          referencedTokens.add(d);
+        if (p.useExisting)
+          referencedTokens.add(p.useExisting);
+      }
+    }
+    modules = modules.map((mod) => ({
+      ...mod,
+      providers: mod.providers.filter((p) => p.providedIn !== "root" || p.multi || referencedTokens.has(p.token) || p.exported)
+    }));
+  }
   const imports = new ImportManager;
   const factorySections = [];
   const descriptorEntries = [];
@@ -693,12 +2364,46 @@ function renderApplication(graph, options) {
     ...imports.size > 0 ? [""] : [],
     INTERFACES,
     "",
+    TYPE_GUARDS,
+    "",
     "export function createCompiledModules(): CompiledModule[] {",
     "  return [",
     ...descriptorEntries.map((entry) => indent(entry, 4) + ","),
     "  ];",
     "}",
     "",
+    "export async function initializeApplication(services: Record<string, unknown>): Promise<void> {",
+    '  const initializers = [services.environmentInitializer ?? services["supacloud.environment-initializer"], services.appInitializer ?? services["supacloud.app-initializer"]];',
+    "  for (const group of initializers) {",
+    "    if (Array.isArray(group)) {",
+    "      for (const init of group) {",
+    "        if (isFunction(init)) await init();",
+    "      }",
+    "    } else if (isFunction(group)) {",
+    "      await group();",
+    "    }",
+    "  }",
+    "}",
+    "",
+    "export async function destroyApplication(services: Record<string, unknown>): Promise<void> {",
+    '  const destroyRef = services.destroyRef ?? services["supacloud.destroy-ref"];',
+    "  if (isRecord(destroyRef) && isFunction(destroyRef.destroy)) {",
+    "    await destroyRef.destroy();",
+    "  } else if (isRecord(destroyRef) && Array.isArray(destroyRef._teardowns)) {",
+    "    for (const teardown of [...destroyRef._teardowns].reverse()) {",
+    "      if (isFunction(teardown)) await teardown();",
+    "    }",
+    "  }",
+    "  const instances = Object.values(services);",
+    "  for (const inst of instances.reverse()) {",
+    "    if (isRecord(inst) && isFunction(inst.onDestroy)) {",
+    "      await inst.onDestroy();",
+    "    } else if (isRecord(inst) && isFunction(inst.ngOnDestroy)) {",
+    "      await inst.ngOnDestroy();",
+    "    }",
+    "  }",
+    "}",
+    "",
     ...factorySections,
     ""
   ].join(`
@@ -708,10 +2413,14 @@ function renderApplication(graph, options) {
     modules: graph.modules,
     externalTokens: graph.externalTokens
   };
+  const clientCode = options.generateClient ? renderClient(graph, options) : undefined;
+  const permissionsCode = options.generatePermissions ? renderPermissions(graph) : undefined;
   return {
     applicationCode: code,
     manifestJson: JSON.stringify(manifest, null, 2) + `
-`
+`,
+    clientCode,
+    permissionsCode
   };
 }
 async function generateApplication(graph, options) {
@@ -719,9 +2428,50 @@ async function generateApplication(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];
+  const written = [];
+  if (await writeFileIfChanged(applicationPath, rendered.applicationCode, options.artifactHashes)) {
+    written.push(applicationPath);
+  }
+  if (await writeFileIfChanged(manifestPath, rendered.manifestJson, options.artifactHashes)) {
+    written.push(manifestPath);
+  }
+  if (rendered.clientCode) {
+    const clientPath = join2(options.outDir, "client.ts");
+    if (await writeFileIfChanged(clientPath, rendered.clientCode, options.artifactHashes)) {
+      written.push(clientPath);
+    }
+  }
+  if (rendered.permissionsCode) {
+    const permissionsPath = join2(options.outDir, "permissions.ts");
+    if (await writeFileIfChanged(permissionsPath, rendered.permissionsCode, options.artifactHashes)) {
+      written.push(permissionsPath);
+    }
+  }
+  return written;
+}
+async function writeFileIfChanged(path, content, hashes) {
+  const hash = createHash4("sha1").update(content).digest("hex");
+  if (hashes?.get(path) === hash) {
+    try {
+      await access(path);
+      return false;
+    } catch {}
+  }
+  await writeFileAtomic(path, content);
+  hashes?.set(path, hash);
+  return true;
+}
+async function writeFileAtomic(path, content) {
+  const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  try {
+    await writeFile(temporaryPath, content, "utf8");
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => {
+      return;
+    });
+    throw error;
+  }
 }
 function factoryOfScope(scope) {
   return scope === "application" ? "services" : scope;
@@ -761,11 +2511,13 @@ class ImportManager {
   get size() {
     return this.entries.size;
   }
-  add(exported, importPath) {
-    if (!importPath)
+  add(exported, importPath, importModule) {
+    const path = importModule ?? importPath;
+    const packageImport = importModule !== undefined;
+    if (!path)
       return exported;
     for (const [local2, entry] of this.entries) {
-      if (entry.path === importPath && entry.exported === exported)
+      if (entry.path === path && entry.exported === exported && entry.package === packageImport)
         return local2;
     }
     let local = exported;
@@ -774,18 +2526,18 @@ class ImportManager {
       local = `${exported}${counter}`;
       counter += 1;
     }
-    this.entries.set(local, { path: importPath, exported });
+    this.entries.set(local, { path, exported, package: packageImport });
     return local;
   }
   render(rootDir, outDir) {
     const byPath = new Map;
     for (const [local, entry] of this.entries) {
-      const list = byPath.get(entry.path) ?? [];
+      const spec = entry.package ? entry.path : relativeImportPath(outDir, join2(rootDir, `${entry.path}.ts`));
+      const list = byPath.get(spec) ?? [];
       list.push({ exported: entry.exported, local });
-      byPath.set(entry.path, list);
+      byPath.set(spec, list);
     }
-    return [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([path, symbols]) => {
-      const spec = relativeImportPath(outDir, join2(rootDir, `${path}.ts`));
+    return [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([spec, symbols]) => {
       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}";`;
     });
@@ -807,14 +2559,19 @@ class ModuleGenerator {
     this.module = module;
     this.imports = imports;
     this.pascal = pascalName(module.name);
+    if (module.providers.some((provider) => (provider.functionalInjects?.length ?? 0) > 0) || module.controllers.some((controller) => (controller.functionalInjects?.length ?? 0) > 0)) {
+      imports.add("runInInjectionContext", undefined, "@supacloud/app");
+    }
   }
   renderFactories() {
     const sections = [this.renderServicesFactory()];
     if (this.hasFactoryContent("request")) {
       sections.push(this.renderScopeFactory("request"));
+      sections.push(this.renderScopeDestroyer("request"));
     }
     if (this.hasFactoryContent("job")) {
       sections.push(this.renderScopeFactory("job"));
+      sections.push(this.renderScopeDestroyer("job"));
     }
     return sections;
   }
@@ -826,12 +2583,18 @@ class ModuleGenerator {
     ];
     if (this.hasFactoryContent("request")) {
       lines.push(`  createRequestScope: create${this.pascal}RequestScope,`);
+      lines.push(`  destroyRequestScope: destroy${this.pascal}RequestScope,`);
     }
     if (this.hasFactoryContent("job")) {
       lines.push(`  createJobScope: create${this.pascal}JobScope,`);
+      lines.push(`  destroyJobScope: destroy${this.pascal}JobScope,`);
     }
     lines.push(`  controllers: ${this.renderControllers()},`);
-    lines.push(`  commands: ${JSON.stringify(this.module.commands)},`);
+    lines.push(`  commands: ${this.renderCommands()},`);
+    lines.push(`  jobs: ${this.renderJobs()},`);
+    if (this.module.aspects && this.module.aspects.length > 0) {
+      lines.push(`  aspects: ${this.renderAspects(this.module.aspects)},`);
+    }
     lines.push(`}`);
     return lines.join(`
 `);
@@ -858,6 +2621,84 @@ class ModuleGenerator {
         }
         if (route.command)
           fields.push(`command: ${JSON.stringify(route.command)}`);
+        if (route.guards && route.guards.length > 0) {
+          fields.push(`guards: ${JSON.stringify(route.guards)}`);
+        }
+        if (route.canMatch && route.canMatch.length > 0) {
+          fields.push(`canMatch: ${JSON.stringify(route.canMatch)}`);
+        }
+        if (route.canDeactivate && route.canDeactivate.length > 0) {
+          fields.push(`canDeactivate: ${JSON.stringify(route.canDeactivate)}`);
+        }
+        if (route.resolvers && Object.keys(route.resolvers).length > 0) {
+          fields.push(`resolvers: ${JSON.stringify(route.resolvers)}`);
+        }
+        if (route.redirectTo) {
+          fields.push(`redirectTo: ${JSON.stringify(route.redirectTo)}`);
+        }
+        if (route.pathMatch) {
+          fields.push(`pathMatch: ${JSON.stringify(route.pathMatch)}`);
+        }
+        if (route.paramTransforms && Object.keys(route.paramTransforms).length > 0) {
+          fields.push(`paramTransforms: ${JSON.stringify(route.paramTransforms)}`);
+        }
+        if (route.paramDefaults && Object.keys(route.paramDefaults).length > 0) {
+          fields.push(`paramDefaults: ${JSON.stringify(route.paramDefaults)}`);
+        }
+        if (route.queryTransforms && Object.keys(route.queryTransforms).length > 0) {
+          fields.push(`queryTransforms: ${JSON.stringify(route.queryTransforms)}`);
+        }
+        if (route.queryDefaults && Object.keys(route.queryDefaults).length > 0) {
+          fields.push(`queryDefaults: ${JSON.stringify(route.queryDefaults)}`);
+        }
+        if (route.title) {
+          fields.push(`title: ${JSON.stringify(route.title)}`);
+        }
+        if (route.data && Object.keys(route.data).length > 0) {
+          fields.push(`data: ${JSON.stringify(route.data)}`);
+        }
+        if (route.aspects && route.aspects.length > 0) {
+          fields.push(`aspects: ${this.renderAspects(route.aspects)}`);
+        }
+        const invokerArgs = (route.handlerParams ?? []).map((hp) => {
+          if (hp.kind === "param") {
+            const accessor = `req.params?.[${JSON.stringify(hp.bindingName ?? hp.name)}]`;
+            const fallback = hp.default !== undefined ? JSON.stringify(hp.default) : "undefined";
+            if (hp.transform === "number") {
+              return `(${accessor} !== undefined ? Number(${accessor}) : ${fallback})`;
+            }
+            if (hp.transform === "boolean") {
+              return `(${accessor} !== undefined ? Boolean(${accessor}) : ${fallback})`;
+            }
+            if (hp.transform === "string") {
+              return `(${accessor} !== undefined ? String(${accessor}) : ${fallback})`;
+            }
+            return `(${accessor} !== undefined ? ${accessor} : ${fallback})`;
+          }
+          if (hp.kind === "query") {
+            const accessor = `req.query?.[${JSON.stringify(hp.bindingName ?? hp.name)}]`;
+            const fallback = hp.default !== undefined ? JSON.stringify(hp.default) : "undefined";
+            if (hp.transform === "number") {
+              return `(${accessor} !== undefined ? Number(${accessor}) : ${fallback})`;
+            }
+            if (hp.transform === "boolean") {
+              return `(${accessor} !== undefined ? Boolean(${accessor}) : ${fallback})`;
+            }
+            if (hp.transform === "string") {
+              return `(${accessor} !== undefined ? String(${accessor}) : ${fallback})`;
+            }
+            return `(${accessor} !== undefined ? ${accessor} : ${fallback})`;
+          }
+          if (hp.kind === "body")
+            return "req.body";
+          if (hp.kind === "headers")
+            return "req.headers";
+          if (hp.kind === "context")
+            return "(req.context ?? req)";
+          return "undefined";
+        });
+        const callArgs = invokerArgs.length > 0 ? invokerArgs.join(", ") : "req";
+        fields.push(`invoker: async (ctrl: unknown, req: { params?: Record<string, unknown>; query?: Record<string, unknown>; body?: unknown; headers?: Record<string, unknown>; context?: unknown }) => { ` + `if (!isRecord(ctrl)) throw new TypeError("Route controller is not an object"); ` + `const handler = ctrl[${JSON.stringify(route.handler)}]; ` + `if (typeof handler !== "function") throw new TypeError("Route handler ${route.handler} is not callable"); ` + `return await Reflect.apply(handler, ctrl, [${callArgs}]); }`);
         return `{ ${fields.join(", ")} }`;
       });
       return [
@@ -874,6 +2715,32 @@ class ModuleGenerator {
 ${indent(item, 2)}`).join(",")}
 ]`;
   }
+  renderCommands() {
+    if (this.module.commands.length === 0)
+      return "[]";
+    return `[${this.module.commands.map((command) => {
+      const fields = [
+        `className: ${JSON.stringify(command.className)}`,
+        `name: ${JSON.stringify(command.name)}`,
+        `permission: ${JSON.stringify(command.permission ?? "")}`,
+        `transaction: ${JSON.stringify(command.transaction)}`,
+        ...command.audit ? [`audit: ${JSON.stringify(command.audit)}`] : [],
+        `idempotency: ${JSON.stringify(command.idempotency)}`,
+        ...command.standalone ? ["standalone: true"] : [],
+        ...command.aspects && command.aspects.length > 0 ? [`aspects: ${this.renderAspects(command.aspects)}`] : []
+      ];
+      return `{ ${fields.join(", ")} }`;
+    }).join(", ")}]`;
+  }
+  renderJobs() {
+    const jobs = this.module.jobs ?? [];
+    if (jobs.length === 0)
+      return "[]";
+    return `[${jobs.map((job) => `{ className: ${JSON.stringify(job.className)}, name: ${JSON.stringify(job.name)}, serviceKey: ${JSON.stringify(camelName(job.className))}, scope: ${JSON.stringify(job.scope)},${job.aspects && job.aspects.length > 0 ? ` aspects: ${this.renderAspects(job.aspects)},` : ""} }`).join(", ")}]`;
+  }
+  renderAspects(aspects) {
+    return `[${aspects.map((aspect) => this.imports.add(aspect.name, aspect.importPath, aspect.importModule)).join(", ")}]`;
+  }
   renderServicesFactory() {
     return [
       `function create${this.pascal}Services(`,
@@ -896,6 +2763,30 @@ ${indent(item, 2)}`).join(",")}
       indent(this.renderFactoryBody(kind), 2),
       `}`
     ].join(`
+`);
+  }
+  renderScopeDestroyer(kind) {
+    const suffix = kind === "request" ? "RequestScope" : "JobScope";
+    const plan = [];
+    const multiIndices = new Map;
+    for (const provider of orderProviders(this.module.providers.filter((p) => factoryOfScope(p.scope) === kind))) {
+      const index = provider.multi ? multiIndices.get(provider.token) ?? 0 : undefined;
+      if (index !== undefined)
+        multiIndices.set(provider.token, index + 1);
+      if (provider.kind !== "existing" && provider.hasOnDestroy) {
+        plan.push({ key: camelName(provider.token), index });
+      }
+    }
+    for (const controller of this.module.controllers) {
+      if (factoryOfScope(controller.scope) === kind && controller.hasOnDestroy) {
+        plan.push({ key: camelName(controller.className) });
+      }
+    }
+    return [
+      `async function destroy${this.pascal}${suffix}(scope: Record<string, unknown>): Promise<void> {`,
+      `  await destroyScopeInstances(scope, ${JSON.stringify(plan)});`,
+      `}`
+    ].join(`
 `);
   }
   renderFactoryBody(kind) {
@@ -903,11 +2794,24 @@ ${indent(item, 2)}`).join(",")}
     const controllers = this.module.controllers.filter((c) => factoryOfScope(c.scope) === kind);
     const lines = [];
     const returns = new Map;
+    const multiGroups = 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);
+      if (provider.multi) {
+        const emitted = this.emitProvider(provider, kind, true);
+        if (emitted.constLine)
+          lines.push(emitted.constLine);
+        const list = multiGroups.get(emitted.key) ?? [];
+        list.push(emitted.expr);
+        multiGroups.set(emitted.key, list);
+      } else {
+        const emitted = this.emitProvider(provider, kind, false);
+        if (emitted.constLine)
+          lines.push(emitted.constLine);
+        returns.set(emitted.key, emitted.expr);
+      }
+    }
+    for (const [key, exprs] of multiGroups) {
+      returns.set(key, `[${exprs.join(", ")}]`);
     }
     for (const controller of controllers) {
       const emitted = this.emitController(controller, kind);
@@ -919,37 +2823,80 @@ ${indent(item, 2)}`).join(",")}
     return lines.join(`
 `);
   }
-  emitProvider(provider, kind) {
+  emitProvider(provider, kind, isMulti = false) {
     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 };
+        const useClass = this.imports.add(provider.useClass ?? provider.token, provider.importPath, provider.importModule);
+        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const local = this.localVar(isMulti ? provider.useClass ?? `${provider.token}Item` : provider.token, kind);
+        return {
+          constLine: `const ${local} = ${this.instantiate(useClass, args, kind, provider.functionalInjects)};`,
+          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);
+        const expr = provider.importPath || provider.importModule ? this.imports.add(provider.useValueExpr ?? "undefined", provider.importPath, provider.importModule) : provider.useValueExpr ?? "undefined";
+        const local = this.localVar(isMulti ? `${provider.token}Item` : 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);
+        if (provider.tokenKind === "injection-token" && !provider.useFactoryName) {
+          const tokenIdent = this.imports.add(provider.token, provider.importPath, provider.importModule);
+          const local2 = this.localVar(isMulti ? `${provider.token}Item` : provider.token, kind);
+          const constLine = `const ${local2} = resolveFactoryValue(${tokenIdent});`;
+          return { constLine, key, expr: local2 };
+        }
+        const factory = this.imports.add(provider.useFactoryName ?? "", provider.importPath, provider.importModule);
+        const args = provider.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(provider, dep))).join(", ");
+        const local = this.localVar(isMulti ? provider.useFactoryName ?? `${provider.token}Item` : provider.token, kind);
         return { constLine: `const ${local} = ${factory}(${args});`, key, expr: local };
       }
       case "existing": {
-        return { key, expr: this.depExpr(provider.useExisting ?? provider.token, kind) };
+        return {
+          key,
+          expr: this.depExpr(provider.useExisting ?? provider.token, kind, this.depOptions(provider, provider.useExisting ?? provider.token))
+        };
       }
     }
   }
   emitController(controller, kind) {
     const className = this.imports.add(controller.className, controller.importPath);
-    const args = controller.deps.map((dep) => this.depExpr(dep, kind)).join(", ");
+    const args = controller.deps.map((dep) => this.depExpr(dep, kind, this.depOptions(controller, dep))).join(", ");
     const key = camelName(controller.className);
     const local = this.localVar(controller.className, kind);
-    return { constLine: `const ${local} = new ${className}(${args});`, key, expr: local };
+    return {
+      constLine: `const ${local} = ${this.instantiate(className, args, kind, controller.functionalInjects)};`,
+      key,
+      expr: local
+    };
+  }
+  instantiate(className, args, kind, functionalInjects) {
+    if (!functionalInjects || functionalInjects.length === 0) {
+      return `new ${className}(${args})`;
+    }
+    const clauses = functionalInjects.map((entry) => {
+      const token = this.imports.add(entry.expression, entry.importPath, entry.importModule);
+      const value = this.depExpr(entry.token, kind, {
+        optional: entry.optional,
+        self: entry.self,
+        skipSelf: entry.skipSelf,
+        host: entry.host
+      });
+      return `if (token === ${token}) return ${value} as T;`;
+    });
+    const missing = `if (options?.optional) return undefined; throw new Error("Static inject token not available: " + String(token));`;
+    const injector = [
+      `{`,
+      `get<T>(token: unknown, options?: { optional?: boolean; self?: boolean; skipSelf?: boolean; host?: boolean }): T | undefined {`,
+      ...clauses,
+      missing,
+      `},`,
+      `}`
+    ].join(`
+`);
+    return `runInInjectionContext(${injector}, () => new ${className}(${args}))`;
   }
   localVar(token, kind) {
     const locals = this.locals[kind];
@@ -966,23 +2913,34 @@ ${indent(item, 2)}`).join(",")}
     locals.set(token, local);
     return local;
   }
-  depExpr(token, kind) {
+  depOptions(node, token) {
+    return {
+      optional: node.optionalDeps?.includes(token) ?? false,
+      self: node.selfDeps?.includes(token) ?? false,
+      skipSelf: node.skipSelfDeps?.includes(token) ?? false,
+      host: "hostDeps" in node ? node.hostDeps?.includes(token) ?? false : false
+    };
+  }
+  depExpr(token, kind, options = {}) {
+    const isOptional = options.optional ?? false;
+    const isSelf = options.self ?? false;
+    const isSkipSelf = options.skipSelf ?? false;
     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) {
+    const ownIsLocal = own && factoryOfScope(own.scope) === kind;
+    if (own && ownIsLocal && !isSkipSelf) {
       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)}`;
+      if (own.kind === "existing") {
+        return this.depExpr(own.useExisting ?? token, kind, options);
       }
-      return `services.${camelName(token)}`;
+    }
+    if (isSelf) {
+      return isOptional ? "undefined" : `services.${camelName(token)}`;
     }
     for (const importName of this.module.imports) {
       const imported = this.graph.modules.find((m) => m.name === importName);
@@ -992,9 +2950,20 @@ ${indent(item, 2)}`).join(",")}
         return `imported.${importName}.${camelName(token)}`;
       return `imported.${importName}.${camelName(token)}`;
     }
+    for (const mod of this.graph.modules) {
+      const rootProv = mod.providers.find((p) => p.token === token && p.providedIn === "root");
+      if (rootProv) {
+        return `imported.${mod.name}.${camelName(token)}`;
+      }
+    }
+    if (isOptional && !this.graph.externalTokens.includes(token)) {
+      return "undefined";
+    }
+    if (isSelf)
+      return isOptional ? "undefined" : `services.${camelName(token)}`;
     if (kind === "services")
-      return `deps.${camelName(token)}`;
-    return `services.${camelName(token)}`;
+      return isOptional ? `(deps.${camelName(token)} ?? undefined)` : `deps.${camelName(token)}`;
+    return isOptional ? `(services.${camelName(token)} ?? undefined)` : `services.${camelName(token)}`;
   }
 }
 function orderProviders(providers) {
@@ -1016,6 +2985,226 @@ function orderProviders(providers) {
   }
   return result;
 }
+function renderClient(graph, _options) {
+  const controllerEntries = [];
+  const allRoutes = [];
+  for (const module of graph.modules) {
+    for (const controller of module.controllers) {
+      const controllerKey = camelName(controller.className.replace(/Controller$/, ""));
+      const routeMethods = [];
+      for (const route of controller.routes) {
+        const fullPath = joinRoutePaths(controller.path, route.path);
+        allRoutes.push({
+          method: route.method,
+          path: fullPath,
+          controller: controller.className,
+          handler: route.handler,
+          command: route.command,
+          guards: route.guards,
+          canMatch: route.canMatch,
+          canDeactivate: route.canDeactivate,
+          resolvers: route.resolvers,
+          redirectTo: route.redirectTo,
+          pathMatch: route.pathMatch,
+          paramTransforms: route.paramTransforms,
+          paramDefaults: route.paramDefaults,
+          queryTransforms: route.queryTransforms,
+          queryDefaults: route.queryDefaults,
+          title: route.title,
+          data: route.data
+        });
+        routeMethods.push(`
+    ${route.handler}: (options: {
+      params${route.pathParams && route.pathParams.length > 0 || (fullPath.match(/:([a-zA-Z0-9_]+)/g) ?? []).length > 0 ? "" : "?"}: ${route.pathParams && route.pathParams.length > 0 || (fullPath.match(/:([a-zA-Z0-9_]+)/g) ?? []).length > 0 ? `{ ${(route.pathParams && route.pathParams.length > 0 ? route.pathParams : (fullPath.match(/:([a-zA-Z0-9_]+)/g) ?? []).map((p) => p.slice(1))).map((p) => `${p}: string | number`).join("; ")} }` : "Record<string, string | number>"};
+      query?: Record<string, unknown>;
+      body?: unknown;
+      headers?: Record<string, string>;
+    }${route.pathParams && route.pathParams.length > 0 || (fullPath.match(/:([a-zA-Z0-9_]+)/g) ?? []).length > 0 ? "" : " = {}"}) => request(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}, options),`);
+      }
+      controllerEntries.push(`
+  ${controllerKey}: {${routeMethods.join("")}
+  },`);
+    }
+  }
+  return [
+    HEADER,
+    "",
+    "export interface ClientRequestOptions {",
+    "  params?: Record<string, string | number>;",
+    "  query?: Record<string, unknown>;",
+    "  body?: unknown;",
+    "  headers?: Record<string, string>;",
+    "}",
+    "",
+    "export type HttpInterceptorFn = (",
+    "  req: { method: string; url: string; headers: Record<string, string>; body?: unknown },",
+    "  next: (req: { method: string; url: string; headers: Record<string, string>; body?: unknown }) => Promise<Response>,",
+    ") => Promise<Response>;",
+    "",
+    "export interface ApiClientConfig {",
+    "  baseUrl?: string;",
+    "  fetch?: typeof fetch;",
+    "  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);",
+    "  interceptors?: HttpInterceptorFn[];",
+    "}",
+    "",
+    "export const API_ROUTES = " + JSON.stringify(allRoutes, null, 2) + " as const;",
+    "",
+    "export type AppRoutePath = typeof API_ROUTES[number]['path'];",
+    "",
+    "/**",
+    " * Type-safe URL builder replacing route path parameters and appending query parameters.",
+    " */",
+    "export function buildRouteUrl(",
+    "  path: string,",
+    "  params?: Record<string, string | number>,",
+    "  query?: Record<string, unknown>,",
+    "): string {",
+    "  let url = path;",
+    "  if (params) {",
+    "    for (const [key, value] of Object.entries(params)) {",
+    "      url = url.replace(`:${key}`, encodeURIComponent(String(value)));",
+    "    }",
+    "  }",
+    "  if (query) {",
+    "    const searchParams = new URLSearchParams();",
+    "    for (const [k, v] of Object.entries(query)) {",
+    "      if (v !== undefined && v !== null) searchParams.set(k, String(v));",
+    "    }",
+    "    const qs = searchParams.toString();",
+    '    if (qs) url += (url.includes("?") ? "&" : "?") + qs;',
+    "  }",
+    "  return url;",
+    "}",
+    "",
+    "export function createApiClient(config: ApiClientConfig = {}) {",
+    "  const fetcher = config.fetch ?? globalThis.fetch.bind(globalThis);",
+    '  const baseUrl = (config.baseUrl ?? "").replace(/\\/+$/, "");',
+    "",
+    "  async function request<T = unknown>(",
+    "    method: string,",
+    "    path: string,",
+    "    options: ClientRequestOptions = {},",
+    "  ): Promise<T> {",
+    "    let url = `${baseUrl}${path}`;",
+    "    if (options.params) {",
+    "      for (const [key, value] of Object.entries(options.params)) {",
+    "        url = url.replace(`:${key}`, encodeURIComponent(String(value)));",
+    "      }",
+    "    }",
+    "    if (options.query) {",
+    "      const searchParams = new URLSearchParams();",
+    "      for (const [k, v] of Object.entries(options.query)) {",
+    "        if (v !== undefined && v !== null) searchParams.set(k, String(v));",
+    "      }",
+    "      const qs = searchParams.toString();",
+    '      if (qs) url += (url.includes("?") ? "&" : "?") + qs;',
+    "    }",
+    '    const customHeaders = typeof config.headers === "function" ? await config.headers() : config.headers;',
+    "    const headers: Record<string, string> = {",
+    '      "content-type": "application/json",',
+    "      ...customHeaders,",
+    "      ...options.headers,",
+    "    };",
+    "    const interceptors = config.interceptors ?? [];",
+    "    const executeChain = (",
+    "      index: number,",
+    "      reqPayload: { method: string; url: string; headers: Record<string, string>; body?: unknown },",
+    "    ): Promise<Response> => {",
+    "      if (index < interceptors.length) {",
+    "        return interceptors[index](reqPayload, (nextPayload) => executeChain(index + 1, nextPayload));",
+    "      }",
+    "      return fetcher(reqPayload.url, {",
+    "        method: reqPayload.method,",
+    "        headers: reqPayload.headers,",
+    "        body: reqPayload.body !== undefined ? JSON.stringify(reqPayload.body) : undefined,",
+    "      });",
+    "    };",
+    "    const response = await executeChain(0, { method, url, headers, body: options.body });",
+    "    if (!response.ok) {",
+    "      const errBody = await response.text();",
+    "      throw new Error(`API request failed: ${method} ${path} -> ${response.status} ${errBody}`);",
+    "    }",
+    '    const contentType = response.headers?.get("content-type") ?? "";',
+    '    if (contentType.includes("application/json")) {',
+    "      return response.json() as Promise<T>;",
+    "    }",
+    "    return response.text() as Promise<T>;",
+    "  }",
+    "",
+    "  return {",
+    "    request,",
+    "    buildRouteUrl,",
+    "    routes: API_ROUTES,",
+    ...controllerEntries,
+    "  };",
+    "}",
+    "",
+    "export type ApiClient = ReturnType<typeof createApiClient>;",
+    ""
+  ].join(`
+`);
+}
+function renderPermissions(graph) {
+  const permissions = new Set;
+  const bindings = [];
+  for (const module of graph.modules) {
+    for (const command of module.commands) {
+      if (command.permission)
+        permissions.add(command.permission);
+    }
+    for (const controller of module.controllers) {
+      for (const route of controller.routes) {
+        let perm;
+        if (route.command) {
+          const cmd = module.commands.find((c) => c.className === route.command);
+          perm = cmd?.permission;
+        }
+        if (perm)
+          permissions.add(perm);
+        bindings.push({
+          method: route.method,
+          path: joinRoutePaths(controller.path, route.path),
+          controller: controller.className,
+          handler: route.handler,
+          command: route.command,
+          permission: perm
+        });
+      }
+    }
+  }
+  const sortedPerms = [...permissions].sort();
+  const enumEntries = sortedPerms.map((perm) => {
+    const key = pascalName(perm.replace(/[^A-Za-z0-9]+/g, " "));
+    return `  ${key}: ${JSON.stringify(perm)},`;
+  });
+  return [
+    HEADER,
+    "",
+    "export const AppPermissions = {",
+    ...enumEntries,
+    "} as const;",
+    "",
+    "export type AppPermission = (typeof AppPermissions)[keyof typeof AppPermissions];",
+    "",
+    "export interface RoutePermissionBinding {",
+    "  method: string;",
+    "  path: string;",
+    "  controller: string;",
+    "  handler: string;",
+    "  command?: string;",
+    "  permission?: string;",
+    "}",
+    "",
+    "export const RoutePermissions: RoutePermissionBinding[] = " + JSON.stringify(bindings, null, 2) + ";",
+    "",
+    "export function hasPermission(granted: string[], required: AppPermission | string): boolean {",
+    '  return granted.includes("*") || granted.includes(required);',
+    "}",
+    ""
+  ].join(`
+`);
+}
 
 // src/profiles.ts
 var MODULAR_MONOLITH_RULES = [
@@ -1190,6 +3379,57 @@ var SCOPE_LIFETIME_RANK = {
   request: 1,
   job: 1
 };
+var COMPILER_DIAGNOSTIC_CODES = {
+  "circular-dependency": { code: "SC1001", docsUrl: "https://supacloud.dev/errors/SC1001" },
+  "scope-violation": { code: "SC1002", docsUrl: "https://supacloud.dev/errors/SC1002" },
+  "module-boundary-violation": { code: "SC1003", docsUrl: "https://supacloud.dev/errors/SC1003" },
+  "module-boundary": { code: "SC1003", docsUrl: "https://supacloud.dev/errors/SC1003" },
+  "circular-module-import": { code: "SC1004", docsUrl: "https://supacloud.dev/errors/SC1004" },
+  "orphan-module": { code: "SC1005", docsUrl: "https://supacloud.dev/errors/SC1005" },
+  "invalid-boundary-preset": { code: "SC1006", docsUrl: "https://supacloud.dev/errors/SC1006" },
+  "circular-existing-alias": { code: "SC1007", docsUrl: "https://supacloud.dev/errors/SC1007" },
+  "missing-deps": { code: "SC2001", docsUrl: "https://supacloud.dev/errors/SC2001" },
+  "unresolved-token": { code: "SC2001", docsUrl: "https://supacloud.dev/errors/SC2001" },
+  "duplicate-token": { code: "SC2002", docsUrl: "https://supacloud.dev/errors/SC2002" },
+  "duplicate-module": { code: "SC2002", docsUrl: "https://supacloud.dev/errors/SC2002" },
+  "disallow-controller-direct-db": { code: "SC2003", docsUrl: "https://supacloud.dev/errors/SC2003" },
+  "self-dependency-violation": { code: "SC2004", docsUrl: "https://supacloud.dev/errors/SC2004" },
+  "skip-self-dependency-violation": { code: "SC2005", docsUrl: "https://supacloud.dev/errors/SC2005" },
+  "export-unprovided-token": { code: "SC2006", docsUrl: "https://supacloud.dev/errors/SC2006" },
+  "unresolved-alias-target": { code: "SC2007", docsUrl: "https://supacloud.dev/errors/SC2007" },
+  "self-referencing-alias": { code: "SC2008", docsUrl: "https://supacloud.dev/errors/SC2008" },
+  "shadowed-route": { code: "SC3001", docsUrl: "https://supacloud.dev/errors/SC3001" },
+  "unresolved-route-redirect": { code: "SC3002", docsUrl: "https://supacloud.dev/errors/SC3002" },
+  "circular-route-redirect": { code: "SC3003", docsUrl: "https://supacloud.dev/errors/SC3003" },
+  "invalid-http-method-body": { code: "SC3004", docsUrl: "https://supacloud.dev/errors/SC3004" },
+  "unmatched-route-parameter": { code: "SC3005", docsUrl: "https://supacloud.dev/errors/SC3005" },
+  "missing-route-parameter-binding": { code: "SC3006", docsUrl: "https://supacloud.dev/errors/SC3006" },
+  "duplicate-route": { code: "SC3007", docsUrl: "https://supacloud.dev/errors/SC3007" },
+  "missing-body-schema": { code: "SC3008", docsUrl: "https://supacloud.dev/errors/SC3008" },
+  "unused-route-schema": { code: "SC3009", docsUrl: "https://supacloud.dev/errors/SC3009" },
+  "malformed-route-path": { code: "SC3010", docsUrl: "https://supacloud.dev/errors/SC3010" },
+  "duplicate-path-param": { code: "SC3011", docsUrl: "https://supacloud.dev/errors/SC3011" },
+  "wildcard-not-trailing": { code: "SC3012", docsUrl: "https://supacloud.dev/errors/SC3012" },
+  "invalid-query-param-name": { code: "SC3013", docsUrl: "https://supacloud.dev/errors/SC3013" },
+  "unmatched-path-param-decorator": { code: "SC3014", docsUrl: "https://supacloud.dev/errors/SC3014" },
+  "invalid-query-default-type": { code: "SC3015", docsUrl: "https://supacloud.dev/errors/SC3015" },
+  "disallowed-body-on-get-delete": { code: "SC3016", docsUrl: "https://supacloud.dev/errors/SC3016" },
+  "duplicate-query-param-binding": { code: "SC3017", docsUrl: "https://supacloud.dev/errors/SC3017" },
+  "conflicting-route-method": { code: "SC3018", docsUrl: "https://supacloud.dev/errors/SC3018" },
+  "missing-param-colon": { code: "SC3019", docsUrl: "https://supacloud.dev/errors/SC3019" },
+  "missing-token-factory": { code: "SC2009", docsUrl: "https://supacloud.dev/errors/SC2009" },
+  "provider-type-mismatch": { code: "SC2010", docsUrl: "https://supacloud.dev/errors/SC2010" },
+  "unsupported-provider-helper": { code: "SC2011", docsUrl: "https://supacloud.dev/errors/SC2011" },
+  "command-missing-permission": { code: "SC4001", docsUrl: "https://supacloud.dev/errors/SC4001" },
+  "duplicate-command": { code: "SC4002", docsUrl: "https://supacloud.dev/errors/SC4002" },
+  "route-command-unresolved": { code: "SC4003", docsUrl: "https://supacloud.dev/errors/SC4003" },
+  "command-governance-unsupported": { code: "SC4004", docsUrl: "https://supacloud.dev/errors/SC4004" },
+  "route-command-binding-disabled": { code: "SC4005", docsUrl: "https://supacloud.dev/errors/SC4005" },
+  "command-transaction-readonly": { code: "SC4006", docsUrl: "https://supacloud.dev/errors/SC4006" },
+  "dynamic-aspect-reference": { code: "SC4010", docsUrl: "https://supacloud.dev/errors/SC4010" },
+  "invalid-aspect-reference": { code: "SC4011", docsUrl: "https://supacloud.dev/errors/SC4011" },
+  "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" }
+};
 function validateGraph(graph, options = false) {
   const strict = typeof options === "boolean" ? options : options.strict ?? false;
   const diagnostics = [];
@@ -1201,12 +3441,15 @@ function validateGraph(graph, options = false) {
         rules: options.moduleBoundaries
       });
     } catch (err) {
+      const meta = COMPILER_DIAGNOSTIC_CODES["invalid-boundary-preset"];
       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
+        line: graph.modules[0]?.line,
+        errorCode: meta?.code,
+        docsUrl: meta?.docsUrl
       });
     }
   }
@@ -1218,10 +3461,14 @@ function validateGraph(graph, options = false) {
       }
     }
   }
-  function resolveDep(module, token) {
-    const own = module.providers.find((p) => p.token === token);
-    if (own)
-      return { module, provider: own };
+  function resolveDep(module, token, flags = {}) {
+    if (!flags.skipSelf) {
+      const own = module.providers.find((p) => p.token === token);
+      if (own)
+        return { module, provider: own };
+    }
+    if (flags.self)
+      return;
     for (const importName of module.imports) {
       const imported = graph.modules.find((m) => m.name === importName);
       if (!imported || !imported.exports.includes(token))
@@ -1230,17 +3477,43 @@ function validateGraph(graph, options = false) {
       if (provider)
         return { module: imported, provider };
     }
+    for (const mod of graph.modules) {
+      const rootProvider = mod.providers.find((p) => p.token === token && p.providedIn === "root");
+      if (rootProvider)
+        return { module: mod, provider: rootProvider };
+    }
     return;
   }
-  const error = (code, message, file, line) => {
-    diagnostics.push({ severity: "error", code, message, file, line });
+  const error = (code, message, file, line, suggestion) => {
+    const meta = COMPILER_DIAGNOSTIC_CODES[code];
+    diagnostics.push({
+      severity: "error",
+      code,
+      message,
+      file,
+      line,
+      suggestion,
+      errorCode: meta?.code,
+      docsUrl: meta?.docsUrl
+    });
   };
-  const warn2 = (code, message, file, line) => {
-    diagnostics.push({ severity: strict ? "error" : "warn", code, message, file, line });
+  const warn2 = (code, message, file, line, suggestion) => {
+    const meta = COMPILER_DIAGNOSTIC_CODES[code];
+    diagnostics.push({
+      severity: strict ? "error" : "warn",
+      code,
+      message,
+      file,
+      line,
+      suggestion,
+      errorCode: meta?.code,
+      docsUrl: meta?.docsUrl
+    });
   };
   const modulesByName = new Map;
   const commandsByName = new Map;
   const routesByKey = new Map;
+  const declaredRoutes = [];
   for (const module of graph.modules) {
     const previousModule = modulesByName.get(module.name);
     if (previousModule) {
@@ -1260,20 +3533,128 @@ function validateGraph(graph, options = false) {
   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);
+        if (route.path.includes("//") || controller.path.includes("//")) {
+          error("malformed-route-path", `Route ${route.method} ${route.path} has malformed path: contains consecutive slashes '//'.`, controller.file, undefined, "Remove duplicate consecutive slashes from the route path.");
+        } else if (/(^|\/):(\/|$)/.test(route.path) || route.path.endsWith("/:")) {
+          error("malformed-route-path", `Route ${route.method} ${route.path} has malformed path: parameter colon ':' is missing a parameter identifier.`, controller.file, undefined, "Specify a valid parameter name following the colon (e.g. ':id').");
+        } else if (route.path.includes("?") || route.path.includes("#")) {
+          error("malformed-route-path", `Route ${route.method} ${route.path} has malformed path: contains invalid URL query '?' or fragment '#' character.`, controller.file, undefined, "Declare query parameters using @Query() decorators instead of in the route path.");
+        }
+        if (route.path.includes("**")) {
+          const segments = route.path.split("/").filter(Boolean);
+          const wildcardIdx = segments.indexOf("**");
+          if (wildcardIdx !== -1 && wildcardIdx !== segments.length - 1) {
+            error("wildcard-not-trailing", `Route ${route.method} '${route.path}' defines wildcard '**' in the middle of the path. In Angular Router semantics, wildcard '**' must be the trailing segment.`, controller.file, undefined, `Move the wildcard '**' to the end of the route path, e.g. '${segments.slice(0, wildcardIdx).join("/")}/**'.`);
+          }
+        }
+        const fullPath = joinRoutePaths2(controller.path, route.path);
+        const rawFullPath = joinRawRoutePaths(controller.path, route.path);
         const key = `${route.method} ${fullPath}`;
+        const openApiMatch = route.path.match(/\{([a-zA-Z0-9_]+)\}/);
+        if (openApiMatch) {
+          error("missing-param-colon", `Route path '${route.path}' in '${controller.className}.${route.handler}' uses OpenAPI-style '{${openApiMatch[1]}}'. SupaCloud routes require Express/Angular-style ':${openApiMatch[1]}'.`, controller.file, undefined, `Replace '{${openApiMatch[1]}}' with ':${openApiMatch[1]}'.`);
+        }
         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 });
         }
+        for (const prev of declaredRoutes) {
+          if (prev.method === route.method && isRouteShadowed(prev.rawFullPath, rawFullPath)) {
+            warn2("shadowed-route", `Route ${route.method} ${rawFullPath} (${controller.className}.${route.handler}) is shadowed by earlier parameterized route ${prev.method} ${prev.rawFullPath} (${prev.controller.className}.${prev.handler}) and will never be matched.`, controller.file, undefined, `Move specific route '${route.path}' before parameterized route '${prev.path}'.`);
+          }
+        }
+        declaredRoutes.push({ method: route.method, path: route.path, fullPath, rawFullPath, controller, module, handler: route.handler, redirectTo: route.redirectTo });
         if (route.command && !module.commands.some((command) => command.className === route.command)) {
           error("route-command-unresolved", `路由 ${key} 绑定的 command 类 ${route.command} 未在模块 ${module.name} 声明`, controller.file);
         }
+        if ((route.method === "GET" || route.method === "HEAD") && route.command) {
+          const boundCommand = module.commands.find((c) => c.className === route.command);
+          if (boundCommand && boundCommand.transaction === "required") {
+            error("command-transaction-readonly", `GET route '${route.path}' in '${controller.className}.${route.handler}' binds mutating command '${route.command}' with transaction: 'required'. Mutating transactions are not permitted on read-only HTTP GET requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for mutating command routes, or set transaction: 'none'.`);
+          }
+        }
         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 (route.redirectTo) {
+          const target = route.redirectTo.replace(/\/+$/, "");
+          const current = fullPath.replace(/\/+$/, "");
+          if (target === current || target === route.path.replace(/\/+$/, "")) {
+            error("circular-route-redirect", `Route ${key} defines circular redirectTo '${route.redirectTo}'`, controller.file);
+          }
+        }
+        const pathParams = route.pathParams ?? [];
+        const seenParams = new Set;
+        for (const p of pathParams) {
+          if (seenParams.has(p)) {
+            error("duplicate-path-param", `Route ${route.method} '${route.path}' defines duplicate path parameter ':${p}'. Each parameter in a route path must be unique.`, controller.file, undefined, `Rename the duplicate parameter ':${p}' to a unique name (e.g. ':${p}Id').`);
+          }
+          seenParams.add(p);
+        }
+        const paramBindings = route.paramBindings ?? [];
+        for (const binding of paramBindings) {
+          if (!binding || binding.trim().length === 0) {
+            error("unmatched-path-param-decorator", `Controller ${controller.className} handler ${route.handler} specifies an empty @Param() parameter binding.`, controller.file, undefined, `Specify a non-empty path parameter name matching a segment in route path '${route.path}'.`);
+          } else if (/[#?&=/\s]/.test(binding)) {
+            error("unmatched-path-param-decorator", `Controller ${controller.className} handler ${route.handler} specifies invalid @Param('${binding}') with illegal character. Path parameter names cannot contain '#', '?', '&', '=', '/', or whitespace.`, controller.file, undefined, `Rename path parameter binding '${binding}' to a valid identifier matching route path segment.`);
+          } else if (!pathParams.includes(binding)) {
+            const suggestion = findClosestMatch(binding, pathParams);
+            error("unmatched-path-param", `Controller ${controller.className} handler ${route.handler} binds @Param('${binding}'), but route path '${route.path}' does not define parameter ':${binding}'.`, controller.file, undefined, suggestion ? `Did you mean @Param('${suggestion}')?` : undefined);
+          }
+        }
+        if (paramBindings.length > 0) {
+          for (const param of pathParams) {
+            if (!paramBindings.includes(param)) {
+              warn2("missing-path-param", `Route path '${route.path}' defines parameter ':${param}', but handler ${controller.className}.${route.handler} does not bind it with @Param('${param}').`, controller.file, undefined, `Add @Param('${param}') to ${route.handler} arguments.`);
+            }
+          }
+        }
+        const queryBindings = route.queryBindings ?? [];
+        const seenQueries = new Set;
+        for (const q of queryBindings) {
+          if (!q || q.trim().length === 0) {
+            error("invalid-query-param-name", `Controller ${controller.className} handler ${route.handler} specifies an empty @Query() parameter binding.`, controller.file, undefined, `Specify a non-empty parameter name in @Query('paramName').`);
+          } else if (/[#?&=/\s]/.test(q)) {
+            error("invalid-query-param-name", `Controller ${controller.className} handler ${route.handler} specifies invalid @Query('${q}') with illegal character. Query parameter names cannot contain '#', '?', '&', '=', '/', or whitespace.`, controller.file, undefined, `Rename query parameter '${q}' to a valid identifier name without reserved characters.`);
+          } else if (seenQueries.has(q)) {
+            error("duplicate-query-param-binding", `Controller ${controller.className} handler ${route.handler} specifies duplicate @Query('${q}') parameter binding. Each query parameter should only be bound once per handler.`, controller.file, undefined, `Remove or rename the duplicate @Query('${q}') parameter binding in ${route.handler}.`);
+          }
+          seenQueries.add(q);
+        }
+        if (route.queryDefaults && route.queryTransforms) {
+          for (const [paramName, defVal] of Object.entries(route.queryDefaults)) {
+            const transform = route.queryTransforms[paramName];
+            if (transform === "number" && typeof defVal !== "number") {
+              error("invalid-query-default-type", `Controller ${controller.className} handler ${route.handler} specifies transform 'number' for @Query('${paramName}'), but default value '${String(defVal)}' is not a number.`, controller.file, undefined, `Provide a numeric default (e.g. default: 0) or change transform type to 'string'.`);
+            } else if (transform === "boolean" && typeof defVal !== "boolean") {
+              error("invalid-query-default-type", `Controller ${controller.className} handler ${route.handler} specifies transform 'boolean' for @Query('${paramName}'), but default value '${String(defVal)}' is not a boolean.`, controller.file, undefined, `Provide a boolean default (e.g. default: false) or change transform type.`);
+            }
+          }
+        }
+        if ((route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS" || route.method === "DELETE") && (route.hasBodyBinding || route.body)) {
+          error("disallowed-body-on-get-delete", `Route handler ${controller.className}.${route.handler} binds @Body() or declares body schema on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`);
+        }
+        if (route.hasBodyBinding && (route.method === "GET" || route.method === "HEAD" || route.method === "OPTIONS")) {
+          error("invalid-body-binding", `Route handler ${controller.className}.${route.handler} binds @Body() on HTTP ${route.method} route '${route.path}'. Request bodies are not supported on ${route.method} requests.`, controller.file, undefined, `Use POST, PUT, or PATCH for routes accepting a request body, or bind parameters via @Query() / @Param().`);
+        } else if (route.hasBodyBinding && !route.body) {
+          warn2("missing-body-schema", `Route handler ${controller.className}.${route.handler} binds @Body() on route '${route.path}', but route definition does not specify a body validation schema.`, controller.file, undefined, `Add schema to route options (e.g. body: Schema) for compile-time and runtime validation.`);
+        } else if (route.body && !route.hasBodyBinding && !route.command) {
+          warn2("unused-route-schema", `Route '${route.path}' defines body schema '${route.body}', but handler ${controller.className}.${route.handler} does not bind @Body().`, controller.file, undefined, `Bind parameter with @Body() in ${controller.className}.${route.handler} or remove unused body schema option.`);
+        }
+      }
+      const handlerMethodMap = new Map;
+      for (const route of controller.routes) {
+        const methods = handlerMethodMap.get(route.handler) ?? [];
+        methods.push(route.method);
+        handlerMethodMap.set(route.handler, methods);
+      }
+      for (const [handler, methods] of handlerMethodMap.entries()) {
+        const uniqueMethods = Array.from(new Set(methods));
+        if (uniqueMethods.length > 1) {
+          warn2("conflicting-route-method", `Controller ${controller.className} handler '${handler}' is mapped to multiple HTTP methods: ${uniqueMethods.join(", ")}.`, controller.file, undefined, `Separate distinct HTTP methods into separate controller handlers.`);
+        }
       }
       if (typeof options === "object" && options.disallowControllerDirectDb) {
         for (const dep of controller.deps) {
@@ -1283,6 +3664,73 @@ function validateGraph(graph, options = false) {
           }
         }
       }
+      if (controller.selfDeps && controller.selfDeps.length > 0) {
+        for (const dep of controller.selfDeps) {
+          const own = module.providers.find((p) => p.token === dep && p.scope === controller.scope);
+          if (!own) {
+            error("self-resolution-failed", `模块 ${module.name} 的 controller ${controller.className} 参数标记了 @Self()，但 ${dep} 未在当前模块内部提供`, controller.file, undefined, `Provide '${dep}' in module '${module.name}' or remove @Self().`);
+          }
+        }
+      }
+      if (controller.skipSelfDeps && controller.skipSelfDeps.length > 0) {
+        for (const dep of controller.skipSelfDeps) {
+          const own = module.providers.find((p) => p.token === dep && p.scope === controller.scope);
+          if (own) {
+            error("skip-self-resolution-failed", `模块 ${module.name} 的 controller ${controller.className} 参数标记了 @SkipSelf()，但 ${dep} 在当前模块内部声明了 provider`, controller.file, undefined, `Remove '${dep}' from module '${module.name}' providers or remove @SkipSelf().`);
+          }
+        }
+      }
+    }
+  }
+  const allTargetPaths = declaredRoutes.map((r) => r.rawFullPath);
+  for (const item of declaredRoutes) {
+    if (item.redirectTo) {
+      const target = item.redirectTo;
+      if (target.startsWith("/") && !target.startsWith("//")) {
+        const normalizedTarget = target.replace(/\/+$/, "") || "/";
+        const matchesTarget = declaredRoutes.some((candidate) => {
+          if (candidate.rawFullPath === normalizedTarget)
+            return true;
+          return routeMatchesTarget(candidate.rawFullPath, normalizedTarget);
+        });
+        if (!matchesTarget) {
+          const suggestion = findClosestMatch(normalizedTarget, allTargetPaths);
+          warn2("unresolved-route-redirect", `Route ${item.method} ${item.rawFullPath} (${item.controller.className}.${item.handler}) redirects to '${target}', but no matching route was found in the application graph.`, item.controller.file, undefined, suggestion ? `Did you mean '${suggestion}'?` : undefined);
+        }
+      }
+    }
+  }
+  const routeByRawPath = new Map;
+  for (const item of declaredRoutes) {
+    if (!routeByRawPath.has(item.rawFullPath)) {
+      routeByRawPath.set(item.rawFullPath, item);
+    }
+  }
+  const reportedRedirectCycles = new Set;
+  for (const item of declaredRoutes) {
+    if (item.redirectTo) {
+      const chain = [item.rawFullPath];
+      let curr = item;
+      while (curr && curr.redirectTo) {
+        const target = curr.redirectTo.replace(/\/+$/, "") || "/";
+        if (chain.includes(target)) {
+          const cycle = [...chain.slice(chain.indexOf(target)), target];
+          if (cycle.length > 2) {
+            const cycleKey = [...cycle].sort().join("|");
+            if (!reportedRedirectCycles.has(cycleKey)) {
+              reportedRedirectCycles.add(cycleKey);
+              const meta = COMPILER_DIAGNOSTIC_CODES["circular-route-redirect"];
+              error("circular-route-redirect", `Route redirect chain forms a cycle: ${cycle.join(" -> ")}`, item.controller.file, undefined, "Break the redirect loop by terminating at a concrete non-redirect route.");
+            }
+          }
+          break;
+        }
+        chain.push(target);
+        const next = routeByRawPath.get(target);
+        if (!next || !next.redirectTo)
+          break;
+        curr = next;
+      }
     }
   }
   for (const module of graph.modules) {
@@ -1290,33 +3738,63 @@ function validateGraph(graph, options = false) {
     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);
+        if (first.multi && provider.multi) {
+          continue;
+        }
+        error("duplicate-token", `模块 ${module.name} 重复注册 token ${provider.token}（首次注册于 ${first.file}:${first.line}）`, provider.file, provider.line, "If multiple providers are intended for this token, specify 'multi: true' on each provider definition (Angular multi-providers pattern).");
       } else {
         seen.set(provider.token, provider);
       }
     }
     for (const provider of module.providers) {
+      if (provider.selfDeps && provider.selfDeps.length > 0) {
+        for (const dep of provider.selfDeps) {
+          const own = module.providers.find((p) => p.token === dep && p.scope === provider.scope);
+          if (!own) {
+            error("self-resolution-failed", `模块 ${module.name} 的 provider ${provider.token} 参数标记了 @Self()，但 ${dep} 未在当前模块内部提供`, provider.file, provider.line, `Provide '${dep}' in module '${module.name}' or remove @Self().`);
+          }
+        }
+      }
+      if (provider.skipSelfDeps && provider.skipSelfDeps.length > 0) {
+        for (const dep of provider.skipSelfDeps) {
+          const own = module.providers.find((p) => p.token === dep && p.scope === provider.scope);
+          if (own) {
+            error("skip-self-resolution-failed", `模块 ${module.name} 的 provider ${provider.token} 参数标记了 @SkipSelf()，但 ${dep} 在当前模块内部声明了 provider`, provider.file, provider.line, `Remove '${dep}' from module '${module.name}' providers or remove @SkipSelf().`);
+          }
+        }
+      }
       for (const dep of provider.deps) {
-        const resolved = resolveDep(module, dep);
+        const isOptional = provider.optionalDeps?.includes(dep);
+        const resolved = resolveDep(module, dep, {
+          self: provider.selfDeps?.includes(dep),
+          skipSelf: provider.skipSelfDeps?.includes(dep)
+        });
         if (!resolved) {
+          if (isOptional) {
+            continue;
+          }
           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);
+              if (!owner)
+                continue;
+              error("module-boundary", `模块 ${module.name} 的 provider ${provider.token} 依赖 ${dep}，该 token 由模块 ${owner.module.name} 提供但未被 import`, provider.file, provider.line, `Import module '${owner.module.name}' in '${module.name}', add '${dep}' to '${owner.module.name}' exports, or mark @Injectable({ providedIn: 'root' }).`);
+            } else if (dep.includes("TOKEN") || dep.endsWith("Token") || dep.length > 2 && dep === dep.toUpperCase()) {
+              error("missing-token-factory", `InjectionToken '${dep}' referenced by provider '${provider.token}' has no provider in module '${module.name}' and no default factory function.`, provider.file, provider.line, `Provide '${dep}' in @Module({ providers: [...] }) or declare it with new InjectionToken('${dep}', { factory: () => ... }).`);
             } else {
-              error("unresolved-token", `模块 ${module.name} 的 provider ${provider.token} 依赖的 token ${dep} 无法解析`, provider.file, provider.line);
+              error("unresolved-token", `模块 ${module.name} 的 provider ${provider.token} 依赖的 token ${dep} 无法解析`, provider.file, provider.line, `Provide '${dep}' in a module, mark constructor parameter @Optional(), or define @Injectable({ providedIn: 'root' }).`);
             }
           }
           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);
+          error("scope-violation", `模块 ${module.name} 的 ${provider.scope} provider ${provider.token} 不能依赖 ${resolved.provider.scope} provider ${dep}`, provider.file, provider.line, `Change provider '${provider.token}' scope to '${resolved.provider.scope}', or inject a factory/context instead.`);
         }
       }
     }
     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);
+        error("command-missing-permission", `模块 ${module.name} 的 command ${command.name} (${command.className}) 未声明 permission`, module.file, module.line, "Add 'permission: string' to @Command({ ... }) or configure command execution capabilities permission=false.");
       }
       if (typeof options === "object" && options.commandCapabilities) {
         const caps = options.commandCapabilities;
@@ -1360,7 +3838,8 @@ function validateGraph(graph, options = false) {
             }
           }
           if (rule.onlyDependOnLibsWithTags && rule.onlyDependOnLibsWithTags.length > 0) {
-            const hasAllowed = targetTags.some((t) => rule.onlyDependOnLibsWithTags.includes(t));
+            const allowedTags = rule.onlyDependOnLibsWithTags;
+            const hasAllowed = targetTags.some((t) => allowedTags.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);
             }
@@ -1369,18 +3848,120 @@ function validateGraph(graph, options = false) {
       }
     }
   }
+  const referencedTokens = new Set;
+  for (const mod of graph.modules) {
+    for (const exp of mod.exports)
+      referencedTokens.add(exp);
+    for (const ctrl of mod.controllers) {
+      for (const d of ctrl.deps ?? [])
+        referencedTokens.add(d);
+      for (const d of ctrl.optionalDeps ?? [])
+        referencedTokens.add(d);
+      for (const d of ctrl.selfDeps ?? [])
+        referencedTokens.add(d);
+      for (const d of ctrl.skipSelfDeps ?? [])
+        referencedTokens.add(d);
+      for (const d of ctrl.hostDeps ?? [])
+        referencedTokens.add(d);
+    }
+    for (const p of mod.providers) {
+      for (const d of p.deps ?? [])
+        referencedTokens.add(d);
+      for (const d of p.optionalDeps ?? [])
+        referencedTokens.add(d);
+      for (const d of p.selfDeps ?? [])
+        referencedTokens.add(d);
+      for (const d of p.skipSelfDeps ?? [])
+        referencedTokens.add(d);
+      for (const d of p.hostDeps ?? [])
+        referencedTokens.add(d);
+      if (p.useExisting)
+        referencedTokens.add(p.useExisting);
+    }
+  }
+  for (const mod of graph.modules) {
+    for (const provider of mod.providers) {
+      if (provider.providedIn === "root" && !provider.multi && !referencedTokens.has(provider.token) && !provider.exported) {
+        warn2("unused-root-provider", `Root provider "${provider.token}" is declared with providedIn: 'root' but is never injected or depended on by any module, controller, or command.`, provider.file, provider.line, `Inject "${provider.token}" in a service or controller, export it, or remove providedIn: 'root' to enable tree-shaking.`);
+      }
+    }
+  }
+  for (const module of graph.modules) {
+    for (const expToken of module.exports) {
+      const resolved = resolveDep(module, expToken);
+      if (resolved)
+        continue;
+      if (module.imports.includes(expToken))
+        continue;
+      error("export-unprovided-token", `Module '${module.name}' exports token '${expToken}', but it is neither provided in '${module.name}' nor imported from an imported module.`, module.file, module.line, `Add a provider for '${expToken}' to '${module.name}.providers', or remove '${expToken}' from exports.`);
+    }
+  }
+  for (const module of graph.modules) {
+    for (const provider of module.providers) {
+      if (provider.useExisting) {
+        const target = provider.useExisting;
+        if (target === provider.token) {
+          error("self-referencing-alias", `Module '${module.name}' defines provider '${provider.token}' with useExisting referencing itself.`, provider.file ?? module.file, provider.line ?? module.line, `Change useExisting to reference a different provider token, or remove the self-referencing alias.`);
+        } else {
+          const resolved = resolveDep(module, target);
+          if (!resolved && !graph.externalTokens.includes(target)) {
+            error("unresolved-alias-target", `Module '${module.name}' defines provider '${provider.token}' with useExisting: '${target}', but '${target}' is neither provided in '${module.name}' nor imported from an imported module.`, provider.file ?? module.file, provider.line ?? module.line, `Add a provider for '${target}' to '${module.name}.providers' or an imported module, or update useExisting to reference an available token.`);
+          }
+        }
+      }
+    }
+  }
   diagnostics.push(...detectCycles(graph, resolveDep));
+  diagnostics.push(...detectExistingAliasCycles(graph, resolveDep));
   diagnostics.push(...detectModuleCycles(graph));
   if (typeof options === "object" && options.detectOrphanModules) {
     diagnostics.push(...detectOrphanModules(graph));
   }
   return diagnostics;
 }
-function joinRoutePaths(prefix, path) {
+function joinRoutePaths2(prefix, path) {
   const joined = `${prefix}/${path}`.replace(/\/{2,}/g, "/");
   const normalized = joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
   return normalized.replace(/:[^/]+/g, ":param");
 }
+function joinRawRoutePaths(prefix, path) {
+  const joined = `${prefix}/${path}`.replace(/\/{2,}/g, "/");
+  return joined.length > 1 ? joined.replace(/\/+$/, "") : joined;
+}
+function isRouteShadowed(earlierPath, laterPath) {
+  const earlierSegments = earlierPath.split("/").filter(Boolean);
+  const laterSegments = laterPath.split("/").filter(Boolean);
+  if (earlierSegments.length !== laterSegments.length) {
+    return false;
+  }
+  let hasParamShadowing = false;
+  for (let i = 0;i < earlierSegments.length; i += 1) {
+    const e = earlierSegments[i];
+    const l = laterSegments[i];
+    if (e === l) {
+      continue;
+    }
+    if (e.startsWith(":") && !l.startsWith(":")) {
+      hasParamShadowing = true;
+      continue;
+    }
+    return false;
+  }
+  return hasParamShadowing;
+}
+function routeMatchesTarget(routePattern, targetPath) {
+  const pSegs = routePattern.split("/").filter(Boolean);
+  const tSegs = targetPath.split("/").filter(Boolean);
+  if (pSegs.length !== tSegs.length)
+    return false;
+  for (let i = 0;i < pSegs.length; i += 1) {
+    if (pSegs[i].startsWith(":"))
+      continue;
+    if (pSegs[i] !== tSegs[i])
+      return false;
+  }
+  return true;
+}
 function detectCycles(graph, resolveDep) {
   const diagnostics = [];
   const nodeId = (ref) => `${ref.module.name}:${ref.provider.token}`;
@@ -1399,12 +3980,16 @@ function detectCycles(graph, resolveDep) {
       const cycleKey = cycle.map((item) => nodeId(item)).sort().join("|");
       if (!reported.has(cycleKey)) {
         reported.add(cycleKey);
+        const meta = COMPILER_DIAGNOSTIC_CODES["circular-dependency"];
         diagnostics.push({
           severity: "error",
           code: "circular-dependency",
           message: `provider 循环依赖: ${path}`,
           file: ref.provider.file,
-          line: ref.provider.line
+          line: ref.provider.line,
+          suggestion: "Break the cycle by extracting common dependencies into a separate service or injecting @Optional().",
+          errorCode: meta?.code,
+          docsUrl: meta?.docsUrl
         });
       }
       return;
@@ -1412,7 +3997,10 @@ function detectCycles(graph, resolveDep) {
     state.set(id, "visiting");
     stack.push(ref);
     for (const dep of ref.provider.deps) {
-      const resolved = resolveDep(ref.module, dep);
+      const resolved = resolveDep(ref.module, dep, {
+        self: ref.provider.selfDeps?.includes(dep),
+        skipSelf: ref.provider.skipSelfDeps?.includes(dep)
+      });
       if (resolved)
         visit(resolved);
     }
@@ -1423,6 +4011,47 @@ function detectCycles(graph, resolveDep) {
     visit(ref);
   return diagnostics;
 }
+function detectExistingAliasCycles(graph, resolveDep) {
+  const diagnostics = [];
+  const existingProviders = [];
+  for (const module of graph.modules) {
+    for (const provider of module.providers) {
+      if (provider.useExisting) {
+        existingProviders.push({ module, provider });
+      }
+    }
+  }
+  const reported = new Set;
+  for (const start of existingProviders) {
+    const visited = [start.provider.token];
+    let current = start;
+    while (current && current.provider.useExisting) {
+      const targetToken = current.provider.useExisting;
+      if (visited.includes(targetToken)) {
+        const cycle = [...visited.slice(visited.indexOf(targetToken)), targetToken];
+        const cycleKey = [...cycle].sort().join("|");
+        if (!reported.has(cycleKey)) {
+          reported.add(cycleKey);
+          const meta = COMPILER_DIAGNOSTIC_CODES["circular-existing-alias"];
+          diagnostics.push({
+            severity: "error",
+            code: "circular-existing-alias",
+            message: `Provider alias cycle detected in useExisting: ${cycle.join(" -> ")}`,
+            file: start.provider.file,
+            line: start.provider.line,
+            suggestion: "Break the alias cycle by pointing useExisting to a concrete provider instead of a circular alias.",
+            errorCode: meta?.code,
+            docsUrl: meta?.docsUrl
+          });
+        }
+        break;
+      }
+      visited.push(targetToken);
+      current = resolveDep(current.module, targetToken);
+    }
+  }
+  return diagnostics;
+}
 function detectModuleCycles(graph) {
   const diagnostics = [];
   const moduleMap = new Map(graph.modules.map((m) => [m.name, m]));
@@ -1439,12 +4068,16 @@ function detectModuleCycles(graph) {
       if (!reported.has(cycleKey)) {
         reported.add(cycleKey);
         const mod2 = moduleMap.get(name);
+        const meta = COMPILER_DIAGNOSTIC_CODES["circular-module-import"];
         diagnostics.push({
           severity: "error",
           code: "circular-module-import",
           message: `Module circular import detected: ${cycle.join(" -> ")}`,
           file: mod2?.file,
-          line: mod2?.line
+          line: mod2?.line,
+          suggestion: "Refactor module imports into a unidirectional acyclic graph.",
+          errorCode: meta?.code,
+          docsUrl: meta?.docsUrl
         });
       }
       return;
@@ -1480,6 +4113,8 @@ function detectOrphanModules(graph) {
   }
   while (queue.length > 0) {
     const current = queue.shift();
+    if (!current)
+      continue;
     const mod = moduleMap.get(current);
     if (!mod)
       continue;
@@ -1492,12 +4127,15 @@ function detectOrphanModules(graph) {
   }
   for (const mod of graph.modules) {
     if (!reachable.has(mod.name)) {
+      const meta = COMPILER_DIAGNOSTIC_CODES["orphan-module"];
       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
+        line: mod.line,
+        errorCode: meta?.code,
+        docsUrl: meta?.docsUrl
       });
     }
   }
@@ -1505,10 +4143,225 @@ function detectOrphanModules(graph) {
 }
 
 // src/compile.ts
-import { existsSync as existsSync2, readFileSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { join as join4 } from "node:path";
+
+// src/type-safety.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join3, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
+import * as ts4 from "@typescript/typescript6";
+var DEFAULT_EXCLUDES = [
+  "**/*.test.ts",
+  "**/*.spec.ts",
+  "**/test/**",
+  "**/tests/**",
+  "**/__tests__/**",
+  "**/fixtures/**",
+  "**/generated/**",
+  "**/dist/**",
+  "**/*.d.ts"
+];
+var DIAGNOSTIC_META = {
+  "generated-any": { errorCode: "SC6001", docsUrl: "https://supacloud.dev/errors/SC6001" },
+  "source-any": { errorCode: "SC6002", docsUrl: "https://supacloud.dev/errors/SC6002" },
+  "source-type-assertion": { errorCode: "SC6003", docsUrl: "https://supacloud.dev/errors/SC6003" },
+  "source-non-null-assertion": { errorCode: "SC6004", docsUrl: "https://supacloud.dev/errors/SC6004" },
+  "source-implicit-widening": { errorCode: "SC6005", docsUrl: "https://supacloud.dev/errors/SC6005" }
+};
+function scanGeneratedArtifacts(artifacts, strict = true) {
+  const diagnostics = [];
+  for (const [file, content] of Object.entries(artifacts)) {
+    if (content === undefined)
+      continue;
+    const sourceFile = ts4.createSourceFile(file, content, ts4.ScriptTarget.Latest, true, ts4.ScriptKind.TS);
+    for (const node of descendantsOfKind2(sourceFile, isAnyKeyword)) {
+      diagnostics.push(makeDiagnostic("generated-any", `生成产物 ${file} 包含 any；严格生成模式要求使用 unknown、具体接口或泛型约束。`, sourceFile, node, strict));
+    }
+  }
+  return diagnostics;
+}
+function scanProductionSource(options) {
+  const rootDir = resolve2(options.rootDir);
+  const configPath = join3(rootDir, "tsconfig.json");
+  const projectConfig = existsSync2(configPath) ? readProjectConfig2(configPath) : {
+    options: {
+      strict: true,
+      skipLibCheck: true,
+      target: ts4.ScriptTarget.ES2022,
+      module: ts4.ModuleKind.ESNext
+    },
+    errors: []
+  };
+  const include = options.include ?? ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"];
+  const rootNames = ts4.sys.readDirectory(rootDir, [".ts", ".tsx", ".mts", ".cts"], ["node_modules", "dist"], include).filter((file) => isProductionSourcePath(rootDir, file, [...DEFAULT_EXCLUDES, ...options.exclude ?? []]));
+  const compilerOptions = { ...projectConfig.options, noEmit: true };
+  const host = ts4.createCompilerHost(compilerOptions);
+  host.getCurrentDirectory = () => rootDir;
+  const program = ts4.createProgram(rootNames, compilerOptions, host);
+  const outDir = options.outDir ? normalizeRelative(rootDir, options.outDir) : undefined;
+  const excludes = [...DEFAULT_EXCLUDES, ...options.exclude ?? []];
+  const sourceFiles = program.getSourceFiles().filter((sourceFile) => isProductionSource(rootDir, sourceFile, excludes, outDir));
+  const diagnostics = [...projectConfig.errors, ...program.getOptionsDiagnostics()].map((diagnostic) => ({
+    severity: "error",
+    code: "source-config",
+    message: ts4.flattenDiagnosticMessageText(diagnostic.messageText, `
+`),
+    file: diagnostic.file ? normalizeRelative(rootDir, diagnostic.file.fileName) : normalizeRelative(rootDir, configPath),
+    line: diagnostic.file && diagnostic.start !== undefined ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1 : undefined,
+    errorCode: `TS${diagnostic.code}`
+  }));
+  const checker = program.getTypeChecker();
+  for (const sourceFile of sourceFiles) {
+    scanSourceFile(sourceFile, checker, rootDir, diagnostics, options.strict ?? false);
+  }
+  return diagnostics;
+}
+function scanSourceFile(sourceFile, checker, rootDir, diagnostics, strict) {
+  for (const node of descendantsOfKind2(sourceFile, isAnyKeyword)) {
+    diagnostics.push(makeDiagnostic("source-any", "生产源码使用了显式 any；请改用 unknown、具体接口或泛型约束。", sourceFile, node, strict, rootDir));
+  }
+  for (const node of descendants(sourceFile)) {
+    if (ts4.isAsExpression(node)) {
+      if (ts4.isAsExpression(node.parent) || ts4.isTypeAssertionExpression(node.parent))
+        continue;
+      const assertedType = node.type.getText(sourceFile);
+      if (assertedType === "const")
+        continue;
+      diagnostics.push(makeDiagnostic("source-type-assertion", `生产源码包含类型断言 ${node.getText(sourceFile)}；请优先使用类型守卫、satisfies 或显式边界解析。`, sourceFile, node, strict, rootDir));
+    } else if (ts4.isTypeAssertionExpression(node)) {
+      if (ts4.isAsExpression(node.parent) || ts4.isTypeAssertionExpression(node.parent))
+        continue;
+      diagnostics.push(makeDiagnostic("source-type-assertion", `生产源码包含类型断言 ${node.getText(sourceFile)}；请优先使用类型守卫、satisfies 或显式边界解析。`, sourceFile, node, strict, rootDir));
+    } else if (ts4.isNonNullExpression(node)) {
+      diagnostics.push(makeDiagnostic("source-non-null-assertion", `生产源码包含非空断言 ${node.getText(sourceFile)}；请显式处理 null/undefined。`, sourceFile, node, strict, rootDir));
+    }
+  }
+  for (const declaration of descendantsOfKind2(sourceFile, ts4.isVariableDeclaration)) {
+    const initializer = declaration.initializer;
+    if (!initializer || declaration.type)
+      continue;
+    const declarationType = checker.getTypeAtLocation(declaration.name);
+    const initializerType = checker.getTypeAtLocation(initializer);
+    for (const name of bindingNames(declaration.name)) {
+      if (isAnyType(checker.getTypeAtLocation(name))) {
+        diagnostics.push(makeDiagnostic("source-any", "生产源码中的变量被推断为 any；请为边界数据提供解析类型或显式 unknown。", sourceFile, name, strict, rootDir));
+      }
+    }
+    if (isAnyType(declarationType))
+      continue;
+    if (isLetDeclaration(declaration) && isLiteralSyntax(initializer) && !isLiteralType(declarationType)) {
+      diagnostics.push(makeDiagnostic("source-implicit-widening", `变量 ${declaration.name.getText(sourceFile)} 的字面量类型从 ${checker.typeToString(initializerType, initializer)} 隐式宽化为 ${checker.typeToString(declarationType, declaration)}；请补充类型或使用 const。`, sourceFile, declaration, strict, rootDir));
+    }
+    if (ts4.isObjectLiteralExpression(initializer) && isConstDeclaration(declaration) && initializer.getText(sourceFile).length > 0 && initializer.properties.some((property) => ts4.isPropertyAssignment(property) && property.initializer !== undefined && !ts4.isAsExpression(property.initializer) && isLiteralExpression(property.initializer))) {
+      diagnostics.push(makeDiagnostic("source-implicit-widening", `常量对象 ${declaration.name.getText(sourceFile)} 的字面量属性会隐式宽化；请补充对象类型或使用 as const。`, sourceFile, declaration, strict, rootDir));
+    }
+  }
+  for (const parameter of descendantsOfKind2(sourceFile, ts4.isParameter)) {
+    if (parameter.type)
+      continue;
+    for (const name of bindingNames(parameter.name)) {
+      if (isAnyType(checker.getTypeAtLocation(name))) {
+        diagnostics.push(makeDiagnostic("source-any", "生产源码中的参数被推断为 any；请补充参数类型。", sourceFile, name, strict, rootDir));
+      }
+    }
+  }
+}
+function readProjectConfig2(configPath) {
+  const config = ts4.readConfigFile(configPath, (file) => readFileSync2(file, "utf8"));
+  if (config.error)
+    return { options: {}, errors: [config.error] };
+  const parsed = ts4.parseJsonConfigFileContent(config.config, ts4.sys, dirname2(configPath));
+  return { options: parsed.options, errors: parsed.errors };
+}
+function isProductionSource(rootDir, sourceFile, excludes, outDir) {
+  const relativePath = normalizeRelative(rootDir, sourceFile.fileName);
+  if (sourceFile.isDeclarationFile || relativePath.startsWith("../") || relativePath.includes("node_modules/"))
+    return false;
+  if (outDir && (relativePath === outDir || relativePath.startsWith(`${outDir}/`)))
+    return false;
+  return !excludes.some((pattern) => globMatches(relativePath, pattern));
+}
+function isProductionSourcePath(rootDir, filePath, excludes) {
+  const relativePath = normalizeRelative(rootDir, filePath);
+  return !relativePath.startsWith("../") && !relativePath.includes("node_modules/") && !excludes.some((pattern) => globMatches(relativePath, pattern));
+}
+function globMatches(value, pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "§/").replace(/\*\*/g, "§§").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/§\//g, "(?:.*/)?").replace(/§§/g, ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}
+function bindingNames(name) {
+  if (ts4.isIdentifier(name))
+    return [name];
+  return name.elements.flatMap((element) => ts4.isBindingElement(element) ? bindingNames(element.name) : []);
+}
+function isLiteralExpression(node) {
+  if (!node)
+    return false;
+  return [
+    ts4.SyntaxKind.StringLiteral,
+    ts4.SyntaxKind.NumericLiteral,
+    ts4.SyntaxKind.TrueKeyword,
+    ts4.SyntaxKind.FalseKeyword
+  ].includes(node.kind);
+}
+function isLiteralSyntax(node) {
+  return ts4.isStringLiteral(node) || ts4.isNumericLiteral(node) || node.kind === ts4.SyntaxKind.TrueKeyword || node.kind === ts4.SyntaxKind.FalseKeyword;
+}
+function isLiteralType(type) {
+  return (type.flags & (ts4.TypeFlags.StringLiteral | ts4.TypeFlags.NumberLiteral | ts4.TypeFlags.BooleanLiteral | ts4.TypeFlags.BigIntLiteral)) !== 0;
+}
+function isAnyType(type) {
+  return (type.flags & ts4.TypeFlags.Any) !== 0;
+}
+function isLetDeclaration(declaration) {
+  return ts4.isVariableDeclarationList(declaration.parent) && (declaration.parent.flags & ts4.NodeFlags.Let) !== 0;
+}
+function isConstDeclaration(declaration) {
+  return ts4.isVariableDeclarationList(declaration.parent) && (declaration.parent.flags & ts4.NodeFlags.Const) !== 0;
+}
+function descendants(root) {
+  const result = [];
+  const visit = (node) => {
+    result.push(node);
+    ts4.forEachChild(node, visit);
+  };
+  ts4.forEachChild(root, visit);
+  return result;
+}
+function descendantsOfKind2(root, predicate) {
+  const result = [];
+  const visit = (node) => {
+    if (predicate(node))
+      result.push(node);
+    ts4.forEachChild(node, visit);
+  };
+  ts4.forEachChild(root, visit);
+  return result;
+}
+function makeDiagnostic(code, message, fileOrSourceFile, node, strict, rootDir) {
+  const sourceFile = typeof fileOrSourceFile === "string" ? undefined : fileOrSourceFile;
+  const file = typeof fileOrSourceFile === "string" ? fileOrSourceFile : rootDir ? normalizeRelative(rootDir, fileOrSourceFile.fileName) : fileOrSourceFile.fileName;
+  const meta = DIAGNOSTIC_META[code];
+  return {
+    severity: strict ? "error" : "warn",
+    code,
+    message,
+    file,
+    line: sourceFile ? sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1 : undefined,
+    errorCode: meta.errorCode,
+    docsUrl: meta.docsUrl
+  };
+}
+function normalizeRelative(rootDir, filePath) {
+  return relative2(rootDir, filePath).split(sep2).join("/").replace(/^\.\//, "");
+}
+function isAnyKeyword(node) {
+  return node.kind === ts4.SyntaxKind.AnyKeyword;
+}
+
+// src/compile.ts
 async function compileProject(options) {
-  const graph = await analyzeProject(options.rootDir, options.include);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, {
@@ -1527,14 +4380,51 @@ async function compileProject(options) {
         diagnostic.severity = "error";
     }
   }
-  const written = await generateApplication(graph, {
+  const typeSafety = resolveTypeSafety(options);
+  const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
-    outDir: options.outDir
+    outDir: options.outDir,
+    generateClient: options.generateClient,
+    generatePermissions: options.generatePermissions,
+    treeShakeUnusedProviders: options.treeShakeUnusedProviders
   });
-  return { diagnostics, graph, written };
+  if (typeSafety.scanProductionSource) {
+    diagnostics.push(...scanProductionSource({
+      rootDir: options.rootDir,
+      include: options.include,
+      outDir: options.outDir,
+      strict: options.strict,
+      ...typeSafety
+    }));
+  }
+  if (typeSafety.noAnyInGenerated) {
+    diagnostics.push(...scanGeneratedArtifacts({
+      "application.ts": rendered.applicationCode,
+      "client.ts": rendered.clientCode,
+      "permissions.ts": rendered.permissionsCode
+    }, options.strict ?? false));
+  }
+  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === "error");
+  const generatedOptions = {
+    rootDir: options.rootDir,
+    outDir: options.outDir,
+    generateClient: options.generateClient,
+    generatePermissions: options.generatePermissions,
+    treeShakeUnusedProviders: options.treeShakeUnusedProviders,
+    artifactHashes: options.cache?.generatedHashes
+  };
+  const written = !hasErrors || options.writeOnError !== false ? await generateApplication(graph, generatedOptions) : [];
+  const stats = graph.cacheStats ? {
+    cacheHit: graph.cacheStats.reanalyzedModules.length === 0,
+    changedFiles: [],
+    affectedModules: graph.cacheStats.reanalyzedModules,
+    reanalyzedModules: graph.cacheStats.reanalyzedModules,
+    reusedModules: graph.cacheStats.reusedModules
+  } : undefined;
+  return { diagnostics, graph, written, stats };
 }
 async function checkProject(options) {
-  const graph = await analyzeProject(options.rootDir, options.include);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache, options.changedPaths);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, {
@@ -1553,22 +4443,48 @@ async function checkProject(options) {
         diagnostic.severity = "error";
     }
   }
+  const typeSafety = resolveTypeSafety(options);
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
-    outDir: options.outDir
+    outDir: options.outDir,
+    generateClient: options.generateClient,
+    generatePermissions: options.generatePermissions,
+    treeShakeUnusedProviders: options.treeShakeUnusedProviders
   });
+  if (typeSafety.scanProductionSource) {
+    diagnostics.push(...scanProductionSource({
+      rootDir: options.rootDir,
+      include: options.include,
+      outDir: options.outDir,
+      strict: options.strict,
+      ...typeSafety
+    }));
+  }
+  if (typeSafety.noAnyInGenerated) {
+    diagnostics.push(...scanGeneratedArtifacts({
+      "application.ts": rendered.applicationCode,
+      "client.ts": rendered.clientCode,
+      "permissions.ts": rendered.permissionsCode
+    }, options.strict ?? false));
+  }
   const expectedFiles = {
     "application.ts": rendered.applicationCode,
     "app.manifest.json": rendered.manifestJson
   };
+  if (rendered.clientCode) {
+    expectedFiles["client.ts"] = rendered.clientCode;
+  }
+  if (rendered.permissionsCode) {
+    expectedFiles["permissions.ts"] = rendered.permissionsCode;
+  }
   const mismatches = [];
   for (const [filename, expectedContent] of Object.entries(expectedFiles)) {
-    const diskPath = join3(options.outDir, filename);
-    if (!existsSync2(diskPath)) {
+    const diskPath = join4(options.outDir, filename);
+    if (!existsSync3(diskPath)) {
       mismatches.push(`${filename}: generated artifact is missing from disk`);
       continue;
     }
-    const diskContent = readFileSync(diskPath, "utf8");
+    const diskContent = readFileSync3(diskPath, "utf8");
     if (diskContent !== expectedContent) {
       mismatches.push(`${filename}: disk artifact differs from current compiler output`);
     }
@@ -1580,19 +4496,547 @@ async function checkProject(options) {
     graph
   };
 }
+function resolveTypeSafety(options) {
+  return {
+    noAnyInGenerated: options.typeSafety?.noAnyInGenerated ?? options.strict ?? false,
+    scanProductionSource: options.typeSafety?.scanProductionSource ?? options.strict ?? false,
+    exclude: options.typeSafety?.exclude
+  };
+}
+// src/watch.ts
+import { watch } from "node:fs";
+import { relative as relative4, resolve as resolve4 } from "node:path";
+
+// src/incremental.ts
+import { createHash as createHash5 } from "node:crypto";
+import { access as access2, readdir, readFile } from "node:fs/promises";
+import { isAbsolute, relative as relative3, resolve as resolve3, sep as sep3 } from "node:path";
+function createDependencyGraphCache() {
+  return {
+    modules: new Map,
+    fileHashes: new Map,
+    generatedHashes: new Map
+  };
+}
+function createIncrementalCompiler() {
+  let previousSnapshot;
+  let previousResult;
+  let previousCache;
+  const cache = createDependencyGraphCache();
+  return {
+    async compile(options, changedPaths) {
+      const optionsKey = optionsKeyOf(options);
+      const snapshot = changedPaths && previousSnapshot && previousSnapshot.optionsKey === optionsKey ? await updateSnapshot(previousSnapshot, options, changedPaths) : await createSnapshot(options);
+      const changedFiles = changedPaths && previousSnapshot ? diffFiles(previousSnapshot.files, snapshot.files) : diffFiles(previousSnapshot?.files, snapshot.files);
+      const activeCache = options.cache ?? cache;
+      const cacheHit = Boolean(previousSnapshot && previousSnapshot.optionsKey === snapshot.optionsKey && previousCache === activeCache && changedFiles.length === 0);
+      if (cacheHit && previousResult) {
+        return {
+          ...previousResult,
+          stats: {
+            cacheHit: true,
+            changedFiles: [],
+            affectedModules: [],
+            reusedModules: previousResult.graph.modules.map((m) => m.name),
+            reanalyzedModules: []
+          }
+        };
+      }
+      if (!activeCache.dependencyGraph && previousResult) {
+        activeCache.dependencyGraph = new ModuleDependencyGraph(previousResult.graph.modules);
+      }
+      const result = await compileProject({
+        ...options,
+        cache: activeCache,
+        changedPaths: changedFiles
+      });
+      const affectedModules = previousResult ? findAffectedModules(previousResult.graph.modules, result.graph.modules, changedFiles) : result.graph.modules.map((module) => module.name);
+      const reusedModules = result.graph.cacheStats?.reusedModules ?? [];
+      const reanalyzedModules = result.graph.cacheStats?.reanalyzedModules ?? affectedModules;
+      if (activeCache) {
+        activeCache.dependencyGraph = new ModuleDependencyGraph(result.graph.modules);
+      }
+      const stats = {
+        cacheHit: false,
+        changedFiles,
+        affectedModules,
+        reusedModules,
+        reanalyzedModules
+      };
+      previousSnapshot = snapshot;
+      previousResult = result;
+      previousCache = activeCache;
+      return { ...result, stats };
+    },
+    reset() {
+      previousSnapshot = undefined;
+      previousResult = undefined;
+      previousCache = undefined;
+      cache.modules.clear();
+      cache.fileHashes.clear();
+      cache.generatedHashes?.clear();
+      cache.dependencyGraph = undefined;
+      cache.programSession?.reset();
+    },
+    getCache() {
+      return cache;
+    }
+  };
+}
+async function updateSnapshot(previous, options, changedPaths) {
+  const rootDir = resolve3(options.rootDir);
+  const outDir = resolve3(options.outDir);
+  const files = { ...previous.files };
+  for (const changedPath of changedPaths) {
+    const absolutePath = isAbsolute(changedPath) ? resolve3(changedPath) : resolve3(rootDir, changedPath);
+    const relativeChangedPath = relative3(rootDir, absolutePath);
+    if (relativeChangedPath === ".." || relativeChangedPath.startsWith(`..${sep3}`))
+      continue;
+    if (absolutePath === outDir || absolutePath.startsWith(`${outDir}/`))
+      continue;
+    const relativePath = relative3(rootDir, absolutePath).split(sep3).join("/");
+    try {
+      await access2(absolutePath);
+      const content = await readFile(absolutePath);
+      files[relativePath] = createHash5("sha256").update(content).digest("hex");
+    } catch {
+      delete files[relativePath];
+    }
+  }
+  return { files, optionsKey: optionsKeyOf(options) };
+}
+async function createSnapshot(options) {
+  const rootDir = resolve3(options.rootDir);
+  const outDir = resolve3(options.outDir);
+  const paths = await listSourceFiles(rootDir, outDir);
+  const files = {};
+  for (const path of paths) {
+    const content = await readFile(path);
+    files[relative3(rootDir, path).split(sep3).join("/")] = createHash5("sha256").update(content).digest("hex");
+  }
+  return { files, optionsKey: optionsKeyOf(options) };
+}
+function optionsKeyOf(options) {
+  return JSON.stringify({
+    rootDir: resolve3(options.rootDir),
+    outDir: resolve3(options.outDir),
+    include: options.include,
+    strict: options.strict,
+    writeOnError: options.writeOnError,
+    moduleBoundaryPreset: options.moduleBoundaryPreset,
+    moduleBoundaries: options.moduleBoundaries,
+    allowRouteCommandBindings: options.allowRouteCommandBindings,
+    commandCapabilities: options.commandCapabilities,
+    disallowControllerDirectDb: options.disallowControllerDirectDb,
+    detectOrphanModules: options.detectOrphanModules,
+    generateClient: options.generateClient,
+    generatePermissions: options.generatePermissions,
+    typeSafety: options.typeSafety,
+    treeShakeUnusedProviders: options.treeShakeUnusedProviders
+  });
+}
+async function listSourceFiles(rootDir, outDir) {
+  const result = [];
+  const visit = async (directory) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = resolve3(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git" || path === outDir)
+          continue;
+        await visit(path);
+      } else if (/\.(tsx?|mts|cts)$/.test(entry.name)) {
+        result.push(path);
+      }
+    }
+  };
+  await visit(rootDir);
+  return result.sort();
+}
+function diffFiles(previous, current) {
+  if (!previous)
+    return Object.keys(current);
+  const names = new Set([...Object.keys(previous), ...Object.keys(current)]);
+  return [...names].filter((name) => previous[name] !== current[name]).sort();
+}
+
+class ModuleDependencyGraph {
+  imports = new Map;
+  dependents = new Map;
+  fileOwners = new Map;
+  moduleMap = new Map;
+  constructor(modules = []) {
+    this.rebuild(modules);
+  }
+  rebuild(modules) {
+    this.imports.clear();
+    this.dependents.clear();
+    this.fileOwners.clear();
+    this.moduleMap.clear();
+    for (const mod of modules) {
+      this.moduleMap.set(mod.name, mod);
+      this.imports.set(mod.name, new Set(mod.imports));
+      if (!this.dependents.has(mod.name)) {
+        this.dependents.set(mod.name, new Set);
+      }
+      this.indexFile(mod.file, mod.name);
+      for (const p of mod.providers) {
+        if (p.importPath)
+          this.indexFile(p.importPath, mod.name);
+        if (p.file)
+          this.indexFile(p.file, mod.name);
+      }
+      for (const c of mod.controllers) {
+        if (c.importPath)
+          this.indexFile(c.importPath, mod.name);
+        if (c.file)
+          this.indexFile(c.file, mod.name);
+      }
+    }
+    for (const [modName, imps] of this.imports.entries()) {
+      for (const imp of imps) {
+        if (!this.dependents.has(imp)) {
+          this.dependents.set(imp, new Set);
+        }
+        const dependents = this.dependents.get(imp);
+        if (dependents)
+          dependents.add(modName);
+      }
+    }
+  }
+  indexFile(path, moduleName) {
+    if (!path)
+      return;
+    const normalized = path.replace(/\.(tsx?|mts|cts)$/, "");
+    if (!this.fileOwners.has(normalized)) {
+      this.fileOwners.set(normalized, new Set);
+    }
+    const owners = this.fileOwners.get(normalized);
+    if (owners)
+      owners.add(moduleName);
+  }
+  getModulesOwningFile(filePath) {
+    const normalized = filePath.replace(/\.(tsx?|mts|cts)$/, "");
+    return Array.from(this.fileOwners.get(normalized) ?? []);
+  }
+  getAffectedModules(changedFiles) {
+    if (changedFiles.length === 0)
+      return [];
+    const directlyAffected = new Set;
+    for (const file of changedFiles) {
+      for (const modName of this.getModulesOwningFile(file)) {
+        directlyAffected.add(modName);
+      }
+    }
+    if (directlyAffected.size === 0) {
+      return [];
+    }
+    const affected = new Set(directlyAffected);
+    const queue = Array.from(directlyAffected);
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (!current)
+        continue;
+      const dependents = this.dependents.get(current);
+      if (dependents) {
+        for (const dep of dependents) {
+          if (!affected.has(dep)) {
+            affected.add(dep);
+            queue.push(dep);
+          }
+        }
+      }
+    }
+    return Array.from(this.moduleMap.keys()).filter((name) => affected.has(name));
+  }
+  getDirectImports(moduleName) {
+    return Array.from(this.imports.get(moduleName) ?? []);
+  }
+  getDirectDependents(moduleName) {
+    return Array.from(this.dependents.get(moduleName) ?? []);
+  }
+}
+function findAffectedModules(previous, current, changedFiles) {
+  const depGraph = new ModuleDependencyGraph(current);
+  return depGraph.getAffectedModules(changedFiles);
+}
+
+// src/watch.ts
+var DEFAULT_DEBOUNCE_MS = 100;
+function watchProject(options) {
+  const rootDir = resolve4(options.rootDir);
+  const outDir = resolve4(options.outDir);
+  const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  let timer;
+  let closed = false;
+  let compiling = false;
+  let pending = false;
+  const pendingPaths = new Set;
+  let watcher;
+  const incremental = createIncrementalCompiler();
+  let initialEvent;
+  let resolveReady = () => {
+    return;
+  };
+  let rejectReady = () => {
+    return;
+  };
+  const ready = new Promise((resolvePromise, rejectPromise) => {
+    resolveReady = resolvePromise;
+    rejectReady = rejectPromise;
+  });
+  const emit = (event) => {
+    options.onEvent?.(event);
+    if (event.initial)
+      initialEvent = event;
+  };
+  const compile = async (initial, changedPaths = []) => {
+    if (closed && !initial)
+      return;
+    if (compiling) {
+      pending = true;
+      return;
+    }
+    compiling = true;
+    const startedAt = performance.now();
+    options.onEvent?.({
+      type: "compile-start",
+      initial,
+      durationMs: 0,
+      diagnostics: [],
+      written: []
+    });
+    try {
+      const result = await incremental.compile({ ...options, writeOnError: false }, changedPaths);
+      const durationMs = Math.round(performance.now() - startedAt);
+      const hasErrors = result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
+      emit({
+        type: hasErrors ? "compile-error" : "compiled",
+        initial,
+        durationMs,
+        diagnostics: result.diagnostics,
+        written: result.written,
+        stats: result.stats
+      });
+    } catch (error) {
+      rejectReady(error);
+      throw error;
+    } finally {
+      compiling = false;
+      if (pending && !closed) {
+        pending = false;
+        compile(false, [...pendingPaths]);
+        pendingPaths.clear();
+      }
+    }
+  };
+  const schedule = (changedPath) => {
+    if (closed)
+      return;
+    if (changedPath)
+      pendingPaths.add(changedPath);
+    if (timer)
+      clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      compile(false, [...pendingPaths]);
+      pendingPaths.clear();
+    }, debounceMs);
+  };
+  compile(true).then(() => {
+    if (closed)
+      return;
+    watcher = watch(rootDir, { recursive: true }, (_eventType, filename) => {
+      if (!filename)
+        return schedule();
+      const changedPath = resolve4(rootDir, filename.toString());
+      const relativePath = relative4(outDir, changedPath);
+      if (!relativePath.startsWith("..") && relativePath !== "")
+        return;
+      if (/\.(tsx?|mts|cts)$/.test(changedPath))
+        schedule(relative4(rootDir, changedPath));
+    });
+    if (initialEvent)
+      resolveReady(initialEvent);
+  }).catch(() => {
+    return;
+  });
+  return {
+    ready,
+    async close() {
+      closed = true;
+      if (timer)
+        clearTimeout(timer);
+      watcher?.close();
+      await ready.catch(() => {
+        return;
+      });
+    }
+  };
+}
+// src/inspect.ts
+import { existsSync as existsSync4 } from "node:fs";
+import { join as join5 } from "node:path";
+function formatGraph(graph) {
+  const lines = [];
+  for (const module of graph.modules) {
+    lines.push(`MODULE ${module.name}`);
+    lines.push(`  file: ${module.file}:${module.line}`);
+    lines.push(`  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`);
+    lines.push(`  providers: ${module.providers.length > 0 ? module.providers.map((p) => p.token).join(", ") : "-"}`);
+    lines.push(`  controllers: ${module.controllers.length > 0 ? module.controllers.map((c) => c.className).join(", ") : "-"}`);
+    lines.push(`  commands: ${module.commands.length > 0 ? module.commands.map((c) => c.name).join(", ") : "-"}`);
+  }
+  lines.push(`EXTERNAL TOKENS ${graph.externalTokens.length > 0 ? graph.externalTokens.join(", ") : "-"}`);
+  return lines.join(`
+`);
+}
+function explainGraph(graph, subject) {
+  const module = graph.modules.find((candidate) => candidate.name === subject);
+  if (module)
+    return explainModule(graph, module);
+  const provider = findProvider(graph, subject);
+  if (provider)
+    return explainProvider(graph, provider.module, provider.provider);
+  if (graph.externalTokens.includes(subject)) {
+    const references = graph.modules.flatMap((candidate) => [
+      ...candidate.providers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.token}`),
+      ...candidate.controllers.filter((item) => item.deps.includes(subject)).map((item) => `${candidate.name}.${item.className}`)
+    ]);
+    return [
+      `EXTERNAL TOKEN ${subject}`,
+      "  provided by: platform runtime",
+      `  references: ${references.length > 0 ? references.join(", ") : "-"}`
+    ].join(`
+`);
+  }
+  const known = [...graph.modules.map((item) => item.name), ...graph.externalTokens].sort();
+  throw new Error(`No module, provider, or external token named "${subject}". Known names: ${known.join(", ") || "(none)"}`);
+}
+function doctorProject(rootDir, outDir, graph, upToDate, diagnostics = []) {
+  const checks = [
+    {
+      name: "project-root",
+      ok: existsSync4(rootDir),
+      detail: existsSync4(rootDir) ? rootDir : `missing: ${rootDir}`
+    },
+    {
+      name: "tsconfig",
+      ok: existsSync4(join5(rootDir, "tsconfig.json")),
+      detail: existsSync4(join5(rootDir, "tsconfig.json")) ? "tsconfig.json found" : "tsconfig.json missing"
+    },
+    {
+      name: "modules",
+      ok: graph.modules.length > 0,
+      detail: `${graph.modules.length} module(s) discovered`
+    },
+    {
+      name: "generated-artifacts",
+      ok: upToDate,
+      detail: upToDate ? "application.ts and app.manifest.json are up to date" : "generated artifacts are missing or stale"
+    }
+  ];
+  const allDiagnostics = [...graph.diagnostics ?? [], ...diagnostics];
+  return {
+    checks,
+    diagnostics: allDiagnostics,
+    errors: allDiagnostics.filter((diagnostic) => diagnostic.severity === "error").length + checks.filter((check) => !check.ok).length
+  };
+}
+function explainModule(graph, module) {
+  const dependents = graph.modules.filter((candidate) => candidate.imports.includes(module.name)).map((candidate) => candidate.name);
+  return [
+    `MODULE ${module.name}`,
+    `  file: ${module.file}:${module.line}`,
+    `  imports: ${module.imports.length > 0 ? module.imports.join(", ") : "-"}`,
+    `  imported by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`,
+    `  providers: ${module.providers.length > 0 ? module.providers.map((provider) => provider.token).join(", ") : "-"}`,
+    `  controllers: ${module.controllers.length > 0 ? module.controllers.map((controller) => controller.className).join(", ") : "-"}`,
+    `  commands: ${module.commands.length > 0 ? module.commands.map((command) => command.name).join(", ") : "-"}`
+  ].join(`
+`);
+}
+function explainProvider(graph, module, provider) {
+  const dependents = graph.modules.flatMap((candidate) => [
+    ...candidate.providers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.token}`),
+    ...candidate.controllers.filter((item) => item.deps.includes(provider.token)).map((item) => `${candidate.name}.${item.className}`)
+  ]);
+  return [
+    `PROVIDER ${provider.token}`,
+    `  module: ${module.name}`,
+    `  file: ${provider.file}:${provider.line}`,
+    `  kind: ${provider.kind}`,
+    `  scope: ${provider.scope}`,
+    `  exported: ${provider.exported ? "yes" : "no"}`,
+    `  deps: ${provider.deps.length > 0 ? provider.deps.join(", ") : "-"}`,
+    `  depended on by: ${dependents.length > 0 ? dependents.join(", ") : "-"}`
+  ].join(`
+`);
+}
+function findProvider(graph, subject) {
+  for (const module of graph.modules) {
+    const provider = module.providers.find((candidate) => candidate.token === subject || candidate.useClass === subject || candidate.useFactoryName === subject);
+    if (provider)
+      return { module, provider };
+  }
+  return;
+}
+function exportGraphMermaid(graph) {
+  const lines = ["graph TD"];
+  for (const mod of graph.modules) {
+    const safeId = mod.name.replace(/[^a-zA-Z0-9_]/g, "_");
+    lines.push(`  ${safeId}["${mod.className ?? mod.name}"]`);
+    for (const imp of mod.imports) {
+      const safeImp = imp.replace(/[^a-zA-Z0-9_]/g, "_");
+      lines.push(`  ${safeId} --> ${safeImp}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function exportGraphDot(graph) {
+  const lines = [
+    "digraph ApplicationGraph {",
+    "  rankdir=LR;",
+    '  node [shape=box, fontname="Helvetica"];'
+  ];
+  for (const mod of graph.modules) {
+    lines.push(`  "${mod.name}" [label="${mod.className ?? mod.name}"];`);
+    for (const imp of mod.imports) {
+      lines.push(`  "${mod.name}" -> "${imp}";`);
+    }
+  }
+  lines.push("}");
+  return lines.join(`
+`);
+}
 export {
   ANGULAR_ENTERPRISE_RULES,
   CLEAN_ARCHITECTURE_RULES,
+  COMPILER_DIAGNOSTIC_CODES,
   MODULAR_MONOLITH_RULES,
   MODULE_BOUNDARY_PROFILES,
+  ModuleDependencyGraph,
+  TraitCompiler,
   analyzeProject,
   camelName,
   checkProject,
   compileProject,
+  compileTraits,
+  createDependencyGraphCache,
+  createIncrementalCompiler,
+  createIncrementalProgramSession,
+  doctorProject,
+  explainGraph,
+  exportGraphDot,
+  exportGraphMermaid,
+  formatGraph,
   generateApplication,
   getModuleBoundaryPreset,
   getModuleBoundaryProfile,
   renderApplication,
   resolveModuleBoundaries,
-  validateGraph
+  scanGeneratedArtifacts,
+  scanProductionSource,
+  validateGraph,
+  watchProject
 };