@supacloud/compiler 0.4.1 → 0.5.0

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { resolve } from "node:path";
+import { resolve as resolve3 } from "node:path";
 
 // src/analyze.ts
 import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join, relative, sep } from "node:path";
 import {
   Node,
@@ -22,10 +23,20 @@ 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);
+async function analyzeProject(rootDir, include, cache) {
+  let project;
+  if (cache?.project) {
+    project = cache.project;
+    for (const sf of project.getSourceFiles()) {
+      sf.refreshFromFileSystemSync();
+    }
+  } else {
+    project = createProject(rootDir);
+    const patterns = (include ?? DEFAULT_INCLUDE).map((glob) => join(rootDir, glob));
+    project.addSourceFilesAtPaths(patterns);
+    if (cache)
+      cache.project = project;
+  }
   const sourceFiles = project.getSourceFiles().filter((sf) => !sf.getFilePath().includes("node_modules") && !sf.isDeclarationFile()).sort((a, b) => a.getFilePath().localeCompare(b.getFilePath()));
   const ctx = {
     rootDir,
@@ -75,7 +86,207 @@ async function analyzeProject(rootDir, include) {
   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.getFilePath());
+      const hash = createHash("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 = [];
+    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 = new Set;
+      ownedFiles.add(parsed.file);
+      for (const p of parsed.providers)
+        if (p.file)
+          ownedFiles.add(p.file);
+      for (const ctrl of parsed.controllers)
+        if (ctrl.file)
+          ownedFiles.add(ctrl.file);
+      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));
+  }
+  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, missing } = classDeps(classInfo.decl, ctx);
+        const file = sourcePath(ctx.rootDir, classInfo.file);
+        const line = classInfo.decl.getStartLineNumber();
+        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,
+          providedIn: "root",
+          hasOnDestroy: classInfo.decl.getMethod("onDestroy") !== undefined || 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 = controllerDec.getArguments()[0];
+        const isStandalone = arg && Node.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.getName() ?? name,
+            name: stringLiteralProp(meta, "name") ?? classInfo.decl.getName() ?? name,
+            permission: stringLiteralProp(meta, "permission"),
+            transaction: commandModeProp(meta, "transaction") ?? "none",
+            audit: stringLiteralProp(meta, "audit"),
+            idempotency: commandModeProp(meta, "idempotency") ?? "none",
+            standalone: true
+          });
+        }
+      }
+    }
+  }
+  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) {
+      existingRoot.providers.push(...rootProviders);
+      existingRoot.controllers.push(...standaloneControllers);
+      existingRoot.commands.push(...standaloneCommands);
+      for (const p of rootProviders) {
+        if (!existingRoot.exports.includes(p.token))
+          existingRoot.exports.push(p.token);
+      }
+    } 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) {
@@ -94,7 +305,8 @@ async function analyzeProject(rootDir, include) {
     modules,
     externalTokens,
     diagnostics: ctx.diagnostics,
-    tokenNames
+    tokenNames,
+    cacheStats: cache ? { reusedModules, reanalyzedModules } : undefined
   };
 }
 function createProject(rootDir) {
@@ -129,7 +341,7 @@ function parseTokenVariable(decl, file) {
   if (init.getExpression().getText() !== "InjectionToken")
     return;
   const [nameArg, optionsArg] = init.getArguments();
-  const info = { name: decl.getName(), file };
+  const info = { name: decl.getName(), file, line: decl.getStartLineNumber() };
   if (nameArg && Node.isStringLiteral(nameArg)) {
     info.stringName = nameArg.getLiteralText();
   }
@@ -138,6 +350,14 @@ function parseTokenVariable(decl, file) {
     if (scope && SCOPES.includes(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;
 }
@@ -146,7 +366,8 @@ function parseModule(candidate, nameByNode, ctx) {
   const name = nameByNode.get(candidate.node) ?? className;
   const tags = arrayProp(options, "tags").map((el) => Node.isStringLiteral(el) ? el.getLiteralText() : el.getText().replace(/['"]/g, "")).filter(Boolean);
   const imports = arrayProp(options, "imports").map((el) => {
-    const decl = Node.isIdentifier(el) ? resolveDeclaration(el)[0] : undefined;
+    const unwrapped = unwrapForwardRef(el);
+    const decl = Node.isIdentifier(unwrapped) ? resolveDeclaration(unwrapped)[0] : undefined;
     if (decl) {
       const known = nameByNode.get(decl);
       if (known)
@@ -211,7 +432,8 @@ function parseModule(candidate, nameByNode, ctx) {
           permission: stringLiteralProp(meta, "permission"),
           transaction: commandModeProp(meta, "transaction") ?? "none",
           audit: stringLiteralProp(meta, "audit"),
-          idempotency: commandModeProp(meta, "idempotency") ?? "none"
+          idempotency: commandModeProp(meta, "idempotency") ?? "none",
+          standalone: booleanProp(meta, "standalone") || undefined
         });
       }
     }
@@ -247,11 +469,13 @@ function commandModeProp(object, name) {
 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 unwrappedEl = unwrapForwardRef(el);
+  if (Node.isIdentifier(unwrappedEl)) {
+    const decl = resolveDeclaration(unwrappedEl)[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 className = cls?.getName() ?? unwrappedEl.getText();
+    const { deps, optionalDeps, selfDeps, skipSelfDeps, hostDeps, missing } = cls ? classDeps(cls, ctx) : { deps: [], optionalDeps: [], selfDeps: [], skipSelfDeps: [], hostDeps: [], missing: false };
+    const injectable = cls ? parseInjectableOptions(cls, ctx) : undefined;
     if (missing) {
       warn(ctx, "missing-deps", `provider ${className} 的部分构造依赖无法静态解析`, file, line);
     }
@@ -262,6 +486,12 @@ 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,
+      providedIn: injectable?.providedIn,
+      hasOnDestroy: cls?.getMethod("onDestroy") !== undefined || undefined,
       exported: exportsSet.has(className),
       file,
       line,
@@ -276,22 +506,33 @@ 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 unwrappedClass = unwrapForwardRef(useClassExpr);
+    const decl = Node.isIdentifier(unwrappedClass) ? resolveDeclaration(unwrappedClass)[0] : undefined;
     const cls = decl && Node.isClassDeclaration(decl) ? decl : undefined;
-    const useClass = cls?.getName() ?? useClassExpr.getText();
+    const useClass = cls?.getName() ?? unwrappedClass.getText();
     let deps = explicitDeps;
+    let optionalDeps = [];
+    let selfDeps = [];
+    let skipSelfDeps = [];
+    let hostDeps = [];
     if (deps.length === 0 && cls) {
       const result = classDeps(cls, ctx);
       deps = result.deps;
+      optionalDeps = result.optionalDeps;
+      selfDeps = result.selfDeps;
+      skipSelfDeps = result.skipSelfDeps;
+      hostDeps = result.hostDeps;
       if (result.missing) {
         warn(ctx, "missing-deps", `provider ${token} (useClass ${useClass}) 的部分构造依赖无法静态解析`, file, line);
       }
     }
+    const injectable = cls ? parseInjectableOptions(cls, ctx) : undefined;
     return {
       token,
       tokenKind,
@@ -299,6 +540,13 @@ 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,
+      multi: multi ?? undefined,
+      providedIn: injectable?.providedIn,
+      hasOnDestroy: cls?.getMethod("onDestroy") !== undefined || undefined,
       exported: exportsSet.has(token),
       file,
       line,
@@ -313,6 +561,7 @@ function parseProvider(el, exportsSet, ctx) {
       useValueExpr: useValueExpr.getText(),
       scope: resolveScope({ explicit: explicitScope, tokenName: token }, ctx),
       deps: [],
+      multi: multi ?? undefined,
       exported: exportsSet.has(token),
       file,
       line,
@@ -331,6 +580,7 @@ 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,
@@ -346,6 +596,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
@@ -353,18 +604,36 @@ function parseProvider(el, exportsSet, ctx) {
   }
   return;
 }
-function parseController(el, ctx) {
-  if (!Node.isIdentifier(el))
-    return;
-  const decl = resolveDeclaration(el)[0];
-  if (!decl || !Node.isClassDeclaration(decl))
+function parseController(input, ctx) {
+  let decl;
+  if (Node.isClassDeclaration(input)) {
+    decl = input;
+  } else {
+    const unwrapped = unwrapForwardRef(input);
+    const resolved = Node.isIdentifier(unwrapped) ? resolveDeclaration(unwrapped)[0] : undefined;
+    if (resolved && Node.isClassDeclaration(resolved)) {
+      decl = resolved;
+    }
+  }
+  if (!decl)
     return;
   const controllerDec = findDecorator(decl, "Controller");
   if (!controllerDec)
     return;
+  let path = "/";
+  let standalone;
   const pathArg = controllerDec.getArguments()[0];
-  const path = pathArg && Node.isStringLiteral(pathArg) ? pathArg.getLiteralText() : "/";
-  const { deps, missing } = classDeps(decl, ctx);
+  if (pathArg) {
+    if (Node.isStringLiteral(pathArg)) {
+      path = pathArg.getLiteralText();
+    } else if (Node.isObjectLiteralExpression(pathArg)) {
+      const p = stringLiteralProp(pathArg, "path");
+      if (p)
+        path = p;
+      standalone = booleanProp(pathArg, "standalone");
+    }
+  }
+  const { deps, optionalDeps, selfDeps, skipSelfDeps, missing } = classDeps(decl, ctx);
   const file = sourcePath(ctx.rootDir, decl.getSourceFile().getFilePath());
   if (missing) {
     warn(ctx, "missing-deps", `controller ${decl.getName()} 的部分构造依赖无法静态解析`, file, decl.getStartLineNumber());
@@ -372,6 +641,14 @@ function parseController(el, ctx) {
   const injectable = parseInjectableOptions(decl, ctx);
   const routes = [];
   const schemaImports = {};
+  const classGuards = [];
+  for (const dec of decl.getDecorators()) {
+    if (decoratorName(dec) === "UseGuards") {
+      for (const gArg of dec.getArguments()) {
+        classGuards.push(tokenText(gArg));
+      }
+    }
+  }
   for (const method of decl.getMethods()) {
     for (const dec of method.getDecorators()) {
       const name = decoratorName(dec);
@@ -380,11 +657,158 @@ function parseController(el, ctx) {
         continue;
       const args = dec.getArguments();
       const pathArg2 = args[0];
+      const routePath = pathArg2 && Node.isStringLiteral(pathArg2) ? pathArg2.getLiteralText() : "/";
       const route = {
         method: httpMethod,
-        path: pathArg2 && Node.isStringLiteral(pathArg2) ? pathArg2.getLiteralText() : "/",
+        path: routePath,
         handler: method.getName()
       };
+      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.getParameters()) {
+        const pName = p.getName();
+        let hasBindingDecorator = false;
+        let paramNode;
+        for (const pDec of p.getDecorators()) {
+          const dName = decoratorName(pDec);
+          const dArgs = pDec.getArguments();
+          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.getType().getText();
+          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 method.getDecorators()) {
+        const dName = decoratorName(mDec);
+        const mArgs = mDec.getArguments();
+        if (dName === "UseGuards") {
+          for (const gArg of mArgs) {
+            routeGuards.push(tokenText(gArg));
+          }
+        } else if (dName === "CanDeactivate") {
+          for (const gArg of mArgs) {
+            routeCanDeactivate.push(tokenText(gArg));
+          }
+        } else if (dName === "Title") {
+          const tArg = mArgs[0];
+          if (tArg && Node.isStringLiteral(tArg)) {
+            route.title = tArg.getLiteralText();
+          }
+        } else if (dName === "Data") {
+          const dArg = mArgs[0];
+          if (dArg && Node.isObjectLiteralExpression(dArg)) {
+            route.data = { ...route.data, ...parseObjectLiteralValues(dArg) };
+          }
+        } else if (dName === "Resolve") {
+          const rArg = mArgs[0];
+          if (rArg && Node.isObjectLiteralExpression(rArg)) {
+            const resolvers = route.resolvers ?? {};
+            for (const prop of rArg.getProperties()) {
+              if (Node.isPropertyAssignment(prop)) {
+                const rName = prop.getName();
+                const init = prop.getInitializer();
+                if (init)
+                  resolvers[rName] = tokenText(init);
+              }
+            }
+            if (Object.keys(resolvers).length > 0) {
+              route.resolvers = resolvers;
+            }
+          }
+        }
+      }
       const optionsArg = args[1];
       if (optionsArg && Node.isObjectLiteralExpression(optionsArg)) {
         for (const field of ["body", "params", "query", "response"]) {
@@ -401,6 +825,68 @@ function parseController(el, ctx) {
           const commandDecl = resolveDeclaration(commandExpr)[0];
           route.command = commandDecl && Node.isClassDeclaration(commandDecl) ? commandDecl.getName() ?? commandExpr.getText() : commandExpr.getText();
         }
+        const guardsExpr = getProp(optionsArg, "guards");
+        if (guardsExpr && Node.isArrayLiteralExpression(guardsExpr)) {
+          for (const el of guardsExpr.getElements()) {
+            routeGuards.push(tokenText(el));
+          }
+        }
+        const canMatchExpr = getProp(optionsArg, "canMatch");
+        if (canMatchExpr && Node.isArrayLiteralExpression(canMatchExpr)) {
+          const canMatchList = [];
+          for (const el of canMatchExpr.getElements()) {
+            canMatchList.push(tokenText(el));
+          }
+          if (canMatchList.length > 0) {
+            route.canMatch = canMatchList;
+          }
+        }
+        const canDeactivateExpr = getProp(optionsArg, "canDeactivate");
+        if (canDeactivateExpr && Node.isArrayLiteralExpression(canDeactivateExpr)) {
+          for (const el of canDeactivateExpr.getElements()) {
+            routeCanDeactivate.push(tokenText(el));
+          }
+        }
+        const resolversExpr = getProp(optionsArg, "resolvers");
+        if (resolversExpr && Node.isObjectLiteralExpression(resolversExpr)) {
+          const resolvers = {};
+          for (const prop of resolversExpr.getProperties()) {
+            if (Node.isPropertyAssignment(prop)) {
+              const rName = prop.getName();
+              const init = prop.getInitializer();
+              if (init)
+                resolvers[rName] = tokenText(init);
+            }
+          }
+          if (Object.keys(resolvers).length > 0) {
+            route.resolvers = resolvers;
+          }
+        }
+        const redirectToExpr = getProp(optionsArg, "redirectTo");
+        if (redirectToExpr && Node.isStringLiteral(redirectToExpr)) {
+          route.redirectTo = redirectToExpr.getLiteralText();
+        }
+        const pathMatchExpr = getProp(optionsArg, "pathMatch");
+        if (pathMatchExpr && Node.isStringLiteral(pathMatchExpr)) {
+          const val = pathMatchExpr.getLiteralText();
+          if (val === "full" || val === "prefix") {
+            route.pathMatch = val;
+          }
+        }
+        const titleExpr = getProp(optionsArg, "title");
+        if (titleExpr && Node.isStringLiteral(titleExpr)) {
+          route.title = titleExpr.getLiteralText();
+        }
+        const dataExpr = getProp(optionsArg, "data");
+        if (dataExpr && Node.isObjectLiteralExpression(dataExpr)) {
+          route.data = { ...route.data, ...parseObjectLiteralValues(dataExpr) };
+        }
+      }
+      if (routeGuards.length > 0) {
+        route.guards = routeGuards;
+      }
+      if (routeCanDeactivate.length > 0) {
+        route.canDeactivate = routeCanDeactivate;
       }
       routes.push(route);
     }
@@ -410,6 +896,10 @@ function parseController(el, ctx) {
     path,
     scope: injectable?.scope ?? "request",
     deps,
+    optionalDeps: optionalDeps.length > 0 ? optionalDeps : undefined,
+    selfDeps: selfDeps.length > 0 ? selfDeps : undefined,
+    skipSelfDeps: skipSelfDeps.length > 0 ? skipSelfDeps : undefined,
+    standalone: standalone || undefined,
     routes,
     file,
     importPath: modulePath(ctx.rootDir, decl.getSourceFile().getFilePath()),
@@ -418,28 +908,84 @@ function parseController(el, ctx) {
 }
 function classDeps(cls, ctx) {
   const injectable = parseInjectableOptions(cls, ctx);
-  if (injectable?.deps)
-    return { deps: injectable.deps, missing: false };
+  if (injectable?.deps) {
+    return {
+      deps: injectable.deps,
+      optionalDeps: [],
+      selfDeps: [],
+      skipSelfDeps: [],
+      hostDeps: [],
+      missing: false
+    };
+  }
   const ctor = cls.getConstructors()[0];
-  if (!ctor || ctor.getParameters().length === 0)
-    return { deps: [], missing: false };
-  const injectParams = parseInjectParams(cls);
   const deps = [];
+  const optionalDeps = [];
+  const selfDeps = [];
+  const skipSelfDeps = [];
+  const hostDeps = [];
   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 (ctor && ctor.getParameters().length > 0) {
+    const injectParams = parseInjectParams(cls);
+    const optionalIndices = parseOptionalParams(cls);
+    const selfIndices = parseModifierParams(cls, "Self");
+    const skipSelfIndices = parseModifierParams(cls, "SkipSelf");
+    const hostIndices = parseModifierParams(cls, "Host");
+    ctor.getParameters().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.getProperties()) {
+    const init = prop.getInitializer();
+    if (init && Node.isCallExpression(init)) {
+      const callName = init.getExpression().getText().split(".").pop();
+      if (callName === "inject") {
+        const [tokenArg, optionsArg] = init.getArguments();
+        if (tokenArg) {
+          const tokenName = tokenText(tokenArg);
+          if (tokenName) {
+            if (!deps.includes(tokenName))
+              deps.push(tokenName);
+            if (optionsArg && Node.isObjectLiteralExpression(optionsArg)) {
+              const isOptional = booleanProp(optionsArg, "optional");
+              if (isOptional && !optionalDeps.includes(tokenName)) {
+                optionalDeps.push(tokenName);
+              }
+              const isSelf = booleanProp(optionsArg, "self");
+              if (isSelf && !selfDeps.includes(tokenName)) {
+                selfDeps.push(tokenName);
+              }
+              const isSkipSelf = booleanProp(optionsArg, "skipSelf");
+              if (isSkipSelf && !skipSelfDeps.includes(tokenName)) {
+                skipSelfDeps.push(tokenName);
+              }
+              const isHost = booleanProp(optionsArg, "host");
+              if (isHost && !hostDeps.includes(tokenName)) {
+                hostDeps.push(tokenName);
+              }
+            }
+          }
+        }
+      }
     }
-  });
-  return { deps, missing };
+  }
+  return { deps, optionalDeps, selfDeps, skipSelfDeps, hostDeps, missing };
 }
 function paramTypeTokenName(param, ctx) {
   const typeNode = param.getTypeNode();
@@ -460,9 +1006,11 @@ 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,
+    providedIn: providedIn === "root" ? "root" : undefined,
     deps: depsExpr ? arrayProp(obj, "deps").map((el) => ctx ? tokenNameOf(el, ctx).name : el.getText()) : undefined
   };
 }
@@ -482,15 +1030,61 @@ function parseInjectParams(cls) {
   });
   return result;
 }
+function parseOptionalParams(cls) {
+  const result = new Set;
+  const ctor = cls.getConstructors()[0];
+  if (!ctor)
+    return result;
+  ctor.getParameters().forEach((param, index) => {
+    for (const dec of param.getDecorators()) {
+      if (decoratorName(dec) === "Optional")
+        result.add(index);
+    }
+    if (param.hasQuestionToken())
+      result.add(index);
+  });
+  return result;
+}
+function parseModifierParams(cls, modifierName) {
+  const result = new Set;
+  const ctor = cls.getConstructors()[0];
+  if (!ctor)
+    return result;
+  ctor.getParameters().forEach((param, index) => {
+    for (const dec of param.getDecorators()) {
+      if (decoratorName(dec) === modifierName)
+        result.add(index);
+    }
+  });
+  return result;
+}
+function unwrapForwardRef(expr) {
+  if (Node.isCallExpression(expr)) {
+    const exprText = expr.getExpression().getText();
+    if (exprText === "forwardRef" || exprText.endsWith(".forwardRef")) {
+      const arg = expr.getArguments()[0];
+      if (arg && (Node.isArrowFunction(arg) || Node.isFunctionExpression(arg))) {
+        const body = arg.getBody();
+        if (body && Node.isExpression(body)) {
+          return unwrapForwardRef(body);
+        }
+      }
+    }
+  }
+  return expr;
+}
 function tokenText(expr) {
-  if (Node.isIdentifier(expr)) {
-    const decl = resolveDeclaration(expr)[0];
+  const unwrapped = unwrapForwardRef(expr);
+  if (Node.isStringLiteral(unwrapped))
+    return unwrapped.getLiteralText();
+  if (Node.isIdentifier(unwrapped)) {
+    const decl = resolveDeclaration(unwrapped)[0];
     if (decl && Node.isClassDeclaration(decl))
-      return decl.getName() ?? expr.getText();
+      return decl.getName() ?? unwrapped.getText();
     if (decl && Node.isVariableDeclaration(decl))
       return decl.getName();
   }
-  return expr.getText();
+  return unwrapped.getText();
 }
 function resolveScope(input, ctx) {
   if (input.explicit)
@@ -506,8 +1100,9 @@ function resolveScope(input, ctx) {
   return "application";
 }
 function tokenNameOf(expr, ctx) {
-  if (Node.isIdentifier(expr)) {
-    const decl = resolveDeclaration(expr)[0];
+  const unwrapped = unwrapForwardRef(expr);
+  if (Node.isIdentifier(unwrapped)) {
+    const decl = resolveDeclaration(unwrapped)[0];
     if (decl && Node.isClassDeclaration(decl)) {
       return { name: decl.getName() ?? expr.getText(), kind: "class" };
     }
@@ -585,10 +1180,90 @@ function arrayProp(obj, name) {
   const expr = getProp(obj, name);
   return expr && Node.isArrayLiteralExpression(expr) ? expr.getElements() : [];
 }
+function booleanProp(obj, name) {
+  const expr = getProp(obj, name);
+  if (!expr)
+    return;
+  if (expr.getKind() === SyntaxKind.TrueKeyword)
+    return true;
+  if (expr.getKind() === SyntaxKind.FalseKeyword)
+    return false;
+  return;
+}
 function parseScopeProp(obj) {
   const scope = stringLiteralProp(obj, "scope");
   return scope && SCOPES.includes(scope) ? scope : undefined;
 }
+function parseBindingOptions(args, defaultName) {
+  let name = defaultName;
+  let transform;
+  let defaultValue;
+  const first = args[0];
+  const second = args[1];
+  if (first && Node.isStringLiteral(first)) {
+    name = first.getLiteralText();
+  } else if (first && Node.isObjectLiteralExpression(first)) {
+    const nameProp = getProp(first, "name");
+    if (nameProp && Node.isStringLiteral(nameProp)) {
+      name = nameProp.getLiteralText();
+    }
+    const trProp = getProp(first, "transform");
+    if (trProp && Node.isStringLiteral(trProp)) {
+      const val = trProp.getLiteralText();
+      if (val === "number" || val === "boolean" || val === "string") {
+        transform = val;
+      }
+    }
+    const defProp = getProp(first, "default");
+    if (defProp) {
+      defaultValue = parseLiteralValue(defProp);
+    }
+  }
+  if (second && Node.isObjectLiteralExpression(second)) {
+    const trProp = getProp(second, "transform");
+    if (trProp && Node.isStringLiteral(trProp)) {
+      const val = trProp.getLiteralText();
+      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 (Node.isStringLiteral(node))
+    return node.getLiteralText();
+  if (Node.isNumericLiteral(node))
+    return node.getLiteralValue();
+  if (node.getKindName() === "TrueKeyword")
+    return true;
+  if (node.getKindName() === "FalseKeyword")
+    return false;
+  if (Node.isArrayLiteralExpression(node)) {
+    return node.getElements().map(parseLiteralValue);
+  }
+  if (Node.isObjectLiteralExpression(node)) {
+    return parseObjectLiteralValues(node);
+  }
+  return;
+}
+function parseObjectLiteralValues(obj) {
+  const result = {};
+  for (const prop of obj.getProperties()) {
+    if (Node.isPropertyAssignment(prop)) {
+      const name = prop.getName();
+      const init = prop.getInitializer();
+      if (init) {
+        result[name] = parseLiteralValue(init);
+      }
+    }
+  }
+  return result;
+}
 function modulePath(rootDir, absFile) {
   return sourcePath(rootDir, absFile).replace(/\.(ts|tsx|js|mts|cts)$/, "");
 }
@@ -600,7 +1275,7 @@ function warn(ctx, code, message, file, line) {
 }
 
 // src/generate.ts
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
 
 // src/util.ts
@@ -633,6 +1308,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";
@@ -645,6 +1342,28 @@ 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>;
+  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 {
@@ -654,6 +1373,7 @@ export interface CompiledCommand {
   transaction: "required" | "none";
   audit?: string;
   idempotency: "required" | "none";
+  standalone?: boolean;
 }
 
 export interface CompiledController {
@@ -683,7 +1403,40 @@ export interface CompiledModule {
   commands: CompiledCommand[];
 }`;
 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 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);
+        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 = [];
@@ -705,6 +1458,34 @@ function renderApplication(graph, options) {
     "  ];",
     "}",
     "",
+    "export async function initializeApplication(services: Record<string, unknown>): Promise<void> {",
+    '  const initializers = (services.appInitializer ?? (services as any)["supacloud.app-initializer"]) as unknown;',
+    "  if (Array.isArray(initializers)) {",
+    "    for (const init of initializers) {",
+    '      if (typeof init === "function") await init();',
+    "    }",
+    '  } else if (typeof initializers === "function") {',
+    "    await (initializers as () => unknown)();",
+    "  }",
+    "}",
+    "",
+    "export async function destroyApplication(services: Record<string, unknown>): Promise<void> {",
+    '  const destroyRef = (services.destroyRef ?? (services as any)["supacloud.destroy-ref"]) as { destroy?: () => Promise<void>; _teardowns?: Array<() => void | Promise<void>> } | undefined;',
+    '  if (destroyRef && typeof destroyRef.destroy === "function") {',
+    "    await destroyRef.destroy();",
+    "  } else if (destroyRef && Array.isArray(destroyRef._teardowns)) {",
+    "    for (const teardown of [...destroyRef._teardowns].reverse()) {",
+    '      if (typeof teardown === "function") await teardown();',
+    "    }",
+    "  }",
+    "  const instances = Object.values(services);",
+    "  for (const inst of instances.reverse()) {",
+    '    if (inst && typeof (inst as any).onDestroy === "function") {',
+    "      await (inst as any).onDestroy();",
+    "    }",
+    "  }",
+    "}",
+    "",
     ...factorySections,
     ""
   ].join(`
@@ -714,10 +1495,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) {
@@ -725,9 +1510,32 @@ 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];
+  await writeFileAtomic(applicationPath, rendered.applicationCode);
+  await writeFileAtomic(manifestPath, rendered.manifestJson);
+  const written = [applicationPath, manifestPath];
+  if (rendered.clientCode) {
+    const clientPath = join2(options.outDir, "client.ts");
+    await writeFileAtomic(clientPath, rendered.clientCode);
+    written.push(clientPath);
+  }
+  if (rendered.permissionsCode) {
+    const permissionsPath = join2(options.outDir, "permissions.ts");
+    await writeFileAtomic(permissionsPath, rendered.permissionsCode);
+    written.push(permissionsPath);
+  }
+  return written;
+}
+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;
@@ -864,6 +1672,81 @@ 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)}`);
+        }
+        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: any, req: any) => await (ctrl as any).${route.handler}(${callArgs})`);
         return `{ ${fields.join(", ")} }`;
       });
       return [
@@ -909,11 +1792,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);
@@ -925,34 +1821,40 @@ ${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);
+        const args = provider.deps.map((dep) => this.depExpr(dep, kind, provider.optionalDeps?.includes(dep))).join(", ");
+        const local = this.localVar(isMulti ? provider.useClass ?? `${provider.token}Item` : provider.token, kind);
         return { constLine: `const ${local} = new ${useClass}(${args});`, key, expr: local };
       }
       case "value": {
         const expr = provider.importPath ? this.imports.add(provider.useValueExpr ?? "undefined", provider.importPath) : provider.useValueExpr ?? "undefined";
-        const local = this.localVar(provider.token, kind);
+        const local = this.localVar(isMulti ? `${provider.token}Item` : provider.token, kind);
         return { constLine: `const ${local} = ${expr};`, key, expr: local };
       }
       case "factory": {
+        if (provider.tokenKind === "injection-token" && !provider.useFactoryName) {
+          const tokenIdent = this.imports.add(provider.token, provider.importPath);
+          const local2 = this.localVar(isMulti ? `${provider.token}Item` : provider.token, kind);
+          const constLine = `const ${local2} = typeof ${tokenIdent} === "object" && ${tokenIdent} && "factory" in ${tokenIdent} && typeof (${tokenIdent} as any).factory === "function" ? (${tokenIdent} as any).factory() : undefined;`;
+          return { constLine, key, expr: local2 };
+        }
         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);
+        const args = provider.deps.map((dep) => this.depExpr(dep, kind, provider.optionalDeps?.includes(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, provider.optionalDeps?.includes(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, controller.optionalDeps?.includes(dep))).join(", ");
     const key = camelName(controller.className);
     const local = this.localVar(controller.className, kind);
     return { constLine: `const ${local} = new ${className}(${args});`, key, expr: local };
@@ -972,7 +1874,7 @@ ${indent(item, 2)}`).join(",")}
     locals.set(token, local);
     return local;
   }
-  depExpr(token, kind) {
+  depExpr(token, kind, isOptional = false) {
     if (kind === "request" && isRequestContextToken(token, this.graph.tokenNames))
       return "ctx";
     if (kind === "job" && isJobContextToken(token, this.graph.tokenNames))
@@ -983,7 +1885,7 @@ ${indent(item, 2)}`).join(",")}
         return this.locals[kind].get(token) ?? camelName(token);
       }
       if (own.kind === "existing" && factoryOfScope(own.scope) === kind) {
-        return this.depExpr(own.useExisting ?? token, kind);
+        return this.depExpr(own.useExisting ?? token, kind, isOptional);
       }
       if (kind === "services") {
         return `services.${camelName(token)}`;
@@ -998,9 +1900,18 @@ ${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 (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) {
@@ -1022,46 +1933,266 @@ function orderProviders(providers) {
   }
   return result;
 }
-
-// src/profiles.ts
-var MODULAR_MONOLITH_RULES = [
-  {
-    sourceTag: "type:feature",
-    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
-  },
-  {
-    sourceTag: "type:root",
-    onlyDependOnLibsWithTags: ["type:feature", "type:core", "type:shared", "type:domain"]
-  },
-  {
-    sourceTag: "type:app",
-    onlyDependOnLibsWithTags: ["type:feature", "type:core", "type:shared", "type:domain"]
-  },
-  {
-    sourceTag: "type:core",
-    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
-  },
-  {
-    sourceTag: "type:shared",
-    bannedDependenciesWithTags: ["type:feature", "type:core", "type:root", "type:app"]
+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("")}
+  },`);
+    }
   }
-];
-var ANGULAR_ENTERPRISE_RULES = [
-  {
-    sourceTag: "type:feature",
-    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
-  },
-  {
-    sourceTag: "type:ui",
-    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
-  },
-  {
-    sourceTag: "type:data-access",
-    bannedDependenciesWithTags: ["type:feature", "type:ui", "type:root", "type:app"]
-  },
-  {
-    sourceTag: "type:util",
-    bannedDependenciesWithTags: ["type:feature", "type:ui", "type:data-access", "type:root", "type:app"]
+  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 = [
+  {
+    sourceTag: "type:feature",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:root",
+    onlyDependOnLibsWithTags: ["type:feature", "type:core", "type:shared", "type:domain"]
+  },
+  {
+    sourceTag: "type:app",
+    onlyDependOnLibsWithTags: ["type:feature", "type:core", "type:shared", "type:domain"]
+  },
+  {
+    sourceTag: "type:core",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:shared",
+    bannedDependenciesWithTags: ["type:feature", "type:core", "type:root", "type:app"]
+  }
+];
+var ANGULAR_ENTERPRISE_RULES = [
+  {
+    sourceTag: "type:feature",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:ui",
+    bannedDependenciesWithTags: ["type:feature", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:data-access",
+    bannedDependenciesWithTags: ["type:feature", "type:ui", "type:root", "type:app"]
+  },
+  {
+    sourceTag: "type:util",
+    bannedDependenciesWithTags: ["type:feature", "type:ui", "type:data-access", "type:root", "type:app"]
   },
   {
     sourceTag: "type:shared",
@@ -1196,6 +2327,53 @@ 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" },
+  "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" },
+  "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 = [];
@@ -1207,12 +2385,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
       });
     }
   }
@@ -1236,17 +2417,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) {
@@ -1266,20 +2473,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) {
@@ -1289,6 +2604,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);
+          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);
+          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) {
@@ -1296,33 +2678,58 @@ 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);
+          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);
+          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 isOptional = provider.optionalDeps?.includes(dep);
         const resolved = resolveDep(module, 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);
+              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;
@@ -1375,18 +2782,116 @@ 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 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);
+      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}`;
@@ -1405,12 +2910,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;
@@ -1429,6 +2938,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]));
@@ -1445,12 +2995,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;
@@ -1498,12 +3052,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
       });
     }
   }
@@ -1514,7 +3071,7 @@ function detectOrphanModules(graph) {
 import { existsSync as existsSync2, readFileSync } from "node:fs";
 import { join as join3 } from "node:path";
 async function compileProject(options) {
-  const graph = await analyzeProject(options.rootDir, options.include);
+  const graph = await analyzeProject(options.rootDir, options.include, options.cache);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, {
@@ -1533,14 +3090,25 @@ async function compileProject(options) {
         diagnostic.severity = "error";
     }
   }
-  const written = await generateApplication(graph, {
+  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === "error");
+  const written = !hasErrors || options.writeOnError !== false ? await generateApplication(graph, {
     rootDir: options.rootDir,
-    outDir: options.outDir
-  });
-  return { diagnostics, graph, written };
+    outDir: options.outDir,
+    generateClient: options.generateClient,
+    generatePermissions: options.generatePermissions,
+    treeShakeUnusedProviders: options.treeShakeUnusedProviders
+  }) : [];
+  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);
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, {
@@ -1561,12 +3129,21 @@ async function checkProject(options) {
   }
   const rendered = renderApplication(graph, {
     rootDir: options.rootDir,
-    outDir: options.outDir
+    outDir: options.outDir,
+    generateClient: options.generateClient,
+    generatePermissions: options.generatePermissions,
+    treeShakeUnusedProviders: options.treeShakeUnusedProviders
   });
   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);
@@ -1587,6 +3164,509 @@ async function checkProject(options) {
   };
 }
 
+// src/inspect.ts
+import { existsSync as existsSync3 } from "node:fs";
+import { join as join4 } 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: existsSync3(rootDir),
+      detail: existsSync3(rootDir) ? rootDir : `missing: ${rootDir}`
+    },
+    {
+      name: "tsconfig",
+      ok: existsSync3(join4(rootDir, "tsconfig.json")),
+      detail: existsSync3(join4(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(`
+`);
+}
+
+// src/watch.ts
+import { watch } from "node:fs";
+import { relative as relative3, resolve as resolve2 } from "node:path";
+
+// src/incremental.ts
+import { createHash as createHash2 } from "node:crypto";
+import { access, readdir, readFile } from "node:fs/promises";
+import { relative as relative2, resolve, sep as sep2 } from "node:path";
+function createDependencyGraphCache() {
+  return {
+    modules: new Map,
+    fileHashes: new Map
+  };
+}
+function createIncrementalCompiler() {
+  let previousSnapshot;
+  let previousResult;
+  const cache = createDependencyGraphCache();
+  return {
+    async compile(options, changedPaths) {
+      const snapshot = changedPaths && previousSnapshot ? await updateSnapshot(previousSnapshot, options, changedPaths) : await createSnapshot(options);
+      const changedFiles = changedPaths && previousSnapshot ? diffFiles(previousSnapshot.files, snapshot.files) : diffFiles(previousSnapshot?.files, snapshot.files);
+      const cacheHit = Boolean(previousSnapshot && previousSnapshot.optionsKey === snapshot.optionsKey && changedFiles.length === 0);
+      if (cacheHit && previousResult) {
+        return {
+          ...previousResult,
+          stats: {
+            cacheHit: true,
+            changedFiles: [],
+            affectedModules: [],
+            reusedModules: previousResult.graph.modules.map((m) => m.name),
+            reanalyzedModules: []
+          }
+        };
+      }
+      if (previousResult && previousSnapshot && changedFiles.length > 0 && !await requiresGraphRebuild(options.rootDir, changedFiles)) {
+        const stats2 = {
+          cacheHit: true,
+          changedFiles,
+          affectedModules: findAffectedModules(previousResult.graph.modules, previousResult.graph.modules, changedFiles),
+          reusedModules: previousResult.graph.modules.map((m) => m.name),
+          reanalyzedModules: []
+        };
+        previousSnapshot = snapshot;
+        return { ...previousResult, written: [], stats: stats2 };
+      }
+      const activeCache = options.cache ?? cache;
+      if (!activeCache.dependencyGraph && previousResult) {
+        activeCache.dependencyGraph = new ModuleDependencyGraph(previousResult.graph.modules);
+      }
+      const result = await compileProject({ ...options, cache: activeCache });
+      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;
+      return { ...result, stats };
+    },
+    reset() {
+      previousSnapshot = undefined;
+      previousResult = undefined;
+      cache.modules.clear();
+      cache.fileHashes.clear();
+      cache.dependencyGraph = undefined;
+    },
+    getCache() {
+      return cache;
+    }
+  };
+}
+async function updateSnapshot(previous, options, changedPaths) {
+  const rootDir = resolve(options.rootDir);
+  const outDir = resolve(options.outDir);
+  const files = { ...previous.files };
+  for (const changedPath of changedPaths) {
+    const absolutePath = resolve(rootDir, changedPath);
+    if (absolutePath === outDir || absolutePath.startsWith(`${outDir}/`))
+      continue;
+    const relativePath = relative2(rootDir, absolutePath).split(sep2).join("/");
+    try {
+      await access(absolutePath);
+      const content = await readFile(absolutePath);
+      files[relativePath] = createHash2("sha256").update(content).digest("hex");
+    } catch {
+      delete files[relativePath];
+    }
+  }
+  return { files, optionsKey: optionsKeyOf(options) };
+}
+async function createSnapshot(options) {
+  const rootDir = resolve(options.rootDir);
+  const outDir = resolve(options.outDir);
+  const paths = await listSourceFiles(rootDir, outDir);
+  const files = {};
+  for (const path of paths) {
+    const content = await readFile(path);
+    files[relative2(rootDir, path).split(sep2).join("/")] = createHash2("sha256").update(content).digest("hex");
+  }
+  return { files, optionsKey: optionsKeyOf(options) };
+}
+function optionsKeyOf(options) {
+  return JSON.stringify({
+    include: options.include,
+    strict: options.strict,
+    moduleBoundaryPreset: options.moduleBoundaryPreset,
+    moduleBoundaries: options.moduleBoundaries,
+    allowRouteCommandBindings: options.allowRouteCommandBindings,
+    commandCapabilities: options.commandCapabilities,
+    disallowControllerDirectDb: options.disallowControllerDirectDb,
+    detectOrphanModules: options.detectOrphanModules,
+    generateClient: options.generateClient,
+    generatePermissions: options.generatePermissions
+  });
+}
+async function requiresGraphRebuild(rootDir, changedFiles) {
+  for (const relativePath of changedFiles) {
+    const path = resolve(rootDir, relativePath);
+    try {
+      const source = await readFile(path, "utf8");
+      if (/@(?:Module|Injectable|Inject|Controller|Command|Query)\b|new\s+InjectionToken\b|\bdefineModule\s*\(/.test(source))
+        return true;
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
+async function listSourceFiles(rootDir, outDir) {
+  const result = [];
+  const visit = async (directory) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = resolve(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);
+        }
+        this.dependents.get(imp).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);
+    }
+    this.fileOwners.get(normalized).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 Array.from(this.moduleMap.keys());
+    }
+    const affected = new Set(directlyAffected);
+    const queue = Array.from(directlyAffected);
+    while (queue.length > 0) {
+      const current = queue.shift();
+      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 = resolve2(options.rootDir);
+  const outDir = resolve2(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;
+  let rejectReady;
+  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 = resolve2(rootDir, filename.toString());
+      const relativePath = relative3(outDir, changedPath);
+      if (!relativePath.startsWith("..") && relativePath !== "")
+        return;
+      if (/\.(tsx?|mts|cts)$/.test(changedPath))
+        schedule(relative3(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/cli.ts
 function printUsage() {
   console.log(`
@@ -1595,15 +3675,27 @@ function printUsage() {
 Usage:
   supacloud-compiler compile [rootDir] [options]
   supacloud-compiler check   [rootDir] [options]
+  supacloud-compiler dev     [rootDir] [options]
+  supacloud-compiler graph   [rootDir] [options]
+  supacloud-compiler explain <name> [rootDir] [options]
+  supacloud-compiler doctor  [rootDir] [options]
 
 Commands:
   compile             Compile application modules and generate artifacts
   check               Check artifact drift and run governance gates
+  dev                 Watch source files and recompile on changes
+  graph               Print the discovered application graph
+  explain             Explain a module, provider, or external token
+  doctor              Run project and generated-artifact health checks
 
 Options:
   --root, -r <dir>    Application source root (default: current directory or first positional argument)
   --out, -o <dir>     Artifact output directory (default: <rootDir>/generated)
   --strict            Treat all warnings as errors
+  --client            Generate typed API client in client.ts
+  --permissions       Generate typed permissions registry in permissions.ts
+  --debounce <ms>     Debounce source changes in dev mode (default: 100)
+  --json              Print machine-readable output for graph/explain/doctor
   --preset, -p <name> Architecture preset ('modular-monolith' | 'angular-enterprise' | 'clean-architecture')
   --help, -h          Show this help
 `);
@@ -1615,7 +3707,7 @@ async function run() {
     process.exit(0);
   }
   const command = args[0];
-  if (command !== "compile" && command !== "check") {
+  if (!["compile", "check", "dev", "graph", "explain", "doctor"].includes(command)) {
     console.error(`Error: unknown command "${command}"`);
     printUsage();
     process.exit(1);
@@ -1623,7 +3715,12 @@ async function run() {
   let rootDir = ".";
   let outDir;
   let strict = false;
+  let generateClient = false;
+  let generatePermissions = false;
   let preset;
+  let debounceMs = 100;
+  let query;
+  let json = false;
   for (let i = 1;i < args.length; i++) {
     const arg = args[i];
     if (arg === "--root" || arg === "-r") {
@@ -1632,26 +3729,41 @@ async function run() {
       outDir = args[++i];
     } else if (arg === "--strict") {
       strict = true;
+    } else if (arg === "--client") {
+      generateClient = true;
+    } else if (arg === "--permissions") {
+      generatePermissions = true;
+    } else if (arg === "--debounce") {
+      debounceMs = Number(args[++i]);
+      if (!Number.isFinite(debounceMs) || debounceMs < 0) {
+        console.error("Error: --debounce must be a non-negative number");
+        process.exit(1);
+      }
+    } else if (arg === "--json") {
+      json = true;
     } else if (arg === "--preset" || arg === "-p") {
       preset = args[++i];
     } else if (!arg.startsWith("-") && rootDir === ".") {
-      rootDir = arg;
+      if (command === "explain" && !query)
+        query = arg;
+      else
+        rootDir = arg;
+    } else if (!arg.startsWith("-") && command === "explain" && !query) {
+      query = arg;
     }
   }
-  const resolvedRoot = resolve(process.cwd(), rootDir);
-  const resolvedOut = outDir ? resolve(process.cwd(), outDir) : resolve(resolvedRoot, "generated");
+  const resolvedRoot = resolve3(process.cwd(), rootDir);
+  const resolvedOut = outDir ? resolve3(process.cwd(), outDir) : resolve3(resolvedRoot, "generated");
   if (command === "compile") {
     const result = await compileProject({
       rootDir: resolvedRoot,
       outDir: resolvedOut,
       strict,
-      moduleBoundaryPreset: preset
+      moduleBoundaryPreset: preset,
+      generateClient,
+      generatePermissions
     });
-    for (const diag of result.diagnostics) {
-      const loc = diag.file ? ` ${diag.file}${diag.line ? `:${diag.line}` : ""}` : "";
-      const log = diag.severity === "error" ? console.error : console.warn;
-      log(`[${diag.severity}] ${diag.code}${loc}: ${diag.message}`);
-    }
+    printDiagnostics(result.diagnostics);
     const errors = result.diagnostics.filter((d) => d.severity === "error");
     if (errors.length > 0) {
       console.error(`
@@ -1662,18 +3774,16 @@ Compilation failed with ${errors.length} error(s).`);
 Compilation succeeded. Generated artifacts:
 ${result.written.map((f) => `  - ${f}`).join(`
 `)}`);
-  } else {
+  } else if (command === "check") {
     const result = await checkProject({
       rootDir: resolvedRoot,
       outDir: resolvedOut,
       strict,
-      moduleBoundaryPreset: preset
+      moduleBoundaryPreset: preset,
+      generateClient,
+      generatePermissions
     });
-    for (const diag of result.diagnostics) {
-      const loc = diag.file ? ` ${diag.file}${diag.line ? `:${diag.line}` : ""}` : "";
-      const log = diag.severity === "error" ? console.error : console.warn;
-      log(`[${diag.severity}] ${diag.code}${loc}: ${diag.message}`);
-    }
+    printDiagnostics(result.diagnostics);
     const errors = result.diagnostics.filter((d) => d.severity === "error");
     if (errors.length > 0) {
       console.error(`
@@ -1690,6 +3800,91 @@ Artifact drift detected:`);
       process.exit(1);
     }
     console.log("Artifact check passed: disk files match compiler output with no drift.");
+  } else if (command === "dev") {
+    const handle = watchProject({
+      rootDir: resolvedRoot,
+      outDir: resolvedOut,
+      strict,
+      moduleBoundaryPreset: preset,
+      debounceMs,
+      generateClient,
+      generatePermissions,
+      onEvent: (event) => {
+        if (event.type === "compile-start") {
+          console.log(event.initial ? `
+Initial compilation...` : `
+Source change detected; compiling...`);
+          return;
+        }
+        printDiagnostics(event.diagnostics);
+        if (event.type === "compile-error") {
+          console.error(`Compilation failed; keeping the last successful artifacts (${event.durationMs}ms).`);
+        } else {
+          const cache = event.stats?.cacheHit ? "cache hit" : "recompiled";
+          const affected = event.stats?.affectedModules?.length ? `; affected modules: ${event.stats.affectedModules.join(", ")}` : "";
+          console.log(`Compilation succeeded in ${event.durationMs}ms (${cache}${affected}).`);
+        }
+      }
+    });
+    const close = async () => {
+      await handle.close();
+      process.exit(0);
+    };
+    process.once("SIGINT", () => void close());
+    process.once("SIGTERM", () => void close());
+    await handle.ready;
+    await new Promise(() => {
+      return;
+    });
+  } else if (command === "graph") {
+    const graph = await analyzeProject(resolvedRoot);
+    if (json)
+      console.log(JSON.stringify(graph, null, 2));
+    else
+      console.log(formatGraph(graph));
+  } else if (command === "explain") {
+    if (!query) {
+      console.error("Error: explain requires a module, provider, or external token name");
+      process.exit(1);
+    }
+    try {
+      const graph = await analyzeProject(resolvedRoot);
+      const explanation = explainGraph(graph, query);
+      if (json)
+        console.log(JSON.stringify({ subject: query, explanation }, null, 2));
+      else
+        console.log(explanation);
+    } catch (error) {
+      console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+  } else {
+    const result = await checkProject({
+      rootDir: resolvedRoot,
+      outDir: resolvedOut,
+      strict,
+      moduleBoundaryPreset: preset
+    });
+    const doctor = doctorProject(resolvedRoot, resolvedOut, result.graph, result.upToDate, result.diagnostics);
+    if (json) {
+      console.log(JSON.stringify(doctor, null, 2));
+    } else {
+      for (const check of doctor.checks)
+        console.log(`${check.ok ? "OK" : "FAIL"} ${check.name}: ${check.detail}`);
+      printDiagnostics(doctor.diagnostics);
+    }
+    if (doctor.errors > 0)
+      process.exit(1);
+  }
+}
+function printDiagnostics(diagnostics) {
+  for (const diag of diagnostics) {
+    const loc = diag.file ? ` ${diag.file}${diag.line ? `:${diag.line}` : ""}` : "";
+    const log = diag.severity === "error" ? console.error : console.warn;
+    log(`[${diag.severity}] ${diag.code}${loc}: ${diag.message}`);
+    if (diag.suggestion) {
+      console.log(`  Hint: ${diag.suggestion}`);
+    }
   }
 }
 run().catch((err) => {