tha-cli 0.1.3 → 0.1.4

package/tha/utils/eslint.mjs

@@ -0,0 +1,288 @@
+// ============ ESLint 自动配置：检测、安装、写配置、验证 ============
+
+import path from 'node:path'
+import { execSync } from 'node:child_process'
+import { exists, read, writeAtomic } from './files.mjs'
+
+/**
+ * 检测项目环境
+ * @param root 项目根目录
+ * @returns { hasEslint, packageManager, hasEslintConfig, hasVue }
+ */
+export function detectEslintEnv(root) {
+  const packageJsonPath = path.join(root, 'package.json')
+  let hasEslint = false
+  let hasVue = false
+
+  if (exists(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(read(packageJsonPath))
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+      hasEslint = !!deps.eslint
+      hasVue = !!(deps.vue || deps['vue-router'])
+    } catch {
+      // package.json 解析失败，按没有处理
+    }
+  }
+
+  // 判断包管理器
+  let packageManager = 'npm'
+  if (exists(path.join(root, 'pnpm-lock.yaml'))) packageManager = 'pnpm'
+  else if (exists(path.join(root, 'yarn.lock'))) packageManager = 'yarn'
+
+  // 检测有没有 ESLint 配置文件（新旧格式都算）
+  const configFiles = [
+    'eslint.config.js',
+    'eslint.config.mjs',
+    'eslint.config.cjs',
+    '.eslintrc.json',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.yml'
+  ]
+  const hasEslintConfig = configFiles.some((file) => exists(path.join(root, file)))
+
+  return { hasEslint, packageManager, hasEslintConfig, hasVue }
+}
+
+/**
+ * 自动安装 ESLint 依赖
+ * @param root 项目根目录
+ * @param env 检测结果
+ * @returns { installed: string[], failed: string[] }
+ */
+export function installEslintDeps(root, env) {
+  const installed = []
+  const failed = []
+
+  const packages = ['eslint', '@eslint/js', '@typescript-eslint/parser', '@typescript-eslint/eslint-plugin']
+  if (env.hasVue) packages.push('eslint-plugin-vue')
+
+  const pm = env.packageManager
+  const installCmd = pm === 'npm'
+    ? `npm install -D ${packages.join(' ')}`
+    : pm === 'yarn'
+      ? `yarn add -D ${packages.join(' ')}`
+      : `pnpm add -D ${packages.join(' ')}`
+
+  try {
+    execSync(installCmd, { cwd: root, stdio: 'inherit' })
+    installed.push(...packages)
+  } catch (error) {
+    failed.push(...packages)
+  }
+
+  return { installed, failed }
+}
+
+/**
+ * 自动写 ESLint 配置（flat config 格式，ESLint 9+）
+ * @param root 项目根目录
+ * @param env 检测结果
+ * @returns { written: string, skipped: boolean }
+ */
+export function writeEslintConfig(root, env) {
+  // 已有配置文件，跳过（后面可以做追加逻辑）
+  if (env.hasEslintConfig) {
+    return { written: null, skipped: true }
+  }
+
+  // 生成 flat config 格式（eslint.config.js）—— 最小配置，只保证 tha 规则能跑
+  const configContent = `import tsparser from '@typescript-eslint/parser'
+import vueParser from 'vue-eslint-parser'
+import tha from 'tha-cli/tha/eslint-rules/index.js'
+
+export default [
+  {
+    ignores: ['dist/**', 'node_modules/**']
+  },
+  // .ts 文件直接用 typescript parser
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      ecmaVersion: 'latest',
+      sourceType: 'module'
+    },
+    plugins: {
+      tha
+    },
+    rules: {
+      // THA 架构边界规则
+      'tha/hub-no-import-steps': 'error',
+      'tha/executor-no-cross-import': 'error',
+      'tha/executor-no-import-api': 'error',
+      'tha/executor-no-import-utils': 'error',
+      'tha/view-no-import-api': 'error',
+      'tha/view-no-create-module': 'error',
+      'tha/store-no-import-api': 'error',
+      'tha/util-no-import-ui': 'error'
+    },
+    settings: {
+      tha: {
+        dirs: {
+          domains: 'src/domains',
+          views: 'src/views',
+          stores: 'src/stores',
+          api: 'src/api',
+          utils: 'src/utils'
+        }
+      }
+    }
+  },
+  // .vue 文件先用 vue-eslint-parser 解析模板，再用 typescript parser 解析 script
+  {
+    files: ['**/*.vue'],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: {
+        parser: tsparser,
+        ecmaVersion: 'latest',
+        sourceType: 'module'
+      }
+    },
+    plugins: {
+      tha
+    },
+    rules: {
+      // THA 架构边界规则
+      'tha/hub-no-import-steps': 'error',
+      'tha/executor-no-cross-import': 'error',
+      'tha/executor-no-import-api': 'error',
+      'tha/executor-no-import-utils': 'error',
+      'tha/view-no-import-api': 'error',
+      'tha/view-no-create-module': 'error',
+      'tha/store-no-import-api': 'error',
+      'tha/util-no-import-ui': 'error'
+    },
+    settings: {
+      tha: {
+        dirs: {
+          domains: 'src/domains',
+          views: 'src/views',
+          stores: 'src/stores',
+          api: 'src/api',
+          utils: 'src/utils'
+        }
+      }
+    }
+  }
+]
+`
+
+  const configPath = path.join(root, 'eslint.config.js')
+  writeAtomic(configPath, configContent)
+
+  return { written: 'eslint.config.js', skipped: false }
+}
+
+/**
+ * 验证 ESLint 规则是否生效
+ * @param root 项目根目录
+ * @returns { ok: boolean, message: string }
+ */
+export function verifyEslintRules(root) {
+  try {
+    // 跑 eslint --print-config，看输出里有没有 tha 规则
+    const output = execSync('npx eslint --print-config src/domains/user/index.ts', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    })
+
+    const config = JSON.parse(output)
+    const hasThaRules = Object.keys(config.rules || {}).some((key) => key.startsWith('tha/'))
+
+    if (hasThaRules) {
+      return { ok: true, message: 'ESLint 规则已生效' }
+    } else {
+      return { ok: false, message: 'ESLint 规则未生效，请检查配置文件' }
+    }
+  } catch (error) {
+    // 文件不存在或者 eslint 跑不起来，不阻塞
+    return { ok: false, message: '无法验证 ESLint 规则（可能是项目还没有 domains 目录）' }
+  }
+}
+
+/**
+ * 检查 ESLint 配置完整性：有没有 tha 规则
+ * @param root 项目根目录
+ * @returns [{ rule, level, file, message }]
+ */
+export function checkEslintConfig(root) {
+  const problems = []
+
+  // 找 ESLint 配置文件（先找新格式，再找旧格式）
+  const configFiles = [
+    'eslint.config.js',
+    'eslint.config.mjs',
+    'eslint.config.cjs',
+    '.eslintrc.json',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.yml'
+  ]
+
+  const configFile = configFiles.find((file) => exists(path.join(root, file)))
+
+  if (!configFile) {
+    problems.push({
+      rule: 'ESLINT-CONFIG-MISSING',
+      level: 'warn',
+      file: '.eslintrc.json',
+      message: '没有 ESLint 配置文件，THA 规则不会生效'
+    })
+    return problems
+  }
+
+  // 读配置文件
+  let config
+  try {
+    if (configFile.endsWith('.json')) {
+      config = JSON.parse(read(path.join(root, configFile)))
+    } else {
+      // .js / .cjs 配置文件不好直接读，跳过解析，只提示
+      problems.push({
+        rule: 'ESLINT-CONFIG-UNCHECKED',
+        level: 'warn',
+        file: configFile,
+        message: 'JS 格式的 ESLint 配置无法自动检查，请确认有没有加 tha 规则'
+      })
+      return problems
+    }
+  } catch {
+    problems.push({
+      rule: 'ESLINT-CONFIG-PARSE-ERROR',
+      level: 'error',
+      file: configFile,
+      message: 'ESLint 配置文件解析失败'
+    })
+    return problems
+  }
+
+  // 检查 plugins 里有没有 tha
+  const plugins = config.plugins || []
+  if (!plugins.includes('tha')) {
+    problems.push({
+      rule: 'ESLINT-PLUGIN-MISSING',
+      level: 'error',
+      file: configFile,
+      message: 'ESLint 配置里没有 tha 插件，THA 规则不会生效'
+    })
+  }
+
+  // 检查 rules 里有没有 tha 规则
+  const rules = config.rules || {}
+  const thaRules = Object.keys(rules).filter((key) => key.startsWith('tha/'))
+
+  if (thaRules.length === 0) {
+    problems.push({
+      rule: 'ESLINT-RULES-MISSING',
+      level: 'error',
+      file: configFile,
+      message: 'ESLint 配置里没有 tha 规则，边界检查不会生效'
+    })
+  }
+
+  return problems
+}

package/tha/verify/boundary.mjs

@@ -1,219 +0,0 @@
-// ============ 护栏检查：按「层」判 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/rules.mjs

@@ -1,91 +0,0 @@
-// ============ 护栏规则表：每条规则只在这里定义一次 ============
-// 规则 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'
-]