@supacloud/compiler 0.6.0 → 0.6.2

package/README.md

@@ -66,7 +66,7 @@ interface ApplicationGraph {
 - `makeEnvironmentProviders`、`provideToken`、`provideAppInitializer`、`provideEnvironmentInitializer`、`provideRouter` 和 `provideHttpClient` 的可静态展开部分会在 AST 分析阶段展开为普通 provider；不支持静态安全展开的动态参数会产生诊断，不会被静默丢弃。
 - 每个模块一个 `create<Name>Services(deps, imported)`：实例化 application 级 provider；dep 解析顺序为本模块 services > imports 模块导出的 services（`imported.<module>.<key>`）> 平台注入（`deps.<camelName>`）。
 - 含 request 级 provider/controller 的模块额外生成 `create<Name>RequestScope(services, ctx)`：依赖 `REQUEST_CONTEXT`（或 token name `supacloud.request-context`）的参数传 `ctx`，其余经 `services` 解析（运行期负责把 imports 模块导出的 application 服务合并进 `services`）；job 级同理生成 `create<Name>JobScope`。
-- 含 request/job 级 provider 或 controller 的模块同时生成静态 `destroy<Name>RequestScope(scope)` / `destroy<Name>JobScope(scope)`，按编译期确定的逆创建顺序调用已知 `onDestroy` 方法；不会运行时扫描或解析 Token。
+- 含 request/job 级 provider 或 controller 的模块同时生成异步静态 `create<Name>RequestScope` / `create<Name>JobScope` 与 `destroy<Name>RequestScope(scope)` / `destroy<Name>JobScope(scope)`；factory 在构造中途失败时按编译期确定的逆创建顺序回滚已知 `onDestroy` 方法，不会运行时扫描或解析 Token。
 - `@Host()` 在 EnvironmentInjector 作用域中保留元数据但不改变解析，因为 SupaCloud 没有 Angular 元素注入器树；`@Self()` / `@SkipSelf()` 由静态 factory 按当前 scope 与模块可见性执行。
 - AOP 只支持静态边界：`ModuleOptions.aspects`、`RouteOptions.aspects`、`CommandOptions.aspects` 和 `JobOptions.aspects` 必须是显式数组字面量，元素必须是可解析的函数标识符。生成器会直接 import aspect 并生成固定顺序的 onion chain，不使用 Proxy、Reflect 扫描、动态 pointcut 或运行时注册。
 - 执行顺序为 `module -> route -> command -> commandGovernance -> handler`；Job 使用 `module -> job -> executor -> run/execute`，并在 finally 中销毁 job scope。
@@ -90,6 +90,7 @@ interface ApplicationGraph {
 | `duplicate-route` | error | 规范化后 HTTP method + path 冲突 |
 | `route-command-unresolved` | error | 路由绑定了本模块未声明的 command 类 |
 | `command-missing-permission` | error | `@Command` 未声明 permission |
+| `invalid-job-scope` | error | `@Job` 使用了不支持的 `request` scope |
 | `provider-type-mismatch` | error | Provider 的 useClass/useValue/useFactory/useExisting 不满足 InjectionToken 的静态类型契约 |
 | `unsupported-provider-helper` | warn（strict 时 error） | functional provider 的动态参数无法安全展开为静态 factory |
 | `dynamic-aspect-reference` | error | aspects 不是显式数组字面量，或包含 spread/表达式/字符串 pointcut |

package/dist/cli.js

@@ -329,6 +329,59 @@ function readProjectConfig(rootDir) {
   };
 }
 
+// src/util.ts
+function camelName(token) {
+  const isConstantCase = token.includes("_") || !/[a-z]/.test(token);
+  if (isConstantCase) {
+    return token.toLowerCase().split("_").filter((part) => part.length > 0).map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  }
+  return token.charAt(0).toLowerCase() + token.slice(1);
+}
+function relativeImportPath(fromDir, toFile) {
+  const fromParts = fromDir.split("/").filter(Boolean);
+  const toParts = toFile.split("/").filter(Boolean);
+  let common = 0;
+  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
+    common += 1;
+  }
+  const ups = fromParts.length - common;
+  const downs = toParts.slice(common);
+  const last = downs[downs.length - 1]?.replace(/\.(ts|tsx|js|mts|cts)$/, "") ?? "";
+  const segments = [...Array(ups).fill(".."), ...downs.slice(0, -1), last];
+  const joined = segments.join("/");
+  return joined.startsWith("..") ? joined : `./${joined}`;
+}
+var REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context";
+var JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
+function isRequestContextToken(token, tokenNames) {
+  return token === "REQUEST_CONTEXT" || tokenNames?.[token] === REQUEST_CONTEXT_TOKEN_NAME;
+}
+function isJobContextToken(token, tokenNames) {
+  return token === "JOB_CONTEXT" || tokenNames?.[token] === JOB_CONTEXT_TOKEN_NAME;
+}
+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/analyze.ts
 var DEFAULT_INCLUDE = ["**/*.module.ts", "**/*.ts"];
 var ROUTE_DECORATORS = {
@@ -825,12 +878,12 @@ function parseModule(candidate, nameByNode, ctx) {
     if (!decl || !ts3.isClassDeclaration(decl))
       continue;
     const className2 = decl.name?.text ?? el.text;
-    const registeredProvider = providers.find((provider) => provider.token === className2);
+    const registeredProvider = providers.find((provider) => provider.token === className2 || provider.useClass === className2);
     if (registeredProvider)
       continue;
     const deps = classDeps(decl, ctx);
     const injectable = parseInjectableOptions(decl, ctx);
-    const scope = injectable?.scope === "application" ? "application" : "job";
+    const scope = injectable?.scope ?? "job";
     providers.push({
       token: className2,
       tokenKind: "class",
@@ -905,12 +958,27 @@ function parseModule(candidate, nameByNode, ctx) {
       const meta = decoratorObjectArg(jobDec);
       if (meta) {
         const injectable = parseInjectableOptions(cls, ctx);
-        const provider = providers.find((candidate2) => candidate2.token === (cls.name?.text ?? "<anonymous>"));
-        const aspects2 = parseAspectRefs(getProp(meta, "aspects"), ctx, `job ${cls.name?.text ?? "<anonymous>"}`);
+        const className2 = cls.name?.text ?? "<anonymous>";
+        const provider = providers.find((candidate2) => candidate2.token === className2 || candidate2.useClass === className2);
+        const scope = provider?.scope ?? injectable?.scope ?? "job";
+        if (scope === "request") {
+          ctx.diagnostics.push({
+            severity: "error",
+            code: "invalid-job-scope",
+            message: `job ${className2} 不能使用 request scope；Job 只能使用 application 或 job scope`,
+            file: sourcePath(ctx.rootDir, cls.getSourceFile().fileName),
+            line: lineOf(cls),
+            suggestion: "移除 request scope，或改用 application/job scope。",
+            errorCode: "SC4007",
+            docsUrl: "https://supacloud.dev/errors/SC4007"
+          });
+        }
+        const aspects2 = parseAspectRefs(getProp(meta, "aspects"), ctx, `job ${className2}`);
         jobs.push({
-          className: cls.name?.text ?? "<anonymous>",
-          name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>",
-          scope: provider?.scope ?? (injectable?.scope === "application" ? "application" : "job"),
+          className: className2,
+          name: stringLiteralProp(meta, "name") ?? className2,
+          serviceKey: camelName(provider?.token ?? className2),
+          scope,
           ...aspects2.length > 0 ? { aspects: aspects2 } : {}
         });
       }
@@ -2116,61 +2184,6 @@ function warn(ctx, code, message, file, line) {
 import { createHash as createHash4 } from "node:crypto";
 import { access, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
-
-// src/util.ts
-function camelName(token) {
-  const isConstantCase = token.includes("_") || !/[a-z]/.test(token);
-  if (isConstantCase) {
-    return token.toLowerCase().split("_").filter((part) => part.length > 0).map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
-  }
-  return token.charAt(0).toLowerCase() + token.slice(1);
-}
-function relativeImportPath(fromDir, toFile) {
-  const fromParts = fromDir.split("/").filter(Boolean);
-  const toParts = toFile.split("/").filter(Boolean);
-  let common = 0;
-  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
-    common += 1;
-  }
-  const ups = fromParts.length - common;
-  const downs = toParts.slice(common);
-  const last = downs[downs.length - 1]?.replace(/\.(ts|tsx|js|mts|cts)$/, "") ?? "";
-  const segments = [...Array(ups).fill(".."), ...downs.slice(0, -1), last];
-  const joined = segments.join("/");
-  return joined.startsWith("..") ? joined : `./${joined}`;
-}
-var REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context";
-var JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
-function isRequestContextToken(token, tokenNames) {
-  return token === "REQUEST_CONTEXT" || tokenNames?.[token] === REQUEST_CONTEXT_TOKEN_NAME;
-}
-function isJobContextToken(token, tokenNames) {
-  return token === "JOB_CONTEXT" || tokenNames?.[token] === JOB_CONTEXT_TOKEN_NAME;
-}
-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";
 var INTERFACES = `export interface CompiledRoute {
   method: string;
@@ -2258,13 +2271,13 @@ export interface CompiledModule {
     services: Record<string, unknown>,
     ctx: unknown,
     imported?: Record<string, Record<string, unknown>>,
-  ): Record<string, unknown>;
+  ): Promise<Record<string, unknown>>;
   destroyRequestScope?(scope: Record<string, unknown>): Promise<void>;
   createJobScope?(
     services: Record<string, unknown>,
     ctx: unknown,
     imported?: Record<string, Record<string, unknown>>,
-  ): Record<string, unknown>;
+  ): Promise<Record<string, unknown>>;
   destroyJobScope?(scope: Record<string, unknown>): Promise<void>;
   controllers: CompiledController[];
   commands: CompiledCommand[];
@@ -2742,7 +2755,7 @@ ${indent(item, 2)}`).join(",")}
     const jobs = this.module.jobs ?? [];
     if (jobs.length === 0)
       return "[]";
-    return `[${jobs.map((job) => `{ className: ${JSON.stringify(job.className)}, name: ${JSON.stringify(job.name)}, serviceKey: ${JSON.stringify(camelName(job.className))}, scope: ${JSON.stringify(job.scope)},${job.aspects && job.aspects.length > 0 ? ` aspects: ${this.renderAspects(job.aspects)},` : ""} }`).join(", ")}]`;
+    return `[${jobs.map((job) => `{ className: ${JSON.stringify(job.className)}, name: ${JSON.stringify(job.name)}, serviceKey: ${JSON.stringify(job.serviceKey)}, scope: ${JSON.stringify(job.scope)},${job.aspects && job.aspects.length > 0 ? ` aspects: ${this.renderAspects(job.aspects)},` : ""} }`).join(", ")}]`;
   }
   renderAspects(aspects) {
     return `[${aspects.map((aspect) => this.imports.add(aspect.name, aspect.importPath, aspect.importModule)).join(", ")}]`;
@@ -2761,12 +2774,22 @@ ${indent(item, 2)}`).join(",")}
   renderScopeFactory(kind) {
     const suffix = kind === "request" ? "RequestScope" : "JobScope";
     return [
-      `function create${this.pascal}${suffix}(`,
+      `async function create${this.pascal}${suffix}(`,
       `  services: Record<string, unknown>,`,
       `  ctx: unknown,`,
       `  imported: Record<string, Record<string, unknown>> = {},`,
-      `): Record<string, unknown> {`,
-      indent(this.renderFactoryBody(kind), 2),
+      `): Promise<Record<string, unknown>> {`,
+      `  const scope: Record<string, unknown> = {};`,
+      `  try {`,
+      indent(this.renderFactoryBody(kind, true), 4),
+      `  } catch (error) {`,
+      `    try {`,
+      `      await destroy${this.pascal}${suffix}(scope);`,
+      `    } catch (cleanupError) {`,
+      `      console.error("supacloud: ${kind} scope rollback failed for ${this.module.name}", cleanupError);`,
+      `    }`,
+      `    throw error;`,
+      `  }`,
       `}`
     ].join(`
 `);
@@ -2795,7 +2818,7 @@ ${indent(item, 2)}`).join(",")}
     ].join(`
 `);
   }
-  renderFactoryBody(kind) {
+  renderFactoryBody(kind, scoped = false) {
     const providers = orderProviders(this.module.providers.filter((p) => factoryOfScope(p.scope) === kind));
     const controllers = this.module.controllers.filter((c) => factoryOfScope(c.scope) === kind);
     const lines = [];
@@ -2806,6 +2829,9 @@ ${indent(item, 2)}`).join(",")}
         const emitted = this.emitProvider(provider, kind, true);
         if (emitted.constLine)
           lines.push(emitted.constLine);
+        if (scoped) {
+          lines.push(`scope[${JSON.stringify(emitted.key)}] = [...(Array.isArray(scope[${JSON.stringify(emitted.key)}]) ? scope[${JSON.stringify(emitted.key)}] : []), ${emitted.expr}];`);
+        }
         const list = multiGroups.get(emitted.key) ?? [];
         list.push(emitted.expr);
         multiGroups.set(emitted.key, list);
@@ -2813,6 +2839,9 @@ ${indent(item, 2)}`).join(",")}
         const emitted = this.emitProvider(provider, kind, false);
         if (emitted.constLine)
           lines.push(emitted.constLine);
+        if (scoped) {
+          lines.push(`scope[${JSON.stringify(emitted.key)}] = ${emitted.expr};`);
+        }
         returns.set(emitted.key, emitted.expr);
       }
     }
@@ -2822,8 +2851,16 @@ ${indent(item, 2)}`).join(",")}
     for (const controller of controllers) {
       const emitted = this.emitController(controller, kind);
       lines.push(emitted.constLine);
+      if (scoped) {
+        lines.push(`scope[${JSON.stringify(emitted.key)}] = ${emitted.expr};`);
+      }
       returns.set(emitted.key, emitted.expr);
     }
+    if (scoped) {
+      lines.push(`return scope;`);
+      return lines.join(`
+`);
+    }
     const entries = [...returns.entries()].map(([key, expr]) => key === expr ? key : `${key}: ${expr}`);
     lines.push(`return { ${entries.join(", ")} };`);
     return lines.join(`
@@ -3019,13 +3056,9 @@ function renderClient(graph, _options) {
           title: route.title,
           data: route.data
         });
+        const routeParams = 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>";
         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),`);
+    ${route.handler}: makeRoute<{ params${routeParams.startsWith("{") ? "" : "?"}: ${routeParams}; query?: Record<string, unknown>; body?: unknown; headers?: Record<string, string> }>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}),`);
       }
       controllerEntries.push(`
   ${controllerKey}: {${routeMethods.join("")}
@@ -3042,6 +3075,13 @@ function renderClient(graph, _options) {
     "  headers?: Record<string, string>;",
     "}",
     "",
+    "export type ResponseDecoder<T> = (value: unknown) => T;",
+    "",
+    "export type RouteMethod<Options extends ClientRequestOptions = ClientRequestOptions> = {",
+    "  <T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
+    "  (options?: Options): Promise<unknown>;",
+    "};",
+    "",
     "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>,",
@@ -3087,11 +3127,23 @@ function renderClient(graph, _options) {
     "  const fetcher = config.fetch ?? globalThis.fetch.bind(globalThis);",
     '  const baseUrl = (config.baseUrl ?? "").replace(/\\/+$/, "");',
     "",
-    "  async function request<T = unknown>(",
+    "  async function request<T>(",
+    "    method: string,",
+    "    path: string,",
+    "    options: ClientRequestOptions,",
+    "    decode: ResponseDecoder<T>,",
+    "  ): Promise<T>;",
+    "  async function request(",
+    "    method: string,",
+    "    path: string,",
+    "    options?: ClientRequestOptions,",
+    "  ): Promise<unknown>;",
+    "  async function request<T>(",
     "    method: string,",
     "    path: string,",
     "    options: ClientRequestOptions = {},",
-    "  ): Promise<T> {",
+    "    decode?: ResponseDecoder<T>,",
+    "  ): Promise<T | unknown> {",
     "    let url = `${baseUrl}${path}`;",
     "    if (options.params) {",
     "      for (const [key, value] of Object.entries(options.params)) {",
@@ -3132,10 +3184,23 @@ function renderClient(graph, _options) {
     "      throw new Error(`API request failed: ${method} ${path} -> ${response.status} ${errBody}`);",
     "    }",
     '    const contentType = response.headers?.get("content-type") ?? "";',
+    "    let value: unknown;",
     '    if (contentType.includes("application/json")) {',
-    "      return response.json() as Promise<T>;",
+    "      value = await response.json();",
+    "    } else {",
+    "      value = await response.text();",
+    "    }",
+    "    return decode ? decode(value) : value;",
+    "  }",
+    "",
+    "  function makeRoute<Options extends ClientRequestOptions>(method: string, path: string): RouteMethod<Options> {",
+    "    function route<T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
+    "    function route(options?: Options): Promise<unknown>;",
+    "    function route<T>(options?: Options, decode?: ResponseDecoder<T>): Promise<T | unknown> {",
+    "      const requestOptions = options ?? {};",
+    "      return decode ? request(method, path, requestOptions, decode) : request(method, path, requestOptions);",
     "    }",
-    "    return response.text() as Promise<T>;",
+    "    return route;",
     "  }",
     "",
     "  return {",
@@ -3432,6 +3497,7 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "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" },
+  "invalid-job-scope": { code: "SC4007", docsUrl: "https://supacloud.dev/errors/SC4007" },
   "dynamic-aspect-reference": { code: "SC4010", docsUrl: "https://supacloud.dev/errors/SC4010" },
   "invalid-aspect-reference": { code: "SC4011", docsUrl: "https://supacloud.dev/errors/SC4011" },
   "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" }

package/dist/index.js

@@ -324,6 +324,59 @@ function readProjectConfig(rootDir) {
   };
 }
 
+// src/util.ts
+function camelName(token) {
+  const isConstantCase = token.includes("_") || !/[a-z]/.test(token);
+  if (isConstantCase) {
+    return token.toLowerCase().split("_").filter((part) => part.length > 0).map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  }
+  return token.charAt(0).toLowerCase() + token.slice(1);
+}
+function relativeImportPath(fromDir, toFile) {
+  const fromParts = fromDir.split("/").filter(Boolean);
+  const toParts = toFile.split("/").filter(Boolean);
+  let common = 0;
+  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
+    common += 1;
+  }
+  const ups = fromParts.length - common;
+  const downs = toParts.slice(common);
+  const last = downs[downs.length - 1]?.replace(/\.(ts|tsx|js|mts|cts)$/, "") ?? "";
+  const segments = [...Array(ups).fill(".."), ...downs.slice(0, -1), last];
+  const joined = segments.join("/");
+  return joined.startsWith("..") ? joined : `./${joined}`;
+}
+var REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context";
+var JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
+function isRequestContextToken(token, tokenNames) {
+  return token === "REQUEST_CONTEXT" || tokenNames?.[token] === REQUEST_CONTEXT_TOKEN_NAME;
+}
+function isJobContextToken(token, tokenNames) {
+  return token === "JOB_CONTEXT" || tokenNames?.[token] === JOB_CONTEXT_TOKEN_NAME;
+}
+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/analyze.ts
 var DEFAULT_INCLUDE = ["**/*.module.ts", "**/*.ts"];
 var ROUTE_DECORATORS = {
@@ -820,12 +873,12 @@ function parseModule(candidate, nameByNode, ctx) {
     if (!decl || !ts3.isClassDeclaration(decl))
       continue;
     const className2 = decl.name?.text ?? el.text;
-    const registeredProvider = providers.find((provider) => provider.token === className2);
+    const registeredProvider = providers.find((provider) => provider.token === className2 || provider.useClass === className2);
     if (registeredProvider)
       continue;
     const deps = classDeps(decl, ctx);
     const injectable = parseInjectableOptions(decl, ctx);
-    const scope = injectable?.scope === "application" ? "application" : "job";
+    const scope = injectable?.scope ?? "job";
     providers.push({
       token: className2,
       tokenKind: "class",
@@ -900,12 +953,27 @@ function parseModule(candidate, nameByNode, ctx) {
       const meta = decoratorObjectArg(jobDec);
       if (meta) {
         const injectable = parseInjectableOptions(cls, ctx);
-        const provider = providers.find((candidate2) => candidate2.token === (cls.name?.text ?? "<anonymous>"));
-        const aspects2 = parseAspectRefs(getProp(meta, "aspects"), ctx, `job ${cls.name?.text ?? "<anonymous>"}`);
+        const className2 = cls.name?.text ?? "<anonymous>";
+        const provider = providers.find((candidate2) => candidate2.token === className2 || candidate2.useClass === className2);
+        const scope = provider?.scope ?? injectable?.scope ?? "job";
+        if (scope === "request") {
+          ctx.diagnostics.push({
+            severity: "error",
+            code: "invalid-job-scope",
+            message: `job ${className2} 不能使用 request scope；Job 只能使用 application 或 job scope`,
+            file: sourcePath(ctx.rootDir, cls.getSourceFile().fileName),
+            line: lineOf(cls),
+            suggestion: "移除 request scope，或改用 application/job scope。",
+            errorCode: "SC4007",
+            docsUrl: "https://supacloud.dev/errors/SC4007"
+          });
+        }
+        const aspects2 = parseAspectRefs(getProp(meta, "aspects"), ctx, `job ${className2}`);
         jobs.push({
-          className: cls.name?.text ?? "<anonymous>",
-          name: stringLiteralProp(meta, "name") ?? cls.name?.text ?? "<anonymous>",
-          scope: provider?.scope ?? (injectable?.scope === "application" ? "application" : "job"),
+          className: className2,
+          name: stringLiteralProp(meta, "name") ?? className2,
+          serviceKey: camelName(provider?.token ?? className2),
+          scope,
           ...aspects2.length > 0 ? { aspects: aspects2 } : {}
         });
       }
@@ -2110,61 +2178,6 @@ function warn(ctx, code, message, file, line) {
 import { createHash as createHash4 } from "node:crypto";
 import { access, mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join as join2 } from "node:path";
-
-// src/util.ts
-function camelName(token) {
-  const isConstantCase = token.includes("_") || !/[a-z]/.test(token);
-  if (isConstantCase) {
-    return token.toLowerCase().split("_").filter((part) => part.length > 0).map((part, index) => index === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)).join("");
-  }
-  return token.charAt(0).toLowerCase() + token.slice(1);
-}
-function relativeImportPath(fromDir, toFile) {
-  const fromParts = fromDir.split("/").filter(Boolean);
-  const toParts = toFile.split("/").filter(Boolean);
-  let common = 0;
-  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
-    common += 1;
-  }
-  const ups = fromParts.length - common;
-  const downs = toParts.slice(common);
-  const last = downs[downs.length - 1]?.replace(/\.(ts|tsx|js|mts|cts)$/, "") ?? "";
-  const segments = [...Array(ups).fill(".."), ...downs.slice(0, -1), last];
-  const joined = segments.join("/");
-  return joined.startsWith("..") ? joined : `./${joined}`;
-}
-var REQUEST_CONTEXT_TOKEN_NAME = "supacloud.request-context";
-var JOB_CONTEXT_TOKEN_NAME = "supacloud.job-context";
-function isRequestContextToken(token, tokenNames) {
-  return token === "REQUEST_CONTEXT" || tokenNames?.[token] === REQUEST_CONTEXT_TOKEN_NAME;
-}
-function isJobContextToken(token, tokenNames) {
-  return token === "JOB_CONTEXT" || tokenNames?.[token] === JOB_CONTEXT_TOKEN_NAME;
-}
-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";
 var INTERFACES = `export interface CompiledRoute {
   method: string;
@@ -2252,13 +2265,13 @@ export interface CompiledModule {
     services: Record<string, unknown>,
     ctx: unknown,
     imported?: Record<string, Record<string, unknown>>,
-  ): Record<string, unknown>;
+  ): Promise<Record<string, unknown>>;
   destroyRequestScope?(scope: Record<string, unknown>): Promise<void>;
   createJobScope?(
     services: Record<string, unknown>,
     ctx: unknown,
     imported?: Record<string, Record<string, unknown>>,
-  ): Record<string, unknown>;
+  ): Promise<Record<string, unknown>>;
   destroyJobScope?(scope: Record<string, unknown>): Promise<void>;
   controllers: CompiledController[];
   commands: CompiledCommand[];
@@ -2736,7 +2749,7 @@ ${indent(item, 2)}`).join(",")}
     const jobs = this.module.jobs ?? [];
     if (jobs.length === 0)
       return "[]";
-    return `[${jobs.map((job) => `{ className: ${JSON.stringify(job.className)}, name: ${JSON.stringify(job.name)}, serviceKey: ${JSON.stringify(camelName(job.className))}, scope: ${JSON.stringify(job.scope)},${job.aspects && job.aspects.length > 0 ? ` aspects: ${this.renderAspects(job.aspects)},` : ""} }`).join(", ")}]`;
+    return `[${jobs.map((job) => `{ className: ${JSON.stringify(job.className)}, name: ${JSON.stringify(job.name)}, serviceKey: ${JSON.stringify(job.serviceKey)}, scope: ${JSON.stringify(job.scope)},${job.aspects && job.aspects.length > 0 ? ` aspects: ${this.renderAspects(job.aspects)},` : ""} }`).join(", ")}]`;
   }
   renderAspects(aspects) {
     return `[${aspects.map((aspect) => this.imports.add(aspect.name, aspect.importPath, aspect.importModule)).join(", ")}]`;
@@ -2755,12 +2768,22 @@ ${indent(item, 2)}`).join(",")}
   renderScopeFactory(kind) {
     const suffix = kind === "request" ? "RequestScope" : "JobScope";
     return [
-      `function create${this.pascal}${suffix}(`,
+      `async function create${this.pascal}${suffix}(`,
       `  services: Record<string, unknown>,`,
       `  ctx: unknown,`,
       `  imported: Record<string, Record<string, unknown>> = {},`,
-      `): Record<string, unknown> {`,
-      indent(this.renderFactoryBody(kind), 2),
+      `): Promise<Record<string, unknown>> {`,
+      `  const scope: Record<string, unknown> = {};`,
+      `  try {`,
+      indent(this.renderFactoryBody(kind, true), 4),
+      `  } catch (error) {`,
+      `    try {`,
+      `      await destroy${this.pascal}${suffix}(scope);`,
+      `    } catch (cleanupError) {`,
+      `      console.error("supacloud: ${kind} scope rollback failed for ${this.module.name}", cleanupError);`,
+      `    }`,
+      `    throw error;`,
+      `  }`,
       `}`
     ].join(`
 `);
@@ -2789,7 +2812,7 @@ ${indent(item, 2)}`).join(",")}
     ].join(`
 `);
   }
-  renderFactoryBody(kind) {
+  renderFactoryBody(kind, scoped = false) {
     const providers = orderProviders(this.module.providers.filter((p) => factoryOfScope(p.scope) === kind));
     const controllers = this.module.controllers.filter((c) => factoryOfScope(c.scope) === kind);
     const lines = [];
@@ -2800,6 +2823,9 @@ ${indent(item, 2)}`).join(",")}
         const emitted = this.emitProvider(provider, kind, true);
         if (emitted.constLine)
           lines.push(emitted.constLine);
+        if (scoped) {
+          lines.push(`scope[${JSON.stringify(emitted.key)}] = [...(Array.isArray(scope[${JSON.stringify(emitted.key)}]) ? scope[${JSON.stringify(emitted.key)}] : []), ${emitted.expr}];`);
+        }
         const list = multiGroups.get(emitted.key) ?? [];
         list.push(emitted.expr);
         multiGroups.set(emitted.key, list);
@@ -2807,6 +2833,9 @@ ${indent(item, 2)}`).join(",")}
         const emitted = this.emitProvider(provider, kind, false);
         if (emitted.constLine)
           lines.push(emitted.constLine);
+        if (scoped) {
+          lines.push(`scope[${JSON.stringify(emitted.key)}] = ${emitted.expr};`);
+        }
         returns.set(emitted.key, emitted.expr);
       }
     }
@@ -2816,8 +2845,16 @@ ${indent(item, 2)}`).join(",")}
     for (const controller of controllers) {
       const emitted = this.emitController(controller, kind);
       lines.push(emitted.constLine);
+      if (scoped) {
+        lines.push(`scope[${JSON.stringify(emitted.key)}] = ${emitted.expr};`);
+      }
       returns.set(emitted.key, emitted.expr);
     }
+    if (scoped) {
+      lines.push(`return scope;`);
+      return lines.join(`
+`);
+    }
     const entries = [...returns.entries()].map(([key, expr]) => key === expr ? key : `${key}: ${expr}`);
     lines.push(`return { ${entries.join(", ")} };`);
     return lines.join(`
@@ -3013,13 +3050,9 @@ function renderClient(graph, _options) {
           title: route.title,
           data: route.data
         });
+        const routeParams = 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>";
         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),`);
+    ${route.handler}: makeRoute<{ params${routeParams.startsWith("{") ? "" : "?"}: ${routeParams}; query?: Record<string, unknown>; body?: unknown; headers?: Record<string, string> }>(${JSON.stringify(route.method)}, ${JSON.stringify(fullPath)}),`);
       }
       controllerEntries.push(`
   ${controllerKey}: {${routeMethods.join("")}
@@ -3036,6 +3069,13 @@ function renderClient(graph, _options) {
     "  headers?: Record<string, string>;",
     "}",
     "",
+    "export type ResponseDecoder<T> = (value: unknown) => T;",
+    "",
+    "export type RouteMethod<Options extends ClientRequestOptions = ClientRequestOptions> = {",
+    "  <T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
+    "  (options?: Options): Promise<unknown>;",
+    "};",
+    "",
     "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>,",
@@ -3081,11 +3121,23 @@ function renderClient(graph, _options) {
     "  const fetcher = config.fetch ?? globalThis.fetch.bind(globalThis);",
     '  const baseUrl = (config.baseUrl ?? "").replace(/\\/+$/, "");',
     "",
-    "  async function request<T = unknown>(",
+    "  async function request<T>(",
+    "    method: string,",
+    "    path: string,",
+    "    options: ClientRequestOptions,",
+    "    decode: ResponseDecoder<T>,",
+    "  ): Promise<T>;",
+    "  async function request(",
+    "    method: string,",
+    "    path: string,",
+    "    options?: ClientRequestOptions,",
+    "  ): Promise<unknown>;",
+    "  async function request<T>(",
     "    method: string,",
     "    path: string,",
     "    options: ClientRequestOptions = {},",
-    "  ): Promise<T> {",
+    "    decode?: ResponseDecoder<T>,",
+    "  ): Promise<T | unknown> {",
     "    let url = `${baseUrl}${path}`;",
     "    if (options.params) {",
     "      for (const [key, value] of Object.entries(options.params)) {",
@@ -3126,10 +3178,23 @@ function renderClient(graph, _options) {
     "      throw new Error(`API request failed: ${method} ${path} -> ${response.status} ${errBody}`);",
     "    }",
     '    const contentType = response.headers?.get("content-type") ?? "";',
+    "    let value: unknown;",
     '    if (contentType.includes("application/json")) {',
-    "      return response.json() as Promise<T>;",
+    "      value = await response.json();",
+    "    } else {",
+    "      value = await response.text();",
+    "    }",
+    "    return decode ? decode(value) : value;",
+    "  }",
+    "",
+    "  function makeRoute<Options extends ClientRequestOptions>(method: string, path: string): RouteMethod<Options> {",
+    "    function route<T>(options: Options, decode: ResponseDecoder<T>): Promise<T>;",
+    "    function route(options?: Options): Promise<unknown>;",
+    "    function route<T>(options?: Options, decode?: ResponseDecoder<T>): Promise<T | unknown> {",
+    "      const requestOptions = options ?? {};",
+    "      return decode ? request(method, path, requestOptions, decode) : request(method, path, requestOptions);",
     "    }",
-    "    return response.text() as Promise<T>;",
+    "    return route;",
     "  }",
     "",
     "  return {",
@@ -3426,6 +3491,7 @@ var COMPILER_DIAGNOSTIC_CODES = {
   "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" },
+  "invalid-job-scope": { code: "SC4007", docsUrl: "https://supacloud.dev/errors/SC4007" },
   "dynamic-aspect-reference": { code: "SC4010", docsUrl: "https://supacloud.dev/errors/SC4010" },
   "invalid-aspect-reference": { code: "SC4011", docsUrl: "https://supacloud.dev/errors/SC4011" },
   "unused-root-provider": { code: "SC5001", docsUrl: "https://supacloud.dev/errors/SC5001" }

package/dist/types.d.ts

@@ -171,6 +171,8 @@ export interface CommandNode {
 export interface JobNode {
     className: string;
     name: string;
+    /** Generated services key; follows a custom useClass provider token when present. */
+    serviceKey: string;
     scope: Scope;
     aspects?: AspectRefNode[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",