@supacloud/compiler 0.15.0 → 0.19.1

package/DELIVERY.md

@@ -0,0 +1,223 @@
+# Local Delivery Planning And Builds
+
+`supacloud-compiler plan --json` is a read-only first step toward automated app
+delivery. It uses the existing source analysis and compiler checks, then groups
+HTTP routes and declared Jobs into deterministic target previews.
+
+`supacloud-compiler build-delivery --json` additionally builds independent local
+module factory bundles. It does **not** configure queues or gateways, verify remote
+hosts, deploy functions, or run an unattended AI repair loop.
+Existing compile/check/dev output remains unchanged.
+
+## Zero-Configuration HTTP
+
+```sh
+supacloud-compiler plan --json
+```
+
+All discovered HTTP routes default to `api`. Module imports contribute dependencies,
+not route ownership. A dependency module's own routes remain with their own explicit
+owner or the default API; they are not copied into the importing target.
+All discovered routes remain exposed in the plan. To make a module private, remove
+its route declarations; simply omitting a module from target configuration does not
+hide its routes.
+
+Declared Jobs default to `jobs`, require a durable queue declaration, and default
+to process isolation. A Job declaration does not rewrite a synchronous HTTP route.
+If these runtime declarations are absent, planning returns errors with no plan.
+
+## Explicit Boundaries
+
+Add an optional `delivery` section to the existing configuration:
+
+```ts
+import { defineSupacloudConfig } from "@supacloud/compiler";
+
+export default defineSupacloudConfig({
+  delivery: {
+    version: 1,
+    targets: [
+      { name: "orders", kind: "api", modules: ["orders"] },
+      {
+        name: "payment-hooks",
+        kind: "webhook",
+        modules: ["payments"],
+        isolation: "process",
+        capabilities: ["payments.verify"],
+      },
+    ],
+    runtime: {
+      processIsolation: true,
+      durableQueue: true,
+      capabilities: ["payments.verify"],
+    },
+  },
+});
+```
+
+The names in `modules` are declared module names, not class names or paths.
+Targets select all routes or all jobs belonging to those modules, depending on
+their kind. HTTP and Job ownership are independent, so one module can contribute
+HTTP to `api` and Jobs to `jobs`. Two HTTP targets cannot both own the same module.
+`api` and `jobs` are reserved for their matching workload kinds.
+
+No unused explicit target is accepted. Unknown modules, duplicate ownership,
+unresolved imports, cyclic dependencies, duplicate job names, and conflicting
+method/path patterns reject the plan. Parameter-name aliases such as `/:id` and
+`/:key` do not establish different route identities.
+
+`runtime` is a declaration only, not host attestation. `capabilities` contains
+adapter/credential boundary references, never values. Declaring a webhook target
+does not implement signature verification or authorize public ingress. The runtime
+and deployment layers must still verify these requirements before activation.
+Changing `isolation` to `shared` is an explicit relaxation requiring user review.
+
+For an AI-generated JSON declaration instead of editing executable config:
+
+```sh
+supacloud-compiler plan --delivery delivery.json --json
+```
+
+`delivery.json` contains the `delivery` object above, not the outer project config.
+It replaces, rather than merges with, `config.delivery`. The executable project
+config is still loaded normally. Invalid configuration is rejected, not echoed.
+`--write` and unknown plan arguments fail. Successful output exits 0; failures exit 1.
+
+## Programmatic Contract
+
+```ts
+import {
+  compileOptionsFromConfig,
+  loadSupacloudConfig,
+  planDeliveryProject,
+  parseDeliveryPlanResult,
+} from "@supacloud/compiler";
+
+const config = await loadSupacloudConfig();
+const result = await planDeliveryProject(compileOptionsFromConfig(config), config.delivery);
+if (result.ok) {
+  for (const target of result.plan.targets) {
+    console.log(target.name, target.routes, target.requirements);
+  }
+}
+
+// File/message data must be validated, not asserted as DeliveryPlanResult.
+const received: unknown = JSON.parse(JSON.stringify(result));
+const validated = parseDeliveryPlanResult(received);
+console.log(validated.ok);
+```
+
+Exported TypeBox schemas are the source of both runtime validation and static types:
+`DeliveryOptionsSchema`, `DeliveryTargetSchema`, `DeliveryPlanSchema`,
+`DeliveryPlanResultSchema`. `createDeliveryPlan` accepts a trusted compiler graph;
+it is not a deserializer for arbitrary external graph JSON.
+
+## Local Builds
+
+```sh
+supacloud-compiler build-delivery --json
+supacloud-compiler build-delivery --delivery delivery.json --json
+```
+
+Requires Bun and a project `tsconfig.json`. The configured output directory must
+be project-local and must not contain the application source root. Output uses
+the dedicated `<outDir>/delivery` namespace:
+
+```text
+delivery/
+  owner.json
+  delivery.manifest.json
+  objects/<objectId>/
+    generated/application.ts
+    bundle/index.js
+    bundle/package.json
+    bundle/app.manifest.json
+    bundle/target.json
+    bundle/assets/...
+```
+
+`bundle/index.js` exports `createCompiledModules`. Move the whole `bundle` directory,
+not just its entrypoint. The generated TypeScript is inspection output and still
+references application sources; the bundle does not require those source files.
+This is **not** a default HTTP handler or a ready-to-deploy Function. A compatible
+host must supply HTTP composition, trusted identity, database/governance adapters,
+and durable Job execution. Route mappings are local metadata, not applied gateway
+configuration. All results continue to report `deploymentReady: false`.
+
+Optional build settings live in the same validated `delivery` declaration:
+
+```json
+{
+  "version": 1,
+  "build": {
+    "minify": true,
+    "environmentContract": "app-env-v1",
+    "assets": [
+      { "target": "api", "source": "templates/report.html", "path": "report.html" }
+    ]
+  }
+}
+```
+
+Asset `source` is relative to configured source root; `path` is relative to
+`bundle/assets`. Only explicit relative paths are accepted. Missing assets, path
+traversal, duplicate destinations, and symlinks reject the build. Environment
+contracts are references, not secret values. Environment values are not inlined.
+Code doing runtime filesystem reads must use declared assets and the host's
+documented asset-location convention; automatic discovery is not provided.
+Computed `import()` and direct computed `require()` calls are rejected. This is
+not a sandbox for arbitrary JavaScript, eval, or filesystem access.
+
+Each target includes its conservative module dependency closure, while route and
+Job descriptors remain exclusive to their owner. Provider pruning is disabled to
+preserve Job and lifecycle dependencies. Package imports are bundled; only Bun
+and Node builtin imports may remain external. Native/platform-dependent packages
+still need destination-platform validation.
+
+Every invocation reruns compiler checks, TypeScript diagnostics, and bundling for
+**all** targets. The generator's type-check project includes application source
+and target-generated files, preserving configured checks and widening only the
+emit-path `rootDir` to the project directory. This does not replace application
+tests or full release checks. Refresh GraphQL artifacts through normal `compile`
+before building when GraphQL drift is reported.
+
+`inputDigest` includes generated source, captured bundled inputs, compiler and Bun
+identity, configuration/lockfile hashes, target build options, explicit assets,
+and environment-contract reference. Shared dependency changes invalidate dependent
+targets; configuration changes conservatively invalidate more targets. Unchanged
+immutable artifacts are reused without touching their files. This is **artifact
+reuse, not skipped bundler work**.
+
+Success exposes `manifest`, `bundledTargets`, `changedTargets`, `unchangedTargets`,
+`removedTargets`, and `written`. An unchanged build has `written: []`.
+`manifest.objects` records per-file size and SHA-256 plus the object identity.
+Use `parseDeliveryBuildResult` / `parseDeliveryBuildManifest` for received JSON;
+matching hashes are integrity checks, not authorization or authenticity proofs.
+
+An exclusive lock protects the owned output directory. Existing unowned output,
+invalid manifests, and modified immutable objects are rejected without overwrites.
+Only an atomic replacement of `delivery.manifest.json` activates a local build.
+Failures preserve the previous active pointer; inactive objects can remain after
+an interrupted publication. Removed target objects are retained for inspection,
+not automatically garbage-collected. Inspect stale locks after confirming no
+writer is active; the builder never removes them automatically.
+
+## Planning Evidence And Limits
+
+- Every result has `written: []`. A failure has `ok: false` and `plan: null`.
+- Success has `deploymentReady: false`. No planning result authorizes deployment.
+- `topologyDigest` hashes canonical target topology, requirements, and declared
+  readiness. It excludes business source contents, toolchain, lockfile, credentials,
+  migrations, and full runtime contracts. It is **not** an artifact hash, cache key,
+  approval token, or proof that a received plan is authentic.
+- Dependencies are a conservative module closure, not provider-level tree shaking.
+  External token inventory is conservative within that closure.
+- `planDeliveryProject` runs existing compiler analysis/governance/contract gates
+  using supplied compile options. Artifact drift is intentionally ignored so a
+  new project can be planned before generation. Existing artifacts are not rewritten.
+- Compiler analysis is not a complete TypeScript type check. Run the application's
+  type checker, tests, full integration/build gates, and host verification before
+  release. Do not weaken those gates to make a plan succeed.
+- This version does not reconcile old deployment topology, validate all possible
+  router-specific pattern overlaps, or attest queue adapters. Deployment remains
+  a separate, explicitly authorized step.

package/README.md

@@ -1,5 +1,58 @@
 # @supacloud/compiler
 
+## Local Delivery
+
+`supacloud-compiler plan --json` previews workload targets, dependency closures,
+route ownership, and required runtime capabilities without writing or deploying.
+`supacloud-compiler build-delivery --json` creates independent local factory bundles
+and an atomic inspection manifest, reusing unchanged artifacts without deployment.
+See [local delivery](./DELIVERY.md) for validated configuration, AI-facing
+contracts, and the distinction between a topology preview and release evidence.
+
+## Persistent Execution Policy
+
+Set `commandCapabilities.requirePersistentAdapters: true` to require named adapters
+with explicit `database`/`external` boundaries, permission, audit and idempotency.
+Database commands require transactional capability and `transaction: "required"`.
+External adapters cannot satisfy a required database transaction: use durable
+intent and read-only reconciliation instead.
+
+`command-persistence-required` and `command-external-transaction` diagnostics include
+recovery suggestions and participate in JSON output and the existing no-write-on-error
+gate. These checks validate declared policy, not the implementation of a custom
+adapter. See [configuration and migration](../../docs/command-migration.md).
+
+## Source Migrations
+
+The compiler includes deterministic, versioned source migrations for breaking
+framework changes. The command is preview-only unless `--write` is explicit:
+
+```bash
+# Preview files, replacements, and manual conflicts
+bunx supacloud-compiler migrate --root . --json
+
+# Apply only after reviewing the preview
+bunx supacloud-compiler migrate --root . --write
+```
+
+Migrations operate on TypeScript ASTs and skip `node_modules`, `dist`, and
+`generated`. Route options are resolved through local constants,
+`defineRouteContract(...)`, namespace properties, named imports, and the
+project's `tsconfig` path/module settings, so a shared contract declaration is
+changed once even when several controllers import it. If the contract is outside
+the selected root/include set, or any file has an ambiguous transformation, the
+command exits non-zero and writes no file. A successful write uses a
+same-directory temporary file followed by replacement for each changed file; it
+is not a version-control rollback mechanism. Review the diff, then run `compile`,
+`check`, and focused tests with the same compiler version. Use version control to
+revert a migration.
+
+The current route-contract migration is `route-response-to-responses` (`0.11.0`
+to `0.12.0`): it changes `response: Schema` into
+`responses: { 200: Schema }`. It refuses to guess when `responses` is already
+present. See the [route contract migration guide](../../docs/route-contract-migration.md)
+for the complete upgrade and release sequence.
+
 FA-derived direct-command RPC ownership, contract inspection and POST command
 protocol migration are documented in `docs/fa-consumer-governance.md` in the
 repository. `context <module> --json` reports `routeContracts` and standalone
@@ -191,6 +244,7 @@ bunx supacloud-compiler dev
 | 文件发现 | `**/*.module.ts`、`**/*.ts` |
 | strict 类型安全门 | 开启 |
 | typed client | 开启 |
+| OpenAPI 3.1 module | 开启 |
 | permissions manifest | 开启 |
 | module boundary preset | `modular-monolith` |
 | provider tree-shaking | 开启 |
@@ -205,6 +259,11 @@ export default defineSupacloudConfig({
   outDir: "generated",
   strict: true,
   generateClient: true,
+  generateOpenApi: true,
+  openApi: {
+    title: "Orders API",
+    version: "1.0.0",
+  },
   generatePermissions: true,
   moduleBoundaryPreset: "modular-monolith",
   commandCapabilities: {
@@ -221,6 +280,37 @@ export default defineSupacloudConfig({
 `commandCapabilities` 用于声明运行时实际支持的命令治理能力；命令声明了
 `permission`、`audit` 或 `idempotency` 时，若对应能力关闭，编译器会失败。
 
+## OpenAPI 与 Client Generator
+
+编译器从同一份 `ApplicationGraph` 生成 `client.ts` 和 `openapi.ts`，不引入
+反射或第二套路由注册。路由装饰器中显式声明的 TypeBox `body`、`params`、
+`query`、`response` schema 会被静态导入；没有 schema 的字段保持为
+`unknown`，不会从 TypeScript 类型推断出未经验证的运行时协议。
+
+`client.ts` 提供路由方法、路径参数检查、请求类型和 `API_ROUTES`。已声明
+响应 schema 的方法不传 decoder 也会按 HTTP status 自动选择并校验内置 schema；
+传入 `ResponseDecoder<T>` 时，decoder 接收已经通过 schema 校验/规范化的值，
+可安全做日期、金额等业务转换。没有响应 schema 的方法仍返回原始 `unknown`，
+除非调用方显式提供 decoder。
+
+`openapi.ts` 导出 `OPENAPI_DOCUMENT`、`OPENAPI_JSON` 和
+`createOpenApiDocument()`。它包含 OpenAPI 3.1 路径、参数、请求体、响应、
+错误协议、默认 bearer security scheme，以及 `x-supacloud` 中的模块、命令、
+权限和静态 contract 元数据。文档只描述编译器发现的 HTTP routes；文件和
+流式响应仍由宿主运行时负责传输。
+
+```bash
+# 导出可提交或交给文档工具的 JSON
+bunx supacloud-compiler openapi-export generated/openapi.ts openapi.json
+
+# 在 CI 中阻止破坏性 contract 变更
+bunx supacloud-compiler openapi-diff openapi-baseline.json openapi.json --json
+```
+
+`openapi-diff` 会检查路径/操作、参数必填性、请求体、响应状态和 schema 的
+枚举、属性与 required 变化；命令失败时返回非零退出码。基线文件由应用
+负责版本管理，生成的 `openapi.ts` 则由普通 `compile`/`check` 漂移检查维护。
+
 ## API
 
 ```ts
@@ -319,9 +409,88 @@ IDE 和 AI agent 做状态机漂移检查。
 - 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。
 - 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 进来的对象。
+- controller 描述静态给出：`{ path, serviceKey, scope, routes: [{ method, path, handler, body?, params?, query?, headers?, cookie?, response?, responses? }] }`，schema 直接引用 import 进来的对象。
+- `client.ts` 在启用 `generateClient` 时生成：包含 `API_ROUTES`、`API_SCHEMAS`、类型化请求选项和显式响应 decoder 入口。
+- `openapi.ts` 在启用 `generateOpenApi` 时生成：包含 OpenAPI 3.1 文档模块和可序列化 JSON；`check` 会将它纳入生成物漂移检查。
 - 严格生成模式会对 `application.ts`、可选的 `client.ts` 和 `permissions.ts` 做 AST 扫描，禁止生成 `any`。
 
+`<outDir>/client.ts` 提供按 Controller 分组的 Fetch client。路径参数会从
+controller 和 route 的完整路径合并推导；声明了 `response` 或 `responses` 的
+route 会自动按 HTTP status 执行内置 response decoder，并返回 schema 推导的
+类型。显式 decoder 仍可用于覆盖自定义转换；没有响应 schema 的 route 返回
+`unknown`。`headers`、`cookie` 和多状态 `responses` 会同步进入客户端和
+OpenAPI。`buildRouteUrl` 和 `createApiClient` 可直接复用，也支持动态 headers
+和请求拦截器。
+
+### Migration from manual decoders
+
+旧版本要求调用方为每个有响应 schema 的 route 传入 decoder。升级后删除该
+decoder 即可；需要保留自定义转换时，将它作为第二个参数传入。旧的单一
+`response: Schema` 当前作为迁移桥接仍可编译，但新代码必须迁移到
+`responses: { 200: Schema }` 或实际的状态映射；该桥接字段不保证在下一次破坏性
+版本继续保留。Management API 的契约注册表
+由实际 Elysia `app.routes` 投影生成，不应再维护平行的路由清单。
+
+完整的破坏性升级步骤（包括 headers、cookie、客户端 decoder、OpenAPI 和生成物
+刷新）见 [route contract migration guide](../../docs/route-contract-migration.md)。
+
+`<outDir>/openapi.ts` 是无额外运行时依赖的 OpenAPI 3.1 module，导出
+`OPENAPI_DOCUMENT`、`OPENAPI_JSON`、`createOpenApiDocument` 和
+`serializeOpenApiDocument`。它在运行时读取同一组 TypeBox schema，生成 paths、
+parameters、requestBody、responses、securitySchemes 以及 `x-supacloud` 路由元数据，
+因此不会维护第二份 API contract。默认包含 bearer JWT scheme；项目可在
+`openApi` 配置中补充文档信息、servers 和其他显式 security schemes。
+
+`OPENAPI_JSON` 是运行时快照；需要提交独立 `openapi.json` 时，在应用已经能加载
+生成模块的运行时调用 `exportGeneratedOpenApiJson()` 或直接写出该字符串。编译器
+不会为了生成 JSON 执行应用 schema。`readOpenApiJson()` 和
+`diffOpenApiDocuments()` 可用于构建发布门禁：
+
+```ts
+import {
+  exportGeneratedOpenApiJson,
+  diffOpenApiDocuments,
+  readOpenApiJson,
+} from "@supacloud/compiler";
+
+await exportGeneratedOpenApiJson({
+  modulePath: "./generated/openapi.ts",
+  outputPath: "./generated/openapi.json",
+});
+
+const diff = diffOpenApiDocuments(
+  await readOpenApiJson("./contracts/openapi.base.json"),
+  await readOpenApiJson("./generated/openapi.json"),
+);
+if (!diff.ok) throw new Error("OpenAPI breaking change");
+```
+
+也可以直接在 CI 中运行：
+
+```bash
+supacloud-compiler openapi-export ./generated/openapi.ts ./generated/openapi.json
+supacloud-compiler openapi-diff ./contracts/openapi.base.json ./generated/openapi.json --json
+```
+
+`openapi-export` 在运行时加载生成的 `openapi.ts` 并原子地写出独立 JSON；它不会在
+编译阶段执行应用 schema。可用 `--space 0` 到 `--space 10` 控制缩进，重复执行不会
+改写内容不变的文件。当前只承诺 JSON 输出，YAML 转换由发布流水线按需处理。
+
+diff 默认阻止路径/操作/参数/响应删除、请求约束收紧、响应字段收窄或安全要求新增；
+新增可选参数、路径、响应和组件会标记为 non-breaking。它是保守的合同门禁，不替代
+应用端的业务兼容性测试。
+
+```ts
+export default defineSupacloudConfig({
+  generateClient: true,
+  generateOpenApi: true,
+  openApi: { title: "Orders API", version: "1.0.0" },
+});
+```
+
+用 `--no-client` 或 `--no-openapi` 关闭对应产物；`compile` 和 `check` 会同时检查
+已生成的 `client.ts`、`openapi.ts` 是否与当前 ApplicationGraph 漂移。
+
 `<outDir>/app.manifest.json`：`{ version: 1, modules, externalTokens }`，供 CLI graph/explain 使用。
 
 ## 诊断码
@@ -432,8 +601,8 @@ bun run build
 
 ## Route Contract Policy
 
-Enable `requireRouteContracts: true` in `defineSupacloudConfig(...)` or
-`CompileOptions` to report `route-contract-required` errors in both compile and
+Project configuration defaults to `requireRouteContracts: true`. Low-level
+`CompileOptions` callers can set it explicitly to report `route-contract-required` errors in both compile and
 check (including JSON diagnostics). Changing this option invalidates incremental
 results. Combine it with `writeOnError: false` when programmatic compilation must
 not emit files on errors.
@@ -443,10 +612,20 @@ query, and response declarations. Required inputs are detected from handler
 bindings and controller/route path parameters. Responses always require an
 explicit declaration, including intentional void contracts.
 
-This checks declaration coverage only, not schema quality, handler/schema type
+This checks declaration coverage and rejects known opaque schemas, not full schema quality, handler/schema type
 equivalence, or database authorization. It deliberately does not auto-fix missing
 schemas with `unknown` placeholders. Consumers must define the actual contracts
-and test decoding separately. The policy defaults to false for existing projects.
+and test decoding separately. Native output must be classified; delegated
+validation and native transports require a `contract.evidence` test reference.
+The report still sets `verified: false`, since a reference does not prove execution.
+
+The source type gate now includes TypeScript syntactic/semantic diagnostics and
+rejects production `@ts-ignore`, `@ts-nocheck` and `@ts-expect-error`. A source-directory root resolves
+the enclosing tsconfig. When this gate is enabled, incremental compilation
+rechecks types instead of returning an unchecked cached result.
+
+Generated route calls require all path parameters and a decoder for typed
+responses. See [type safety and migration](../../docs/type-safety.md).
 
 ## License
 

package/dist/benchmark.d.ts

@@ -0,0 +1,10 @@
+export interface CompilerBenchmarkResult {
+    fixtureFiles: number;
+    coldCompileMs: number;
+    incrementalCompileMs: number;
+    dependencyInvalidationMs: number;
+    generatedBytes: number;
+    reusedModules: string[];
+    reanalyzedModules: string[];
+}
+export declare function runCompilerBenchmark(): Promise<CompilerBenchmarkResult>;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};