tha-cli 0.0.0-stage → 0.1.1

package/tha/verify/ast.mjs

@@ -0,0 +1,143 @@
+// ============ AST 工具：import 关系与中枢函数体检查 ============
+// 契约检查与护栏检查共用这一份实现：同一件事只解析一次，判定口径不会分叉。
+// .vue 文件先抽 script 块再解析，行号回填到文件真实行。
+
+import { ts } from '../utils/ts.mjs'
+
+/**
+ * 解析文件（.vue 只取 script 块）
+ * @param file 文件绝对路径（用扩展名判断是否 .vue）
+ * @param text 文件内容
+ * @returns 每个 script 块与其起始行偏移
+ */
+function parseBlocks(file, text) {
+  if (!file.endsWith('.vue')) {
+    return [{ sourceFile: ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS), offset: 0 }]
+  }
+
+  const blocks = []
+  const pattern = /<script\b[^>]*>([\s\S]*?)<\/script>/gi
+  let match
+
+  while ((match = pattern.exec(text))) {
+    const code = match[1]
+    const codeStart = match.index + match[0].indexOf(code)
+    const offset = text.slice(0, codeStart).split('\n').length - 1
+    blocks.push({
+      sourceFile: ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS),
+      offset
+    })
+  }
+
+  return blocks.length > 0
+    ? blocks
+    : [{ sourceFile: ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS), offset: 0 }]
+}
+
+function isTypeOnly(node) {
+  if (ts.isExportDeclaration(node)) return node.isTypeOnly === true
+
+  const clause = node.importClause
+  if (!clause) return false
+  if (clause.isTypeOnly) return true
+  if (clause.name) return false
+
+  const bindings = clause.namedBindings
+  if (!bindings) return false
+  if (ts.isNamespaceImport(bindings)) return false
+
+  return bindings.elements.length > 0 && bindings.elements.every((element) => element.isTypeOnly)
+}
+
+function specifierOf(node) {
+  if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+    const specifier = node.moduleSpecifier
+    if (specifier && ts.isStringLiteral(specifier)) return specifier
+  }
+  return null
+}
+
+function importedNames(node) {
+  if (ts.isExportDeclaration(node)) {
+    const clause = node.exportClause
+    if (!clause || !ts.isNamedExports(clause)) return []
+    return clause.elements.filter((element) => !element.isTypeOnly).map((element) => element.name.text)
+  }
+
+  const clause = node.importClause
+  if (!clause) return []
+
+  const names = []
+  if (clause.name) names.push(clause.name.text)
+
+  const bindings = clause.namedBindings
+  if (bindings) {
+    if (ts.isNamespaceImport(bindings)) names.push(bindings.name.text)
+    else names.push(...bindings.elements.filter((element) => !element.isTypeOnly).map((element) => element.name.text))
+  }
+
+  return names
+}
+
+/**
+ * 提取文件里的运行时依赖（含 re-export；`import type` 不计）
+ * @param file 文件绝对路径
+ * @param text 文件内容
+ * @returns [{ spec, line, names }]：模块路径、真实行号、引入的本地名
+ */
+export function importsFrom(file, text) {
+  const imports = []
+
+  for (const block of parseBlocks(file, text)) {
+    const { sourceFile, offset } = block
+
+    for (const node of sourceFile.statements) {
+      const specifier = specifierOf(node)
+      if (!specifier || isTypeOnly(node)) continue
+
+      imports.push({
+        spec: specifier.text,
+        line: offset + sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+        names: importedNames(node)
+      })
+    }
+  }
+
+  return imports
+}
+
+/**
+ * 按名字找函数声明
+ * @param sourceFile TS 语法树
+ * @param name       函数名
+ * @returns 函数节点或 null
+ */
+export function findFunction(sourceFile, name) {
+  for (const statement of sourceFile.statements) {
+    if (!ts.isFunctionDeclaration(statement)) continue
+    if (statement.name?.text === name) return statement
+  }
+  return null
+}
+
+/**
+ * 中枢函数体违约：if 分支 / await / 直接调用 ctx.api
+ * @param hub 中枢函数节点
+ * @returns 违约描述列表
+ */
+export function hubViolations(hub) {
+  const found = new Set()
+
+  const visit = (node) => {
+    if (ts.isIfStatement(node)) found.add('出现了 if 分支')
+    else if (ts.isAwaitExpression(node)) found.add('出现了 await')
+    else if (ts.isPropertyAccessExpression(node) && node.getText().startsWith('ctx.api')) {
+      found.add('直接调用了 ctx.api')
+    }
+    ts.forEachChild(node, visit)
+  }
+
+  if (hub.body) visit(hub.body)
+
+  return [...found]
+}

package/tha/verify/boundary.mjs

@@ -0,0 +1,219 @@
+// ============ 护栏检查：按「层」判 import 越界，不按模块 ============
+// 模块级（中枢 / 执行器 / 零件）按 <domains>/<模块> 扫；
+// 层级（视图 / 状态 / 基础设施）全局扫一遍 —— 因为文件边界是层边界，不是模块边界。
+// 所有判定只看运行时 import（import type 放行）：类型不构成依赖。
+// 目录前缀一律由目录映射推出，规则本身不认识具体目录名。
+
+import path from 'node:path'
+import { importsFrom } from './ast.mjs'
+import { PURE_UTILS, RULES } from './rules.mjs'
+import { importSpec } from '../config/paths.mjs'
+import { read, relativePath, walkFiles } from '../utils/files.mjs'
+
+const PURE_NAMES = PURE_UTILS.map((spec) => spec.replace(/^@\/utils\//, ''))
+
+/**
+ * 护栏检查入口
+ * @param modules 模块描述列表（见 scan.mjs 的 describeModule）
+ * @param root    项目根目录
+ * @param dirs    目录映射
+ * @returns 偏离清单 [{ rule, level, file, line, message, basis, fix }]
+ */
+export function checkBoundaries(modules, root, dirs) {
+  const problems = []
+  importCache.clear()
+
+  for (const module of modules) inspectModule(module, root, dirs, problems)
+
+  inspectViews(root, dirs, problems)
+  inspectStores(root, dirs, problems)
+  inspectUtils(root, dirs, problems)
+
+  return problems.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line)
+}
+
+function report(problems, rule, file, line, note = '') {
+  const meta = RULES[rule]
+  problems.push({
+    rule,
+    level: meta.level,
+    file,
+    line,
+    message: meta.title,
+    note,
+    basis: meta.basis,
+    fix: meta.fix
+  })
+}
+
+const importCache = new Map()
+
+function imports(filename) {
+  const cached = importCache.get(filename)
+  if (cached) return cached
+
+  const parsed = importsFrom(filename, read(filename))
+  importCache.set(filename, parsed)
+  return parsed
+}
+
+/** 模块级：中枢不许抓零件、中枢应单例、执行器互不引用、执行器只认 ctx */
+function inspectModule(module, root, dirs, problems) {
+  if (module.hub) {
+    const hubFile = path.join(root, module.hub)
+    const hubText = read(hubFile)
+
+    for (const imported of importsFrom(hubFile, hubText)) {
+      if (/^(\.\.?\/)+steps\//.test(imported.spec)) {
+        report(problems, 'HUB-01', module.hub, imported.line, `import ${imported.spec}`)
+      }
+    }
+
+    if (!isSingletonHub(hubText)) {
+      report(problems, 'HUB-03', module.hub, 1, '没找到缓存的实例（每次调用都会新建一个）')
+    }
+  }
+
+  const transportPrefixes = [
+    importSpec(dirs, 'api'),
+    importSpec(dirs, 'stores'),
+    importSpec(dirs, 'router'),
+    '@/store'
+  ]
+
+  for (const executor of module.executors) {
+    for (const imported of imports(executor)) {
+      const file = relativePath(root, executor)
+
+      if (/^(\.\.?\/)+executors\//.test(imported.spec) || imported.spec.startsWith('./')) {
+        report(problems, 'EXE-01', file, imported.line, `import ${imported.spec}`)
+      }
+      if (matchesAnyPrefix(imported.spec, transportPrefixes)) {
+        report(problems, 'EXE-02', file, imported.line, `import ${imported.spec}`)
+      }
+      if (isForbiddenUtil(imported.spec, dirs)) {
+        report(problems, 'EXE-03', file, imported.line, `import ${imported.spec}`)
+      }
+    }
+  }
+
+  for (const step of module.steps) {
+    for (const imported of imports(step)) {
+      const file = relativePath(root, step)
+
+      if (matchesAnyPrefix(imported.spec, transportPrefixes)) {
+        report(problems, 'EXE-02', file, imported.line, `import ${imported.spec}`)
+      }
+      if (isForbiddenUtil(imported.spec, dirs)) {
+        report(problems, 'EXE-03', file, imported.line, `import ${imported.spec}`)
+      }
+    }
+  }
+
+  // 零件复用数：只被 0 或 1 个执行器引用 = 抽早了或死代码
+  for (const step of module.steps) {
+    const name = path.basename(step, '.ts')
+    const users = new Set()
+
+    for (const executor of module.executors) {
+      for (const imported of imports(executor)) {
+        if (new RegExp(`steps/${escapeRegExp(name)}$`).test(imported.spec)) {
+          users.add(executor)
+        }
+      }
+    }
+
+    if (users.size < 2) {
+      report(
+        problems,
+        'STEP-01',
+        relativePath(root, step),
+        1,
+        users.size === 0 ? '没有被任何执行器使用' : '只有 1 个执行器使用'
+      )
+    }
+  }
+}
+
+/** 视图层：不碰网络层、不碰执行器与零件、不自己造中枢实例 */
+function inspectViews(root, dirs, problems) {
+  const apiBase = importSpec(dirs, 'api')
+  const utilsBase = importSpec(dirs, 'utils')
+  const domainsBase = importSpec(dirs, 'domains')
+  const transportUtils = new Set([`${utilsBase}/request`, `${utilsBase}/stream`, `${utilsBase}/token`])
+  const factories = new RegExp(`^${escapeRegExp(domainsBase)}\\/[^/]+$`)
+
+  for (const file of walkFiles(path.join(root, dirs.views), ['.ts', '.vue'])) {
+    const rel = relativePath(root, file)
+    for (const imported of imports(file)) {
+      if (
+        imported.spec.startsWith(`${apiBase}/`) ||
+        transportUtils.has(imported.spec) ||
+        new RegExp(`${escapeRegExp(domainsBase)}\\/[^/]+\\/(executors|steps)\\/`).test(imported.spec)
+      ) {
+        report(problems, 'VIEW-01', rel, imported.line, `import ${imported.spec}`)
+      }
+
+      if (factories.test(imported.spec)) {
+        const factory = imported.names.find((name) => /^create[A-Z]\w*Module$/.test(name))
+        if (factory) report(problems, 'VIEW-02', rel, imported.line, `import { ${factory} } from '${imported.spec}'`)
+      }
+    }
+  }
+}
+
+/** 状态层：不发请求 */
+function inspectStores(root, dirs, problems) {
+  const apiBase = importSpec(dirs, 'api')
+
+  for (const file of walkFiles(path.join(root, dirs.stores), ['.ts'])) {
+    const rel = relativePath(root, file)
+    for (const imported of imports(file)) {
+      if (imported.spec.startsWith(`${apiBase}/`)) {
+        report(problems, 'STORE-01', rel, imported.line, `import ${imported.spec}`)
+      }
+    }
+  }
+}
+
+/** 基础设施：只上报不越权（不做展示、不感知业务模块） */
+function inspectUtils(root, dirs, problems) {
+  const viewsBase = importSpec(dirs, 'views')
+  const domainsBase = importSpec(dirs, 'domains')
+
+  for (const file of walkFiles(path.join(root, dirs.utils), ['.ts'])) {
+    const rel = relativePath(root, file)
+    for (const imported of imports(file)) {
+      if (
+        imported.spec === 'element-plus' ||
+        imported.spec.startsWith(`${viewsBase}/`) ||
+        imported.spec.startsWith(`${domainsBase}/`)
+      ) {
+        report(problems, 'UTIL-01', rel, imported.line, `import ${imported.spec}`)
+      }
+    }
+  }
+}
+
+function matchesAnyPrefix(spec, prefixes) {
+  return prefixes.some((prefix) => spec === prefix || spec.startsWith(`${prefix}/`))
+}
+
+function isForbiddenUtil(spec, dirs) {
+  const base = importSpec(dirs, 'utils')
+  if (spec === base) return true
+  if (!spec.startsWith(`${base}/`)) return false
+  return !PURE_NAMES.includes(spec.slice(base.length + 1))
+}
+
+/** 中枢是否模块级单例：惰性缓存（let + if (!x)）或模块级常量 */
+function isSingletonHub(text) {
+  if (/(?:export\s+)?const\s+\w+\s*(?::\s*[^=]+)?=\s*create[A-Z]\w*Module\s*\(/.test(text)) return true
+
+  const cached = [...text.matchAll(/\blet\s+([A-Za-z_$][\w$]*)/g)].map((match) => match[1])
+  return cached.some((name) => new RegExp(`if\\s*\\(\\s*!\\s*${escapeRegExp(name)}\\s*\\)`).test(text))
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/tha/verify/contract.mjs

@@ -0,0 +1,186 @@
+// ============ 契约检查：中枢活在不在、导出名对不对、有没有变厚 ============
+// 两种模块都要过：config 驱动的（标准 5 文件 + 动作挂载）和纯手写的（只有中枢契约）。
+// 手写模块的视图目录名不一定等于模块名（如 chat → views/Home），所以不查页面模板。
+
+import path from 'node:path'
+import { ts } from '../utils/ts.mjs'
+import { exists, listFiles, read } from '../utils/files.mjs'
+import { findFunction, hubViolations } from './ast.mjs'
+import { pascal } from '../generate/names.mjs'
+import { relPath } from '../config/paths.mjs'
+
+const PAGE_LABEL = { list: '列表页', detail: '详情页', form: '表单页' }
+
+/**
+ * 契约检查：中枢是否存在、createXxxModule 是否存在、中枢是否违约（if / await / ctx.api）、
+ * config 模块另外检查页面模板与动作挂载。只做静态分析，不执行模块代码。
+ * @param modules 模块描述列表（source = 'config' | 'manual'）
+ * @param root    项目根目录
+ * @param dirs    目录映射
+ * @returns 问题清单 [{ file, line, message }]
+ */
+export function checkContracts(modules, root, dirs) {
+  const problems = []
+
+  for (const module of modules) checkModule(module, root, dirs, problems)
+
+  return problems
+}
+
+function checkModule(module, root, dirs, problems) {
+  const type = pascal(module.name)
+  const hubRel = relPath(dirs, 'domains', module.name, 'index.ts')
+  const hubFile = path.join(root, hubRel)
+  const manual = module.source === 'manual'
+
+  // 1. 中枢必须存在（sync 只补一次骨架，删了就是真没了）
+  if (!exists(hubFile)) {
+    problems.push({
+      file: hubRel,
+      message: `missing hub file ${hubRel}, run tha sync ${module.name} to scaffold it (少了模块入口，运行 sync 会补一个)`
+    })
+    return
+  }
+
+  // 2. 页面模板：只对 config 模块要求；按 pages 逐页检查
+  //    （手写模块的视图目录名不必等于模块名，所以整体跳过）
+  if (!manual) {
+    const pages = module.domain.pages ?? ['list']
+    const pageFiles = { list: 'Index.vue', detail: 'Detail.vue', form: 'Form.vue' }
+
+    for (const page of pages) {
+      const viewRel = relPath(dirs, 'views', module.name, pageFiles[page] ?? 'Index.vue')
+      if (!exists(path.join(root, viewRel))) {
+        problems.push({
+          file: viewRel,
+          message: `missing ${page} page, run tha sync to generate it, or write it yourself then adopt (少了这个页面)`
+        })
+      }
+    }
+  }
+
+  const text = read(hubFile)
+  const expected = `create${type}Module`
+  const alias = `use${type}Module`
+  const sourceFile = ts.createSourceFile(hubFile, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+
+  // 3. 装配入口必须存在：createXxxModule（生成器产出的装配函数）或 useXxxModule（单例访问）
+  const hub = findFunction(sourceFile, expected) ?? findFunction(sourceFile, alias)
+  if (!hub) {
+    problems.push({
+      file: hubRel,
+      message: `expected ${expected}() or ${alias}() in hub, the file may have been edited (模块入口里少了这两个函数)`
+    })
+    return
+  }
+
+  // 4. 中枢违约：只挂载，不判断、不 await、不调接口
+  for (const violation of hubViolations(hub)) {
+    problems.push({
+      file: hubRel,
+      message: `hub must only mount actions, found: ${violation} (模块入口出现了不该有的逻辑)`
+    })
+  }
+
+  // 5. 动作必须挂上（只对 config 模块：手写模块的动作由用例决定）
+  if (manual) return
+
+  // 6. 声明了权限码，执行器里就得真有判断（adopt 之后最容易丢的就是这一行）
+  checkPermissionGuards(module, root, dirs, problems)
+
+  const mounted = mountedActions(hub)
+  const crud = module.domain.crud ?? {}
+  const pages = module.domain.pages ?? ['list']
+
+  const required = ['refresh']
+  if (crud.create) required.push('create')
+  if (crud.update) required.push('update')
+  if (crud.remove) required.push('remove')
+  if (pages.includes('detail') || pages.includes('form')) required.push('load')
+
+  // 兼容旧骨架：save 同时承担新增与编辑
+  const legacySave = mounted.has('save')
+
+  for (const action of required) {
+    if (mounted.has(action)) continue
+    if (legacySave && (action === 'create' || action === 'update')) continue
+    problems.push({
+      file: hubRel,
+      message: `missing action ${action} in hub, mount it or drop the capability from config (入口没挂这个动作)`
+    })
+  }
+}
+
+/**
+ * 声明了权限码，执行器里就必须真有一处 can(...) 判断。
+ * adopt 之后生成物归人管，生成模板里的 ctx.can 可能被删掉 —— 这里是唯一还能发现的地方。
+ */
+function checkPermissionGuards(module, root, dirs, problems) {
+  const codes = module.domain.permissions
+  if (!codes || Object.keys(codes).length === 0) return
+
+  const executorsRel = relPath(dirs, 'domains', module.name, 'executors')
+  const dir = path.join(root, executorsRel)
+  if (!exists(dir)) return
+
+  const files = listFiles(dir, '.ts')
+  if (files.length === 0) return
+
+  const hasGuard = files.some((file) => /\bcan\s*\(/.test(stripComments(read(path.join(dir, file)))))
+
+  if (hasGuard) return
+
+  problems.push({
+    file: executorsRel,
+    message:
+      'permissions declared, but no ctx.can() anywhere in the action files (配了权限码却没做权限判断，等于没开权限)'
+  })
+}
+
+function stripComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '')
+}
+
+function unwrapExpr(node) {
+  let current = node
+
+  while (
+    ts.isParenthesizedExpression(current) ||
+    ts.isAsExpression(current) ||
+    ts.isTypeAssertionExpression(current) ||
+    (typeof ts.isSatisfiesExpression === 'function' && ts.isSatisfiesExpression(current)) ||
+    ts.isNonNullExpression(current)
+  ) {
+    current = current.expression
+  }
+
+  return current
+}
+
+/**
+ * 中枢 return 的对象字面量里挂了哪些动作名
+ */
+function mountedActions(hub) {
+  const actions = new Set()
+  const body = hub.body
+  if (!body) return actions
+
+  for (const statement of body.statements) {
+    if (!ts.isReturnStatement(statement) || !statement.expression) continue
+
+    const expression = unwrapExpr(statement.expression)
+    if (!ts.isObjectLiteralExpression(expression)) continue
+
+    for (const property of expression.properties) {
+      if (
+        ts.isPropertyAssignment(property) ||
+        ts.isMethodDeclaration(property) ||
+        ts.isShorthandPropertyAssignment(property)
+      ) {
+        actions.add(property.name.getText().replace(/['"]/g, ''))
+      }
+    }
+  }
+
+  return actions
+}