@supacloud/compiler 0.11.0 → 0.13.0

package/README.md

@@ -1,9 +1,95 @@
 # @supacloud/compiler
 
+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
+command execution plans; these are declarations and obligations, not runtime proof.
+
 SupaCloud 应用静态编译器：读取 `@supacloud/app` 装饰器元数据的原生 TypeScript AST，构建 ApplicationGraph，做静态校验，并生成**无反射、无容器**的工厂代码与 manifest。
 
 本包不依赖 `@supacloud/app`：AST 只按装饰器名匹配（`Module`/`Injectable`/`Inject`/`Command`/`Query`/`Controller`/`Get`/`Post`/`Put`/`Patch`/`Delete`/`defineModule`/`InjectionToken`），不校验 import 来源。
 
+## Recommended GraphQL Query Contracts
+
+**Database First is the only server-schema model.** Drizzle and SQL declarations
+are migrated to PostgreSQL; `pg_graphql` reflects the actual database, and
+`graphql-schema` exports the intended role's snapshot. Author queries/fragments,
+not GraphQL resolver classes or a separate server SDL. `graphql.schema` accepts
+only local `.graphql`, `.gql` or `.json` snapshots; executable sources, URLs and
+schema-authoring options such as `autoSchemaFile`, `typePaths`, `resolvers` or
+`mode` are rejected. Snapshot formats and TypedDocumentNode output are not
+alternative authoring modes.
+
+Do not edit exported snapshots. Change database declarations, apply migrations,
+export again and compile. Offline compilation cannot attest a snapshot's origin;
+`graphql-schema --check` against the intended database detects local/remote drift.
+The starter's synthetic SDL is solely an offline test fixture, not a deployed
+schema. Replace it with a database export before integration.
+
+New `supacloud app init` projects preconfigure GraphQL query contracts and include
+an offline example. Existing REST, Command-only and background-task projects
+remain unchanged: general App/CLI configuration and `compileProject(options)`
+only enable this pipeline when `graphql` is explicitly configured. Enabled
+contracts always reject invalid queries and missing schemas, even with
+`strict: false` or `--no-strict`. Choosing `graphql: false` (or `--no-graphql` for
+one compiler run) disables adoption, not just validation of individual queries.
+The platform extension is still opt-in; compilation changes no database grants,
+extensions or production introspection settings.
+
+```ts
+export default defineSupacloudConfig({
+  root: "src",
+  graphql: { schema: "graphql/schema.graphql" },
+});
+```
+
+The schema path is configuration-relative, query globs are source-root-relative.
+Normal `compile`, `check`, `dev` and `context` handle the local snapshot and
+queries offline. Invalid fields/variables, unnamed operations, mutations and
+subscriptions produce structured diagnostics; failures preserve working output.
+GraphQL.js and GraphQL Code Generator own parsing, validation and operation types.
+Unknown custom scalars stay `unknown` unless explicitly mapped via `graphql.scalars`.
+
+```sh
+supacloud-compiler graphql-schema --url https://your-project.example \
+  --key-env SUPACLOUD_PUBLISHABLE_KEY --token-env APP_USER_ACCESS_TOKEN
+supacloud-compiler compile
+supacloud-compiler check --json
+```
+
+Export is explicit and requires introspection already enabled in the selected
+development project. Flags name environment variables, not secrets. Use the
+intended caller role, never a privileged service-role schema for browser queries.
+After migrations, use the same export command with `--check --json` to detect
+remote schema drift without overwriting the local snapshot (exit 1 on drift).
+Refresh intentionally, then run compile/check and the application's typecheck
+and role/RLS tests. This remote gate requires development introspection; offline
+compilation does not require production introspection.
+
+Set `graphql.typedDocuments: true` to additionally generate
+`graphql.documents.ts` using the standard TypedDocumentNode Codegen plugin.
+Consumers of that optional file must install `@graphql-typed-document-node/core`;
+it provides `ResultOf` and `VariablesOf` for operation-level inference. The default
+fetch client still needs no GraphQL runtime dependency.
+
+```ts
+import { createGraphqlClient } from "./generated/graphql";
+const queries = createGraphqlClient({
+  url: projectUrl,
+  publishableKey,
+  getAccessToken: readCurrentUserToken,
+});
+const result = await queries.ReviewList({ first: 20 });
+```
+
+Method names and types come from named operations. The generated client is
+dependency-free and refreshes identity per request; `getSdk(requester)` integrates
+an existing transport. It rejects HTTP errors, GraphQL errors and malformed
+response envelopes, but does not runtime-decode selected field values.
+`graphql.manifest.json` records query locations and the schema hash; context packs
+include colocated queries. RLS/grants, real database acceptance and query resource
+limits remain deployment responsibilities. Business writes stay in Commands.
+
 ## 安装
 
 ```bash
@@ -185,6 +271,7 @@ IDE 和 AI agent 做状态机漂移检查。
 | `unsupported-provider-helper` | warn（strict 时 error） | functional provider 的动态参数无法安全展开为静态 factory |
 | `dynamic-aspect-reference` | error | aspects 不是显式数组字面量，或包含 spread/表达式/字符串 pointcut |
 | `invalid-aspect-reference` | error | aspect 不是可静态解析的函数声明、箭头函数或函数表达式 |
+| `invalid-command-mode` | error | transaction/idempotency 必须显式为 `"required"` 或 `"none"`，不允许拼写错误或动态值悄悄关闭治理（SC4012） |
 | `missing-deps` | warn（strict 时 error） | 构造/工厂依赖无法静态解析 |
 | `generated-any` | warn（strict 时 error） | 生成的 TypeScript 产物包含 `any` |
 | `source-any` | warn（strict 时 error） | 未被排除的生产源码包含显式 `any` |
@@ -211,7 +298,7 @@ supacloud-compiler check --root ./app --out ./app/generated --strict
 supacloud-compiler dev --root . --out ./generated
 ```
 
-开发模式默认对源码变化做 100ms 防抖，并只监听 TypeScript 文件。编译器会复用进程内的源码快照：相同输入直接命中缓存；只改动普通实现文件时复用既有依赖图和生成物；只有 SupaCloud 元数据、模块声明或依赖相关文件变化时才重建图。编译失败时不会覆盖最后一次成功的 `application.ts` 和 `app.manifest.json`；修复错误后会自动生成新产物。`--debounce <ms>` 可调整防抖时间。
+开发模式默认对源码变化做 100ms 防抖，监听 TypeScript 文件；启用 GraphQL 后，还监听查询文件和配置的 Schema 快照。编译器会复用进程内的源码快照：相同输入直接命中缓存；只改动普通实现文件时复用既有依赖图和生成物；只有 SupaCloud 元数据、模块声明或依赖相关文件变化时才重建图。编译失败时不会覆盖最后一次成功的 `application.ts` 和 `app.manifest.json`；修复错误后会自动生成新产物。`--debounce <ms>` 可调整防抖时间。
 
 ## 图谱与诊断
 
@@ -238,6 +325,20 @@ supacloud-compiler context case --root ./app --json
 `supacloud-compiler fix ./fix.json --dry-run` 调用；CLI 默认预览，需显式
 使用 `--write` 才写盘。写盘前会重新解析 AST，
 前置条件不满足时拒绝修改，并通过临时文件原子替换。
+CLI 修复的 `targetFile` 相对于配置的源码根目录解析，也可以用 `--root` 显式指定；
+JSON 修复文件本身仍相对于当前工作目录读取。
+
+上下游分别沿单一方向遍历，不会经过共享基础模块再扩散到无关兄弟业务。
+上下文包还包含准确的切面源文件、校验诊断和 `executionPlans`；`explain <module>`
+也展示静态执行计划。计划描述标准命令治理；自定义 executor 的内部实现和短路行为
+仍需运行时追踪验证。成功审计在 handler 返回后执行，而非 handler 之前。
+
+例如 `@Command({ transaction: "requried" })` 会报告 `invalid-command-mode`，
+并输出 `set_command_mode` 修复建议。必须显式给 fix 的 `value` 选择 `"required"`
+或 `"none"` 才能预览或写入；不会推断较弱权限。若诊断后的源表达式变化，修复拒绝写盘。
+
+`compileProject()` 现在默认在存在 error 时保留已有产物。仅诊断/迁移工具可以显式
+设置 `writeOnError: true` 导出错误版本；这些产物不应被部署或视为可执行成功产物。
 
 ## 编译基准