tha-cli 0.0.0-stage → 0.1.1

package/tha/verify/openapi.mjs

@@ -0,0 +1,345 @@
+// ============ OpenAPI 契约比对：config.fields 与后端真实字段对不对得上 ============
+// 真源是项目里的 OpenAPI 文件，不是 config。config 只是「这一页要用哪些字段」的声明。
+// 只比字段名 / 类型 / 必填，不比描述、示例与枚举值集合（那些不构成运行时依赖）。
+//
+// 兼容的是「schema 方言」，不是「后端语言」：
+//   - OAS 3.0：nullable、allOf、$ref
+//   - OAS 3.1：type 是数组、anyOf / oneOf、字段级 $ref（FastAPI / Pydantic v2、NestJS）
+//   - 包装层：{ code, data } / { result } / { items } 往下钻一层
+//   - Swagger 2.0：不解析，明确报错让人先转换（2.0 结构完全不同，养第二套解析不划算）
+
+import path from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import { exists, read } from '../utils/files.mjs'
+
+const ACTION_LABEL = { create: '新增', update: '修改' }
+import { relPath } from '../config/paths.mjs'
+
+// config 类型 → OpenAPI 允许的类型（date/datetime 在 OpenAPI 里都是 string + format）
+const TYPE_COMPATIBLE = {
+  string: ['string'],
+  text: ['string'],
+  number: ['number', 'integer'],
+  boolean: ['boolean'],
+  date: ['string'],
+  datetime: ['string'],
+  enum: ['string', 'number', 'integer']
+}
+
+// 常见的统一响应包装键。只在「业务字段一个都没命中」时才尝试解包，
+// 避免把真有 data 字段的业务对象拆错。
+const WRAPPER_KEYS = ['data', 'result', 'items', 'records', 'list', 'payload']
+
+/**
+ * OpenAPI 比对入口
+ * @param modules 模块描述列表
+ * @param root    项目根目录
+ * @param dirs    目录映射
+ * @returns [{ file, level, message }] —— level: 'error' | 'warn'
+ */
+export function checkOpenApiContracts(modules, root, dirs) {
+  const problems = []
+
+  for (const module of modules) {
+    if (module.source !== 'config') continue
+
+    const contractRel = module.domain.api?.contract
+    if (!contractRel) continue
+
+    const configRel = relPath(dirs, 'domains', module.name, 'config.ts')
+    const report = (level, message) => problems.push({ file: configRel, level, message: `${contractRel}：${message}` })
+
+    const contractFile = path.join(root, contractRel)
+    if (!exists(contractFile)) {
+      report('error', 'API spec file not found (接口文档文件找不到)')
+      continue
+    }
+
+    let spec
+    const isYaml = /\.(ya?ml)$/i.test(contractRel)
+    const format = isYaml ? 'YAML' : 'JSON'
+    try {
+      const text = read(contractFile)
+      spec = isYaml ? parseYaml(text) : JSON.parse(text)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      report('error', `API spec is not valid ${format} (接口文档不是合法 ${format}): ${message}`)
+      continue
+    }
+
+    if (!spec || typeof spec !== 'object') {
+      report('error', 'API spec is empty (接口文档是空的)')
+      continue
+    }
+
+    if (spec.swagger === '2.0') {
+      report(
+        'error',
+        'swagger 2.0 detected, convert it first (文档是旧格式 Swagger 2.0，先转成新版再比): ' +
+          'npx swagger2openapi ' + contractRel + ' -o ' + contractRel
+      )
+      continue
+    }
+
+    const base = module.domain.api.base
+    const schema = rowSchema(spec, base)
+    if (!schema) {
+      const available = Object.keys(spec.paths ?? {}).slice(0, 6).join(', ')
+      report(
+        'warn',
+        `no response schema for ${base}, skipped (文档里找不到这个接口的返回结构，这项跳过)` +
+          (available ? ` (available paths: ${available})` : '')
+      )
+      continue
+    }
+
+    compareFields(spec, module.domain, unwrapSchema(spec, schema, module.domain.fields), report)
+
+    // 请求体：生成器按 form 字段构造 create / update 的 payload，也要和契约对得上。
+    // 没有 requestBody 声明时只报一条 warn，不逐字段误报。
+    const missingBodies = []
+    for (const action of ['create', 'update']) {
+      if (module.domain.crud?.[action] === false) continue
+      const body = requestSchema(spec, base, action)
+      if (!body) {
+        missingBodies.push(action)
+        continue
+      }
+      compareRequestFields(spec, module.domain, body, action, report)
+    }
+    if (missingBodies.length > 0) {
+      report(
+        'warn',
+        `no request body for ${missingBodies.map((a) => ACTION_LABEL[a]).join(', ')}, skipped (文档里没写提交字段，这块跳过)`
+      )
+    }
+  }
+
+  return problems
+}
+
+/**
+ * 取某个接口「一行数据」的 schema：先找 $ref，再拆数组
+ */
+function rowSchema(spec, base) {
+  const item = findPath(spec, base)
+  if (!item) return null
+
+  const schema =
+    item.get?.responses?.['200']?.content?.['application/json']?.schema ??
+    item.post?.responses?.['201']?.content?.['application/json']?.schema
+
+  return resolve(spec, schema, 0)
+}
+
+/**
+ * 找路径：容忍尾斜杠差异。FastAPI 里挂 prefix 的列表接口常是 `/doc/`，
+ * 而 config 的 api.base 是 `/doc`（拼请求 URL 用），两边不该为此互相迁就。
+ */
+function findPath(spec, base) {
+  const paths = spec.paths ?? {}
+  if (paths[base]) return paths[base]
+  const alt = base.endsWith('/') ? base.slice(0, -1) : `${base}/`
+  return paths[alt] ?? null
+}
+
+/**
+ * 取请求体 schema：create 看 POST，update 看 PUT / PATCH（POST 兜底）
+ */
+function requestSchema(spec, base, action) {
+  const item = findPath(spec, base)
+  if (!item) return null
+
+  // create 只认 POST，update 只认 PUT / PATCH —— POST 归 create，不能拿来给 update 兜底
+  const methods = action === 'create' ? ['post'] : ['put', 'patch']
+
+  for (const method of methods) {
+    const schema = item[method]?.requestBody?.content?.['application/json']?.schema
+    if (schema) return resolve(spec, schema, 0)
+  }
+
+  return null
+}
+
+function resolve(spec, node, depth) {
+  if (!node || depth > 10) return null
+
+  if (node.$ref) {
+    const name = node.$ref.split('/').pop()
+    return resolve(spec, spec.components?.schemas?.[name], depth + 1)
+  }
+
+  // 列表接口返回数组，比对的是数组里那一行
+  if (node.type === 'array' || node.items) return resolve(spec, node.items, depth + 1)
+
+  // allOf 常见于「基类 + 补充字段」，合并成扁平对象
+  if (node.allOf) {
+    const merged = { type: 'object', properties: {}, required: [] }
+    for (const part of node.allOf) {
+      const resolved = resolve(spec, part, depth + 1)
+      Object.assign(merged.properties, resolved?.properties ?? {})
+      merged.required.push(...(resolved?.required ?? []))
+    }
+    return merged
+  }
+
+  return node
+}
+
+/**
+ * 包装层解包：{ code, data: [...] } → data 那一层。
+ * 只在这些条件同时成立时才解包：业务字段一个都没命中、包装键存在、解开后能命中。
+ */
+function unwrapSchema(spec, schema, fields) {
+  const props = schema?.properties ?? {}
+  const keys = Object.keys(props)
+  if (keys.length === 0) return schema
+  if (keys.some((key) => fields[key])) return schema
+
+  for (const wrapper of WRAPPER_KEYS) {
+    const inner = props[wrapper]
+    if (!inner) continue
+    const resolved = resolve(spec, inner, 0)
+    const innerProps = Object.keys(resolved?.properties ?? {})
+    if (innerProps.some((key) => fields[key] || key === 'id')) return resolved
+  }
+
+  return schema
+}
+
+/**
+ * 把各种方言抹平成 { types: string[], format, nullable }
+ * types 是「后端可能返回的全部非 null 类型」；为空表示不可判定，调用方跳过类型检查。
+ */
+function normalize(spec, node, depth) {
+  const empty = { types: [], format: null, nullable: false }
+  if (!node || depth > 10) return empty
+
+  if (node.$ref) {
+    const name = node.$ref.split('/').pop()
+    return normalize(spec, spec.components?.schemas?.[name], depth + 1)
+  }
+
+  // OAS 3.1：type 是数组，null 表示可空
+  if (Array.isArray(node.type)) {
+    const types = node.type.filter((t) => t !== null)
+    return { types, format: node.format ?? null, nullable: node.type.includes('null') }
+  }
+
+  // OAS 3.1 / 3.0：anyOf / oneOf 表达可空与联合
+  const branches = node.anyOf ?? node.oneOf
+  if (!node.type && Array.isArray(branches)) {
+    const types = []
+    let nullable = false
+    let format = node.format ?? null
+    for (const branch of branches) {
+      if (branch?.type === 'null') {
+        nullable = true
+        continue
+      }
+      const resolved = normalize(spec, branch, depth + 1)
+      nullable = nullable || resolved.nullable
+      for (const t of resolved.types) if (!types.includes(t)) types.push(t)
+      if (!format && resolved.format) format = resolved.format
+    }
+    return { types, format, nullable }
+  }
+
+  // 内联枚举没有 type，按字符串算（后端枚举值通常是字符串）
+  if (!node.type && Array.isArray(node.enum)) return { types: ['string'], format: null, nullable: !!node.nullable }
+
+  return { types: node.type ? [node.type] : [], format: node.format ?? null, nullable: !!node.nullable }
+}
+
+/**
+ * 请求体比对：只比会真的提交上去的字段（form !== false）。
+ * 口径与响应侧一致——「会导致请求失败或数据丢失」= error，「可能是有意为之」= warn。
+ */
+function compareRequestFields(spec, domain, schema, action, report) {
+  const props = schema?.properties ?? {}
+  const required = Array.isArray(schema?.required) ? schema.required : []
+  const submittable = Object.entries(domain.fields).filter(([, field]) => field.form !== false)
+
+  for (const [key, field] of submittable) {
+    const prop = props[key]
+
+    if (!prop) {
+      report(
+        'error',
+        `field ${key} not accepted in ${action} body (表单会提交这个字段，但接口不收)`
+      )
+      continue
+    }
+
+    const info = normalize(spec, prop, 0)
+    const expected = TYPE_COMPATIBLE[field.type] ?? []
+
+    if (expected.length > 0 && info.types.length > 0 && !info.types.some((t) => expected.includes(t))) {
+      report('error', `提交的 ${key} 类型对不上：配置写 ${field.type}，后端是 ${info.types.join(' | ')}`)
+      continue
+    }
+
+    const wanted = field.type === 'date' ? 'date' : field.type === 'datetime' ? 'date-time' : null
+    if (wanted && info.format && info.format !== wanted) {
+      report('warn', `提交的 ${key} 时间格式对不上：配置 ${wanted}，后端 ${info.format}`)
+    }
+  }
+
+  // 后端要求必填，但 config 里没有这个可提交字段 → 一定 422
+  for (const key of required) {
+    if (key === 'id') continue
+    const field = domain.fields[key]
+    if (!field || field.form === false) {
+      report('error', `required ${key} in ${action} body, but config has no submittable field (后端要求必传，配置里没有可提交字段)`)
+    }
+  }
+
+  // 后端可选、config 没声明：可能是有意为之
+  for (const key of Object.keys(props)) {
+    if (key === 'id') continue
+    if (!domain.fields[key]) {
+      report('warn', `后端接受 ${key} 这个提交字段，配置里没写，表单不会提交它`)
+    }
+  }
+}
+
+function compareFields(spec, domain, schema, report) {
+  const props = schema?.properties ?? {}
+  const required = Array.isArray(schema?.required) ? schema.required : []
+
+  for (const [key, field] of Object.entries(domain.fields)) {
+    const prop = props[key]
+
+    if (!prop) {
+      report('error', `field ${key} missing in backend contract (配置里有，后端没有，请求发出去会被丢掉)`)
+      continue
+    }
+
+    const info = normalize(spec, prop, 0)
+    const expected = TYPE_COMPATIBLE[field.type] ?? []
+
+    if (expected.length > 0 && info.types.length > 0 && !info.types.some((t) => expected.includes(t))) {
+      report('error', `type mismatch on ${key}: config says ${field.type}, backend says ${info.types.join(' | ')} (类型对不上)`)
+      continue
+    }
+
+    const wanted = field.type === 'date' ? 'date' : field.type === 'datetime' ? 'date-time' : null
+    if (wanted && info.format && info.format !== wanted) {
+      report('warn', `${key} 的时间格式对不上：配置 ${wanted}，后端 ${info.format}`)
+    }
+
+    if (field.required && !required.includes(key)) {
+      report('warn', `${key} 你标了必填，后端是可选的`)
+    }
+    if (!field.required && required.includes(key)) {
+      report('warn', `required backend-side, missing in config (后端要求必填，配置里没标)`)
+    }
+  }
+
+  for (const key of Object.keys(props)) {
+    if (key === 'id') continue
+    if (!domain.fields[key]) {
+      report('warn', `后端有 ${key} 这个字段，配置里没写（列表和表单都不会显示它）`)
+    }
+  }
+}

package/tha/verify/rules.mjs

@@ -0,0 +1,91 @@
+// ============ 护栏规则表：每条规则只在这里定义一次 ============
+// 规则 id 是「文档 ↔ 检查器」的唯一纽带：架构图改了哪句，就改这条规则的 basis；
+// 输出里出现哪个 id，就能回溯到哪句架构约束。
+// level：error = 破架构（退出码 1）；warn = 灰区（--strict 时才算失败）。
+// 判断逻辑在 boundary.mjs，这里只放「说给人和 CI 听的话」。
+//
+// 文案口径：title / fix 是给开发看的结果行，只用业务语言，不出现中枢 / 零件 / 生成位这类架构名词；
+// basis 保留架构原话，用于回溯到文档。
+
+export const RULES = {
+  'HUB-01': {
+    level: 'error',
+    title: '模块入口绕开动作，直接调内部函数',
+    basis: '中枢只做分发：把意图交给执行器；禁止直接依赖执行器内部步骤',
+    fix: '把这类控制动作放进动作文件（如 stop），或由 context.ts 提供'
+  },
+  'HUB-03': {
+    level: 'warn',
+    title: '模块入口不是单例，被重复创建',
+    basis: '每个领域全局唯一实例，视图不能各造一个「私人大脑」',
+    fix: '在模块顶层用 let 缓存：if (!module) module = createXxxModule()'
+  },
+  'EXE-01': {
+    level: 'error',
+    title: '两个动作文件互相 import',
+    basis: '执行器之间互不引用：共用逻辑下沉成零件，用例顺序留在各自执行器里',
+    fix: '把共用的那段抽到 steps/，两个动作都调它'
+  },
+  'EXE-02': {
+    level: 'error',
+    title: '动作文件绕开 ctx，直接调接口或改状态',
+    basis: '执行器只认 ctx：网络走 ctx.api，状态走 ctx.state',
+    fix: '改从 ctx.api / ctx.state 取；缺什么就往 context.ts 里加'
+  },
+  'EXE-03': {
+    level: 'error',
+    title: '动作文件直接用工具库（该从 ctx 拿）',
+    basis: '执行器只认 ctx：日志/时钟/流/鉴权走 ctx.ports，判定走 ctx.errors',
+    fix: '把实现放进 context.ts 的端口；确实是纯函数的登记到纯函数白名单'
+  },
+  'STEP-01': {
+    level: 'warn',
+    title: '共用的函数只有一个动作在用',
+    basis: '零件是「同一段步骤被第二个用例用到」才下沉的；只有一个使用者是过度设计',
+    fix: '先内联回动作文件；真有第二个动作用时再抽出来'
+  },
+  'VIEW-01': {
+    level: 'error',
+    title: '页面绕开模块入口，直接调接口',
+    basis: '视图只表达意图：动作走域中枢，数据直读状态层',
+    fix: '改调 useXxxModule() 上的动作；缺动作就在模块入口加一个'
+  },
+  'VIEW-02': {
+    level: 'error',
+    title: '页面自己创建了模块实例',
+    basis: '每个领域全局唯一实例：视图只能经 useXxxModule() 取，不能自己 create',
+    fix: '改用 useXxxModule()；需要独立能力就在模块入口加动作'
+  },
+  'STORE-01': {
+    level: 'error',
+    title: '状态文件里发请求',
+    basis: '状态层只存状态，不发请求',
+    fix: '把请求挪进动作文件，拿到结果再写回 state'
+  },
+  'UTIL-01': {
+    level: 'error',
+    title: '工具文件里用了 UI 库或业务模块',
+    basis: '传输层只上报不越权：不感知业务模块，不做展示',
+    fix: '提示交给页面（订阅错误总线）；业务判断交给动作文件'
+  }
+}
+
+/**
+ * 执行器/零件允许直接 import 的纯函数工具
+ * 判据：无副作用、不持有状态、不依赖运行时环境（换实现无意义）
+ * 新增一条必须写理由：它为什么不属于「外界」
+ */
+export const PURE_UTILS = ['@/utils/adapters', '@/utils/format', '@/utils/number']
+
+/** 基础设施里属于「能力」而非「纯函数」的模块：必须经 ctx.ports 注入 */
+export const PORT_UTILS = [
+  '@/utils/stream',
+  '@/utils/request',
+  '@/utils/auth',
+  '@/utils/logger',
+  '@/utils/stopwatch',
+  '@/utils/time',
+  '@/utils/token',
+  '@/utils/errorBus',
+  '@/utils/error'
+]

package/tha/verify/scan.mjs

@@ -0,0 +1,59 @@
+// ============ 模块发现：config 驱动的模块 + 纯手写模块 ============
+// 护栏模式的前提是「看得见手写模块」：复杂模块没有 config，构造机不生成它，
+// 但它仍然在架构里，仍然要被检查。扫描只看目录形状，不看有没有 config。
+
+import path from 'node:path'
+import { exists, listDirectories, walkFiles } from '../utils/files.mjs'
+import { absPath, relPath } from '../config/paths.mjs'
+
+/**
+ * 描述一个模块的实际文件形状
+ * @param root 项目根目录
+ * @param name 模块目录名（<domains>/<name>）
+ * @param dirs 目录映射
+ * @returns { name, hub(相对路径或 null), executors(绝对路径), steps(绝对路径) }
+ */
+export function describeModule(root, name, dirs) {
+  const dir = absPath(root, dirs, 'domains', name)
+  const hub = path.join(dir, 'index.ts')
+
+  return {
+    name,
+    hub: exists(hub) ? relPath(dirs, 'domains', name, 'index.ts') : null,
+    executors: walkFiles(path.join(dir, 'executors'), ['.ts']),
+    steps: walkFiles(path.join(dir, 'steps'), ['.ts'])
+  }
+}
+
+/**
+ * 扫描没有 config 的手写模块
+ * @param root       项目根目录
+ * @param configured 已有 config 的模块名集合
+ * @param dirs       目录映射
+ * @returns 模块描述列表（source = 'manual'）
+ */
+export function scanManualModules(root, configured, dirs) {
+  const dir = absPath(root, dirs, 'domains')
+  if (!exists(dir)) return []
+
+  return listDirectories(dir)
+    .filter((name) => !configured.has(name))
+    .map((name) => describeModule(root, name, dirs))
+    .filter((module) => module.hub || module.executors.length > 0 || module.steps.length > 0)
+    .map((module) => ({ ...module, source: 'manual' }))
+}
+
+/**
+ * 给 config 驱动的模块补上实际文件形状
+ * @param domains 已通过配置校验的模块
+ * @param root    项目根目录
+ * @param dirs    目录映射
+ * @returns 模块描述列表（source = 'config'，附带原始配置）
+ */
+export function describeConfigured(domains, root, dirs) {
+  return domains.map((domain) => ({
+    ...describeModule(root, domain.name, dirs),
+    source: 'config',
+    domain
+  }))
+}

package/tha.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { run } from './tha/cli.mjs'
+import { configureStyle, glyph, ui } from './tha/utils/style.mjs'
+
+const argv = process.argv.slice(2)
+
+configureStyle({
+  noColor: argv.includes('--no-color'),
+  color: !argv.includes('--no-color') && argv.includes('--color')
+})
+
+run(argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  const [headline, ...details] = message.split('\n')
+
+  console.error('')
+  console.error(`  ${ui.danger(glyph.err)} ${ui.bold(headline)}`)
+  for (const line of details) {
+    console.error(`    ${ui.muted(line)}`)
+  }
+  process.exitCode = 1
+})