@yss123/cage-cli 0.1.0 → 0.2.0

package/managed/errors/CAGE-REACT-001.md

@@ -1,32 +0,0 @@
-# CAGE-REACT-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/flow.ts:46](../../packages/kernel/src/primitives/flow.ts)
-
-```ts
-  if (def.target && def.target !== def.command.agg) {
-    throw declError('CAGE-REACT-001', `反应的 target 与 command 所属聚合不一致`);
-  }
-  return Object.freeze({
-    [REACTION]: true as const,
-    event: ev,
-```
-
-## 怎么修
-
-反应的目标聚合必须与 command 一致，目标命令需从统一入口导出。
-
-## 正例
-
-```text
-reaction(Approved, { command: acquireLock, map: e => ({ id: e.orderId }) })
-```
-
-## 反例
-
-```text
-reaction(Approved, { target: Order, command: acquireLock, map })
-```

package/managed/errors/CAGE-REACT-002.md

@@ -1,32 +0,0 @@
-# CAGE-REACT-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/kernel.ts:193](../../packages/kernel/src/kernel.ts)
-
-```ts
-    const agg = cmd.agg;
-    if (depth > this.maxDepth) throw new Error(`[CAGE-REACT-002] 同事务反应嵌套超过 ${this.maxDepth} 层`);
-
-    // 第 1 关：认证
-    if (!ctx.actor || (ctx.actor.kind === 'anonymous' && !cmd.public)) throw cageError('UNAUTHENTICATED');
-
-```
-
-## 怎么修
-
-反应的目标聚合必须与 command 一致，目标命令需从统一入口导出。
-
-## 正例
-
-```text
-reaction(Approved, { command: acquireLock, map: e => ({ id: e.orderId }) })
-```
-
-## 反例
-
-```text
-reaction(Approved, { target: Order, command: acquireLock, map })
-```

package/managed/errors/CAGE-READS-001.md

@@ -1,32 +0,0 @@
-# CAGE-READS-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/pipeline/load.ts:83](../../packages/kernel/src/pipeline/load.ts)
-
-```ts
-      if (typeof prop === 'string' && !(prop in target) && prop !== 'then' && prop !== 'toJSON') {
-        throw new Error(`[CAGE-READS-001] handler 使用了未声明的读依赖 ${prop}（详见 docs/errors/CAGE-READS-001.md）`);
-      }
-      return (target as any)[prop];
-    },
-  });
-```
-
-## 怎么修
-
-在 reads 中声明所有读依赖，并确认目标聚合也从入口导出。
-
-## 正例
-
-```text
-reads: { stock: Inventory }
-```
-
-## 反例
-
-```text
-reads: {} // handler 却读取 deps.stock
-```

package/managed/errors/CAGE-REG-001.md

@@ -1,32 +0,0 @@
-# CAGE-REG-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/kernel.ts:109](../../packages/kernel/src/kernel.ts)
-
-```ts
-    if (!rc) {
-      throw new Error(`[CAGE-REG-001] 找不到命令 ${typeof ref === 'string' ? ref : ref.agg.name + '.?'}，它是否从 domain 导出了？`);
-    }
-    return rc;
-  }
-
-```
-
-## 怎么修
-
-检查统一入口中的聚合/命令引用及名称是否重复，所有依赖都必须在注册表中。
-
-## 正例
-
-```text
-export * from './purchase-order.js';
-```
-
-## 反例
-
-```text
-// 命令引用了没有从入口导出的聚合
-```

package/managed/errors/CAGE-REG-002.md

@@ -1,32 +0,0 @@
-# CAGE-REG-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/registry.ts:86](../../packages/kernel/src/registry.ts)
-
-```ts
-          if (aggregates.some((a) => a.name === (v as AnyAggregate).name)) {
-            throw declError('CAGE-REG-002', `聚合名重复：${(v as AnyAggregate).name}`);
-          }
-          aggregates.push(v as AnyAggregate);
-          break;
-        case 'COMMAND': {
-```
-
-## 怎么修
-
-检查统一入口中的聚合/命令引用及名称是否重复，所有依赖都必须在注册表中。
-
-## 正例
-
-```text
-export * from './purchase-order.js';
-```
-
-## 反例
-
-```text
-// 命令引用了没有从入口导出的聚合
-```

package/managed/errors/CAGE-REG-003.md

@@ -1,32 +0,0 @@
-# CAGE-REG-003
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/registry.ts:133](../../packages/kernel/src/registry.ts)
-
-```ts
-    if (!aggSet.has(c.cmd.agg)) throw declError('CAGE-REG-001', `命令 ${c.capability} 所属的聚合 ${c.cmd.agg.name} 没有从 domain 导出`);
-    if (caps.has(c.capability)) throw declError('CAGE-REG-003', `能力点重复：${c.capability}，可用 command({ name }) 区分`);
-    caps.add(c.capability);
-    for (const [alias, a] of Object.entries(c.cmd.reads)) {
-      if (!aggSet.has(a)) throw declError('CAGE-REG-001', `命令 ${c.capability} 的 reads.${alias} 引用的聚合没有导出`);
-    }
-```
-
-## 怎么修
-
-检查统一入口中的聚合/命令引用及名称是否重复，所有依赖都必须在注册表中。
-
-## 正例
-
-```text
-export * from './purchase-order.js';
-```
-
-## 反例
-
-```text
-// 命令引用了没有从入口导出的聚合
-```

package/managed/errors/CAGE-ROUTE-001.md

@@ -1,32 +0,0 @@
-# CAGE-ROUTE-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/lint/src/rules/no-manual-routes.ts:11](../../packages/lint/src/rules/no-manual-routes.ts)
-
-```ts
-    docs: { description: '禁止在业务项目里手写 HTTP 路由' },
-    messages: { route: '[CAGE-ROUTE-001] 不要手写路由 {{call}}：在 domain 里声明命令或查询，路由由框架生成' },
-    schema: [],
-  },
-  create(context) {
-    return {
-```
-
-## 怎么修
-
-在 domain 声明 command/query，让框架生成 HTTP 路由。
-
-## 正例
-
-```text
-export const submit = command(Order, definition);
-```
-
-## 反例
-
-```text
-app.post('/api/order/submit', handler);
-```

package/managed/errors/CAGE-SCOPE-001.md

@@ -1,32 +0,0 @@
-# CAGE-SCOPE-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/scope/index.ts:66](../../packages/kernel/src/scope/index.ts)
-
-```ts
-    default:
-      throw new Error('[CAGE-SCOPE-001] 未知的范围组合子');
-  }
-}
-
-/** 多个授权取并集：用 OR 连接；外层始终加租户条件。 */
-```
-
-## 怎么修
-
-选择内置范围组合子，引用聚合中真实存在的部门/创建人字段。
-
-## 正例
-
-```text
-scope: scope.deptSubtree('deptId')
-```
-
-## 反例
-
-```text
-scope: scope.deptSubtree('missingField')
-```

package/managed/errors/CAGE-SCOPE-002.md

@@ -1,32 +0,0 @@
-# CAGE-SCOPE-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/aggregate.ts:96](../../packages/kernel/src/primitives/aggregate.ts)
-
-```ts
-  for (const f of [sc.deptField, ownerField]) {
-    if (f && f !== 'id' && !(f in fields)) throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
-  }
-  const scope: ScopeSpec = Object.freeze({ ...sc, ownerField });
-
-  return Object.freeze({
-```
-
-## 怎么修
-
-选择内置范围组合子，引用聚合中真实存在的部门/创建人字段。
-
-## 正例
-
-```text
-scope: scope.deptSubtree('deptId')
-```
-
-## 反例
-
-```text
-scope: scope.deptSubtree('missingField')
-```

package/managed/errors/CAGE-SECRET-001.md

@@ -1,32 +0,0 @@
-# CAGE-SECRET-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/connectors/src/runtime.ts:22](../../packages/connectors/src/runtime.ts)
-
-```ts
-    const v = process.env[name];
-    if (!v) throw new Error(`[CAGE-SECRET-001] 缺少密钥 ${name}（由密钥管理服务或环境变量注入）`);
-    return v;
-  },
-};
-
-```
-
-## 怎么修
-
-配置中只写密钥名；密钥值通过运行环境注入，移除源码中的字面量。
-
-## 正例
-
-```text
-secret: 'ERP_API_TOKEN'
-```
-
-## 反例
-
-```text
-secret: 'a-real-token-in-source'
-```

package/managed/errors/CAGE-SECRET-002.md

@@ -1,32 +0,0 @@
-# CAGE-SECRET-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/lint/src/rules/no-secret-literal.ts:19](../../packages/lint/src/rules/no-secret-literal.ts)
-
-```ts
-    docs: { description: '禁止密钥字面量' },
-    messages: { secret: '[CAGE-SECRET-002] 疑似{{what}}写在了代码里：密钥只写名字，值由密钥管理服务注入' },
-    schema: [],
-  },
-  create(context) {
-    const check = (node: any, value: string, name?: string) => {
-```
-
-## 怎么修
-
-配置中只写密钥名；密钥值通过运行环境注入，移除源码中的字面量。
-
-## 正例
-
-```text
-secret: 'ERP_API_TOKEN'
-```
-
-## 反例
-
-```text
-secret: 'a-real-token-in-source'
-```

package/managed/errors/CAGE-SENS-001.md

@@ -1,32 +0,0 @@
-# CAGE-SENS-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/rules.ts:114](../../packages/cli/src/rules.ts)
-
-```ts
-
-/** CAGE-SENS-001：敏感字段不得原样进入事件载荷 */
-export function checkSensitiveEvents(g: Ontology): Finding[] {
-  const { get, out } = index(g);
-  const findings: Finding[] = [];
-  for (const c of g.nodes.filter((n) => n.kind === 'command')) {
-```
-
-## 怎么修
-
-从事件移除敏感字段，或保留与聚合一致的 sensitive 标注，让运行时脱敏。
-
-## 正例
-
-```text
-event('OrderChanged', { phone: text().sensitive('phone') })
-```
-
-## 反例
-
-```text
-event('OrderChanged', { phone: text() }) // 来源字段是敏感电话
-```

package/managed/errors/CAGE-SQL-001.md

@@ -1,32 +0,0 @@
-# CAGE-SQL-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/lint/src/rules/no-sql-concat.ts:19](../../packages/lint/src/rules/no-sql-concat.ts)
-
-```ts
-    messages: {
-      concat: '[CAGE-SQL-001] 不要拼接 SQL 字符串，改用 sql 标签模板或查询构建器（值会自动参数化）',
-      raw: '[CAGE-SQL-002] sql.raw() 只能接收字面量',
-    },
-    schema: [],
-  },
-```
-
-## 怎么修
-
-使用参数化 SQL 或查询构建器；sql.raw 只接收固定 SQL 片段。
-
-## 正例
-
-```text
-sql`select * from safe.purchase_order where id = ${id}`
-```
-
-## 反例
-
-```text
-'select * from safe.purchase_order where id = ' + input
-```

package/managed/errors/CAGE-SQL-002.md

@@ -1,32 +0,0 @@
-# CAGE-SQL-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/lint/src/rules/no-sql-concat.ts:20](../../packages/lint/src/rules/no-sql-concat.ts)
-
-```ts
-      concat: '[CAGE-SQL-001] 不要拼接 SQL 字符串，改用 sql 标签模板或查询构建器（值会自动参数化）',
-      raw: '[CAGE-SQL-002] sql.raw() 只能接收字面量',
-    },
-    schema: [],
-  },
-  create(context) {
-```
-
-## 怎么修
-
-使用参数化 SQL 或查询构建器；sql.raw 只接收固定 SQL 片段。
-
-## 正例
-
-```text
-sql`select * from safe.purchase_order where id = ${id}`
-```
-
-## 反例
-
-```text
-'select * from safe.purchase_order where id = ' + input
-```

package/managed/errors/CAGE-STATE-001.md

@@ -1,32 +0,0 @@
-# CAGE-STATE-001
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/command.ts:130](../../packages/kernel/src/primitives/command.ts)
-
-```ts
-  if (from !== 'new' && !hasStates(agg, from)) {
-    throw declError('CAGE-STATE-001', `${agg.name} 的命令 from 里有未声明的状态：${[from].flat().join(', ')}`);
-  }
-  // 回执等异步元数据可能在单据取消/完成后到达。允许显式保留当前状态，
-  // 避免业务 handler 通过篡改 status 绕过状态机；新建命令必须有实际目标状态。
-  if (from === 'new' && def.to === null) {
-```
-
-## 怎么修
-
-让 from/to 引用已声明的状态，初始状态可达，非终态有出边，结束状态列入 terminal。
-
-## 正例
-
-```text
-states('draft', 'done', { terminal: ['done'] });
-```
-
-## 反例
-
-```text
-command(Order, { from: 'missing', to: 'done', handler: o => o });
-```

package/managed/errors/CAGE-STATE-002.md

@@ -1,32 +0,0 @@
-# CAGE-STATE-002
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/states.ts:22](../../packages/kernel/src/primitives/states.ts)
-
-```ts
-  const values = all.filter((a): a is S => typeof a === 'string');
-  if (values.length === 0) throw declError('CAGE-STATE-002', 'states() 至少需要一个状态');
-  for (const v of values) {
-    if (!/^[a-z][a-z0-9_]*$/.test(v)) throw declError('CAGE-STATE-003', `状态名 ${v} 必须是小写下划线`);
-  }
-  if (new Set(values).size !== values.length) throw declError('CAGE-STATE-004', '状态名重复');
-```
-
-## 怎么修
-
-让 from/to 引用已声明的状态，初始状态可达，非终态有出边，结束状态列入 terminal。
-
-## 正例
-
-```text
-states('draft', 'done', { terminal: ['done'] });
-```
-
-## 反例
-
-```text
-command(Order, { from: 'missing', to: 'done', handler: o => o });
-```

package/managed/errors/CAGE-STATE-003.md

@@ -1,32 +0,0 @@
-# CAGE-STATE-003
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/states.ts:24](../../packages/kernel/src/primitives/states.ts)
-
-```ts
-  for (const v of values) {
-    if (!/^[a-z][a-z0-9_]*$/.test(v)) throw declError('CAGE-STATE-003', `状态名 ${v} 必须是小写下划线`);
-  }
-  if (new Set(values).size !== values.length) throw declError('CAGE-STATE-004', '状态名重复');
-  const terminal = opts.terminal ?? [];
-  for (const t of [...terminal, ...(opts.initial ? [opts.initial] : [])]) {
-```
-
-## 怎么修
-
-让 from/to 引用已声明的状态，初始状态可达，非终态有出边，结束状态列入 terminal。
-
-## 正例
-
-```text
-states('draft', 'done', { terminal: ['done'] });
-```
-
-## 反例
-
-```text
-command(Order, { from: 'missing', to: 'done', handler: o => o });
-```

package/managed/errors/CAGE-STATE-004.md

@@ -1,32 +0,0 @@
-# CAGE-STATE-004
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/states.ts:26](../../packages/kernel/src/primitives/states.ts)
-
-```ts
-  }
-  if (new Set(values).size !== values.length) throw declError('CAGE-STATE-004', '状态名重复');
-  const terminal = opts.terminal ?? [];
-  for (const t of [...terminal, ...(opts.initial ? [opts.initial] : [])]) {
-    if (!values.includes(t)) throw declError('CAGE-STATE-001', `状态 ${t} 未在 states 中声明`);
-  }
-```
-
-## 怎么修
-
-让 from/to 引用已声明的状态，初始状态可达，非终态有出边，结束状态列入 terminal。
-
-## 正例
-
-```text
-states('draft', 'done', { terminal: ['done'] });
-```
-
-## 反例
-
-```text
-command(Order, { from: 'missing', to: 'done', handler: o => o });
-```

package/managed/errors/CAGE-STATE-005.md

@@ -1,32 +0,0 @@
-# CAGE-STATE-005
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/kernel/src/primitives/aggregate.ts:78](../../packages/kernel/src/primitives/aggregate.ts)
-
-```ts
-    if (isStates(v)) {
-      if (k !== 'status') throw declError('CAGE-STATE-005', `状态集只能放在 status 字段上（发现 ${name}.${k}）`);
-      if (st) throw declError('CAGE-STATE-005', `${name} 同时在 states 和 fields.status 里声明了状态`);
-      st = v;
-      continue;
-    }
-```
-
-## 怎么修
-
-让 from/to 引用已声明的状态，初始状态可达，非终态有出边，结束状态列入 terminal。
-
-## 正例
-
-```text
-states('draft', 'done', { terminal: ['done'] });
-```
-
-## 反例
-
-```text
-command(Order, { from: 'missing', to: 'done', handler: o => o });
-```

package/managed/errors/CAGE-STATE-010.md

@@ -1,32 +0,0 @@
-# CAGE-STATE-010
-
-## 什么时候出现
-
-命中以下实现中的检查时触发。终端会附具体声明位置、原因和修复方法。
-
-来源：[packages/cli/src/rules.ts:67](../../packages/cli/src/rules.ts)
-
-```ts
-
-/** CAGE-STATE-010：每个状态都能从初始状态到达；CAGE-STATE-011：非终态必须有出边 */
-export function checkStates(g: Ontology): Finding[] {
-  const { get } = index(g);
-  const findings: Finding[] = [];
-  for (const a of g.nodes.filter((n) => n.kind === 'aggregate')) {
-```
-
-## 怎么修
-
-让 from/to 引用已声明的状态，初始状态可达，非终态有出边，结束状态列入 terminal。
-
-## 正例
-
-```text
-states('draft', 'done', { terminal: ['done'] });
-```
-
-## 反例
-
-```text
-command(Order, { from: 'missing', to: 'done', handler: o => o });
-```