@supacloud/compiler 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @supacloud/compiler
+
+SupaCloud 应用静态编译器：读取 `@supacloud/app` 装饰器元数据的源码 AST（ts-morph），构建 ApplicationGraph，做静态校验，并生成**无反射、无容器**的工厂代码与 manifest。
+
+本包不依赖 `@supacloud/app`：AST 只按装饰器名匹配（`Module`/`Injectable`/`Inject`/`Command`/`Query`/`Controller`/`Get`/`Post`/`Put`/`Patch`/`Delete`/`defineModule`/`InjectionToken`），不校验 import 来源。
+
+## 安装
+
+```bash
+bun add @supacloud/compiler
+```
+
+## API
+
+```ts
+import { analyzeProject, compileProject, validateGraph } from "@supacloud/compiler";
+
+// 完整流程：分析 → 校验 → 写出 application.ts 与 app.manifest.json
+const result = await compileProject({
+  rootDir: "/path/to/app",            // 项目根（含 tsconfig）
+  include: ["**/*.ts"],               // 可选，默认 ['**/*.module.ts', '**/*.ts']
+  outDir: "/path/to/app/generated",   // 生成目录
+  strict: false,                      // true 时 warn 级诊断升级为 error
+});
+result.diagnostics; // Diagnostic[]
+result.graph;       // ApplicationGraph
+result.written;     // 写出的绝对路径
+
+// 只做分析 / 只做校验
+const graph = await analyzeProject("/path/to/app");
+const diagnostics = validateGraph(graph, /* strict */ false);
+```
+
+### ApplicationGraph
+
+```ts
+interface ApplicationGraph {
+  modules: ModuleNode[];     // 模块：providers/controllers/commands/queries/exports/imports
+  externalTokens: string[];  // 被依赖但无任何模块提供的 token（平台注入，如 DB_CLIENT、REQUEST_CONTEXT）
+}
+```
+
+详见 `src/types.ts`。provider 的 scope 解析顺序：provider 对象显式 `scope` > `@Injectable({ scope })` > InjectionToken 定义处的 `{ scope }` 选项 > `application`。deps 解析顺序：对象 provider 的 `deps` 数组 > `@Injectable({ deps })` > 构造函数 `@Inject(token)` 参数装饰器 > 构造函数参数类型名（仅当引用已知 token/类，否则 warn `missing-deps`）。
+
+## 生成产物
+
+`<outDir>/application.ts`（头注释 `// GENERATED BY @supacloud/compiler — do not edit`）：
+
+- 文件顶部本地声明 `CompiledRoute` / `CompiledController` / `CompiledModule` 接口，不 import 任何外部包。
+- `createCompiledModules(deps)` 按 imports 拓扑序返回模块描述：`{ name, createServices, createRequestScope?, createJobScope?, controllers }`。
+- 每个模块一个 `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`。
+- services 对象的 key 为 token 名的 camelCase：`CaseService → caseService`、`CASE_REPOSITORY → caseRepository`、`LOGGER → logger`。
+- controller 描述静态给出：`{ path, serviceKey, scope, routes: [{ method, path, handler, body?, params?, query?, response? }] }`，schema 直接引用 import 进来的对象。
+
+`<outDir>/app.manifest.json`：`{ version: 1, modules, externalTokens }`，供 CLI graph/explain 使用。
+
+## 诊断码
+
+| code | 级别 | 含义 |
+| --- | --- | --- |
+| `circular-dependency` | error | provider 级循环依赖（message 含环路径） |
+| `scope-violation` | error | application provider 依赖 request/job provider（controller 不受限） |
+| `module-boundary` | error | 依赖的 token 由未 import 的模块提供 |
+| `unresolved-token` | error | 依赖的 token 无法解析且不属于平台注入 |
+| `duplicate-token` | error | 同一 token 在同模块重复注册 |
+| `command-missing-permission` | warn（strict 时 error） | `@Command` 未声明 permission |
+| `missing-deps` | warn（strict 时 error） | 构造/工厂依赖无法静态解析 |
+
+依赖的 token 全图都无 provider 时不报错，记入 `externalTokens`（平台注入）。
+
+## 开发
+
+```bash
+bun install
+bun run typecheck
+bun run typecheck:test
+bun test
+bun run build
+```
+
+## License
+
+MIT

package/dist/analyze.d.ts

@@ -0,0 +1,7 @@
+import type { ApplicationGraph } from "./types";
+/**
+ * 分析 rootDir 下的源码（ts-morph AST，无类型检查依赖），构建 ApplicationGraph。
+ * 装饰器仅按名字匹配（Module/Injectable/Inject/Command/Query/Controller/Get/...），
+ * 不校验 import 来源，因此本包不需要依赖 @supacloud/app。
+ */
+export declare function analyzeProject(rootDir: string, include?: string[]): Promise<ApplicationGraph>;

package/dist/compile.d.ts

@@ -0,0 +1,6 @@
+import type { CompileOptions, CompileResult } from "./types";
+/**
+ * 完整编译流程：AST 分析 → 校验 → 生成静态工厂代码与 manifest。
+ * 即使存在 error 级诊断也会照常写出文件，由调用方根据 diagnostics 决定是否采用。
+ */
+export declare function compileProject(options: CompileOptions): Promise<CompileResult>;

package/dist/generate.d.ts

@@ -0,0 +1,10 @@
+import type { ApplicationGraph } from "./types";
+export interface GenerateOptions {
+    rootDir: string;
+    outDir: string;
+}
+/**
+ * 生成静态工厂代码（application.ts）与 app.manifest.json，返回写入的绝对路径。
+ * 生成代码只 import 业务类/schema，不 import @supacloud/app，运行期无反射、无容器。
+ */
+export declare function generateApplication(graph: ApplicationGraph, options: GenerateOptions): Promise<string[]>;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { analyzeProject } from "./analyze";
+export { compileProject } from "./compile";
+export { generateApplication } from "./generate";
+export type { GenerateOptions } from "./generate";
+export { validateGraph } from "./validate";
+export { camelName } from "./util";
+export type { ApplicationGraph, CommandNode, CompileOptions, CompileResult, ControllerNode, Diagnostic, ModuleNode, ProviderKind, ProviderNode, QueryNode, RouteNode, Scope, TokenKind, } from "./types";