tha-cli 0.0.0-stage → 0.1.0

package/tha/config/field.mjs

@@ -0,0 +1,178 @@
+import {
+  ENUM_COLORS,
+  FIELD_KEYS,
+  FIELD_TYPES,
+  OPTION_KEYS,
+  SEARCH_TYPES,
+  error,
+  isPlainObject
+} from './rules.mjs'
+
+export function validateFields(errors, file, value) {
+  if (!isPlainObject(value)) {
+    error(errors, file, 'fields', '必须是对象，至少一个字段')
+    return null
+  }
+
+  const keys = Object.keys(value)
+  if (keys.length === 0) {
+    error(errors, file, 'fields', '至少一个字段')
+    return null
+  }
+
+  const fields = {}
+  let ok = true
+
+  for (const key of keys) {
+    const at = `fields.${key}`
+    if (!/^[a-z][a-zA-Z0-9]*$/.test(key)) {
+      error(errors, file, at, '字段名必须是小写开头，例如 title')
+      ok = false
+      continue
+    }
+    if (key === 'id') {
+      error(errors, file, at, 'id 由 CLI 生成，不用手写')
+      ok = false
+      continue
+    }
+
+    const raw = value[key]
+    if (!isPlainObject(raw)) {
+      error(errors, file, at, '必须是对象')
+      ok = false
+      continue
+    }
+
+    const before = errors.length
+
+    for (const property of Object.keys(raw)) {
+      if (!FIELD_KEYS.has(property)) {
+        error(errors, file, `${at}.${property}`, '不认识的配置项')
+      }
+    }
+
+    if (typeof raw.label !== 'string' || !raw.label.trim()) {
+      error(errors, file, `${at}.label`, '必须是非空字符串')
+    }
+
+    if (!FIELD_TYPES.has(raw.type)) {
+      error(errors, file, `${at}.type`, `类型不支持；可用：${[...FIELD_TYPES].join('、')}`)
+    }
+
+    for (const flag of ['required', 'list', 'form', 'search', 'readonly']) {
+      if (raw[flag] !== undefined && typeof raw[flag] !== 'boolean') {
+        error(errors, file, `${at}.${flag}`, '必须是 boolean')
+      }
+    }
+
+    if (raw.readonly === true && raw.form === true) {
+      error(errors, file, `${at}.form`, 'readonly 字段不能同时出现在表单里')
+    }
+
+    if (raw.search === true && !SEARCH_TYPES.has(raw.type)) {
+      error(errors, file, `${at}.search`, '只有 string、enum、number、date、datetime 可以搜索')
+    }
+
+    const options = validateOptions(errors, file, `${at}.options`, raw)
+    validateDefault(errors, file, `${at}.default`, raw, options)
+
+    if (errors.length !== before) {
+      ok = false
+      continue
+    }
+
+    fields[key] = {
+      label: raw.label.trim(),
+      type: raw.type,
+      required: raw.required === true,
+      list: raw.list !== false,
+      form: raw.readonly === true ? false : raw.form !== false,
+      search: raw.search === true,
+      readonly: raw.readonly === true,
+      ...(options ? { options } : {}),
+      ...(raw.default !== undefined ? { default: raw.default } : {})
+    }
+  }
+
+  return ok ? fields : null
+}
+
+function validateOptions(errors, file, at, field) {
+  if (field.type !== 'enum') {
+    if (field.options !== undefined) {
+      error(errors, file, at, '只有类型为 enum 的字段可以写 options')
+    }
+    return null
+  }
+
+  if (!Array.isArray(field.options) || field.options.length === 0) {
+    error(errors, file, at, '类型为 enum 的字段必须提供非空 options')
+    return null
+  }
+
+  const options = []
+  const values = new Set()
+
+  field.options.forEach((option, index) => {
+    const optionAt = `${at}[${index}]`
+    if (!isPlainObject(option)) {
+      error(errors, file, optionAt, '必须是 { label, value, color? }')
+      return
+    }
+
+    for (const key of Object.keys(option)) {
+      if (!OPTION_KEYS.has(key)) error(errors, file, `${optionAt}.${key}`, '不认识的配置项')
+    }
+
+    if (typeof option.label !== 'string' || !option.label.trim()) {
+      error(errors, file, `${optionAt}.label`, '必须是非空字符串')
+    }
+    if (typeof option.value !== 'string' || !option.value) {
+      error(errors, file, `${optionAt}.value`, '必须是非空字符串')
+    } else if (values.has(option.value)) {
+      error(errors, file, `${optionAt}.value`, `可选值重复：${option.value}`)
+    } else {
+      values.add(option.value)
+    }
+    if (option.color !== undefined && !ENUM_COLORS.has(option.color)) {
+      error(errors, file, `${optionAt}.color`, `未知颜色；可用：${[...ENUM_COLORS].join('、')}`)
+    }
+
+    options.push({
+      label: option.label,
+      value: option.value,
+      ...(option.color ? { color: option.color } : {})
+    })
+  })
+
+  return options
+}
+
+function validateDefault(errors, file, at, field, options) {
+  if (field.default === undefined) return
+
+  if (field.type === 'enum') {
+    if (typeof field.default !== 'string' || !options?.some((option) => option.value === field.default)) {
+      error(errors, file, at, 'enum 的默认值必须是 options 里的某个 value')
+    }
+    return
+  }
+
+  if (field.type === 'number') {
+    if (typeof field.default !== 'number' || !Number.isFinite(field.default)) {
+      error(errors, file, at, 'number 默认值必须是数字')
+    }
+    return
+  }
+
+  if (field.type === 'boolean') {
+    if (typeof field.default !== 'boolean') {
+      error(errors, file, at, 'boolean 默认值必须是 true 或 false')
+    }
+    return
+  }
+
+  if (typeof field.default !== 'string') {
+    error(errors, file, at, `${field.type} 默认值必须是字符串`)
+  }
+}

package/tha/config/load.mjs

@@ -0,0 +1,188 @@
+import path from 'node:path'
+import { ts } from '../utils/ts.mjs'
+import { exists, listDirectories, read, relativePath } from '../utils/files.mjs'
+import { absPath } from './paths.mjs'
+
+export function loadConfigs(root, dirs) {
+  const domainsDir = absPath(root, dirs, 'domains')
+  const configs = []
+  const errors = []
+
+  for (const dirName of listDirectories(domainsDir)) {
+    const file = path.join(domainsDir, dirName, 'config.ts')
+    if (!exists(file)) continue
+
+    const relativeFile = relativePath(root, file)
+
+    try {
+      const parsed = parseConfigFile(file)
+      configs.push({
+        ...parsed,
+        file,
+        relativeFile,
+        dirName
+      })
+    } catch (error) {
+      errors.push({
+        file: relativeFile,
+        path: '',
+        message: error instanceof Error ? error.message : String(error)
+      })
+    }
+  }
+
+  return { configs, errors }
+}
+
+export function parseConfigFile(file) {
+  const text = read(file)
+  const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+
+  assertTypeOnlyImports(sourceFile)
+
+  const candidates = []
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+
+    for (const declaration of statement.declarationList.declarations) {
+      if (!declaration.initializer) continue
+
+      const initializer = unwrap(declaration.initializer)
+      if (!ts.isObjectLiteralExpression(initializer)) continue
+      if (!hasProperty(initializer, 'name')) continue
+
+      candidates.push({
+        node: initializer,
+        exportName: declaration.name.getText(sourceFile)
+      })
+    }
+  }
+
+  if (candidates.length === 0) {
+    throw new Error('没有找到配置对象：请写 export const <模块>Config = { ... }')
+  }
+
+  if (candidates.length > 1) {
+    throw new Error('找到多个带 name 的配置对象，只能有一个模块配置')
+  }
+
+  const candidate = candidates[0]
+  const value = readLiteral(candidate.node, sourceFile)
+
+  return {
+    value,
+    exportName: candidate.exportName
+  }
+}
+
+function assertTypeOnlyImports(sourceFile) {
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue
+
+    const clause = statement.importClause
+    if (!clause) {
+      throw new Error('config 只能写 import type，不能执行其他代码')
+    }
+    if (clause.isTypeOnly) continue
+
+    const bindings = clause.namedBindings
+    if (bindings && ts.isNamedImports(bindings) && bindings.elements.every((element) => element.isTypeOnly)) {
+      continue
+    }
+
+    throw new Error('config 只能写 import type，不能写运行时 import')
+  }
+}
+
+function unwrap(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
+}
+
+function hasProperty(node, name) {
+  return node.properties.some((property) => {
+    if (!ts.isPropertyAssignment(property)) return false
+    return propertyName(property.name) === name
+  })
+}
+
+function propertyName(name) {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+    return name.text
+  }
+  return null
+}
+
+function readLiteral(node, sourceFile) {
+  if (ts.isObjectLiteralExpression(node)) {
+    const object = {}
+    const seen = new Set()
+
+    for (const property of node.properties) {
+      if (!ts.isPropertyAssignment(property)) {
+        throw at(node, sourceFile, '只能直接写 key: value，不能用 spread、方法或简写')
+      }
+
+      const key = propertyName(property.name)
+      if (!key) {
+        throw at(property.name, sourceFile, '不允许计算属性名')
+      }
+      if (seen.has(key)) {
+        throw at(property.name, sourceFile, `重复的键：${key}`)
+      }
+      seen.add(key)
+
+      object[key] = readLiteral(property.initializer, sourceFile)
+    }
+
+    return object
+  }
+
+  if (ts.isArrayLiteralExpression(node)) {
+    return node.elements.map((element) => {
+      if (ts.isSpreadElement(element) || ts.isOmittedExpression(element)) {
+        throw at(element, sourceFile, '数组里不允许 spread 或空位')
+      }
+      return readLiteral(element, sourceFile)
+    })
+  }
+
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text
+  }
+
+  if (ts.isNumericLiteral(node)) {
+    return Number(node.text)
+  }
+
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false
+
+  if (
+    ts.isPrefixUnaryExpression(node) &&
+    node.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(node.operand)
+  ) {
+    return -Number(node.operand.text)
+  }
+
+  throw at(node, sourceFile, `只能直接写值，不能写 ${ts.SyntaxKind[node.kind]}；也不能引用变量或调用函数`)
+}
+
+function at(node, sourceFile, message) {
+  const position = node.getStart(sourceFile)
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(position)
+  return new Error(`第 ${line + 1} 行第 ${character + 1} 列：${message}`)
+}

package/tha/config/manifest.mjs

@@ -0,0 +1,75 @@
+// ============ 交接清单：哪些生成位改由人维护 ============
+// adopt 的语义只有一个：这个文件不再由 CLI 生成，但仍然在架构里、照常被护栏检查。
+// 工具放弃「写」，不放弃「管」——否则手写文件只能变成永久 conflict。
+
+import path from 'node:path'
+import { exists, read, toPosix, writeAtomic } from '../utils/files.mjs'
+
+const MANIFEST = '.tha/manifest.json'
+
+/**
+ * 读取交接清单
+ * @param root 项目根目录
+ * @returns { version, manual: string[] }（manual 为相对路径，posix 分隔）
+ */
+export function loadManifest(root) {
+  const file = path.join(root, MANIFEST)
+  if (!exists(file)) return { version: 1, manual: [] }
+
+  try {
+    const parsed = JSON.parse(read(file))
+    return {
+      version: 1,
+      manual: Array.isArray(parsed.manual) ? parsed.manual.map((entry) => toPosix(entry)) : []
+    }
+  } catch {
+    return { version: 1, manual: [] }
+  }
+}
+
+/**
+ * 交接清单里的路径集合（比较用）
+ * @param root 项目根目录
+ * @returns Set<string>
+ */
+export function manualPaths(root) {
+  return new Set(loadManifest(root).manual)
+}
+
+/**
+ * 把文件记入交接清单
+ * @param root  项目根目录
+ * @param paths 相对路径列表（posix）
+ * @returns 新增的路径
+ */
+export function adoptFiles(root, paths) {
+  const manifest = loadManifest(root)
+  const existing = new Set(manifest.manual)
+  const added = paths.map((entry) => toPosix(entry)).filter((entry) => !existing.has(entry))
+
+  save(root, [...existing, ...added])
+  return added
+}
+
+/**
+ * 从交接清单移除（交回生成管理）
+ * @param root  项目根目录
+ * @param paths 相对路径列表（posix）
+ * @returns 实际移除的路径
+ */
+export function releaseFiles(root, paths) {
+  const manifest = loadManifest(root)
+  const wanted = new Set(paths.map((entry) => toPosix(entry)))
+  const removed = manifest.manual.filter((entry) => wanted.has(entry))
+
+  save(
+    root,
+    manifest.manual.filter((entry) => !wanted.has(entry))
+  )
+  return removed
+}
+
+function save(root, manual) {
+  const file = path.join(root, MANIFEST)
+  writeAtomic(file, `${JSON.stringify({ version: 1, manual: [...manual].sort() }, null, 2)}\n`)
+}

package/tha/config/paths.mjs

@@ -0,0 +1,124 @@
+// ============ 目录映射：一处定义，所有模板与检查器共用 ============
+// 默认值与约定一致（src/domains、src/views …）。
+// 项目根放一个 tha.config.json 就能整体搬走，CLI 不再写死任何目录名。
+
+import path from 'node:path'
+import { exists, read } from '../utils/files.mjs'
+
+export const DIR_KEYS = [
+  'domains',
+  'views',
+  'stores',
+  'api',
+  'router',
+  'layouts',
+  'components',
+  'utils'
+]
+
+export const DEFAULT_DIRS = Object.freeze({
+  domains: 'src/domains',
+  views: 'src/views',
+  stores: 'src/stores',
+  api: 'src/api',
+  router: 'src/router',
+  layouts: 'src/layouts',
+  components: 'src/components',
+  utils: 'src/utils'
+})
+
+const CONFIG_FILE = 'tha.config.json'
+const SAFE_PATH = /^[a-zA-Z0-9_.-]+(?:[a-zA-Z0-9_.-]*[a-zA-Z0-9_.-])?(?:\/[a-zA-Z0-9_.-]+)*$/
+
+/**
+ * 读取目录映射
+ * @param root 项目根目录
+ * @returns { dirs, errors, configured } —— configured 表示项目里确实有这个文件
+ */
+export function loadDirs(root) {
+  const file = path.join(root, CONFIG_FILE)
+  const errors = []
+
+  if (!exists(file)) return { dirs: { ...DEFAULT_DIRS }, errors, configured: false }
+
+  let raw
+  try {
+    raw = JSON.parse(read(file))
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    errors.push({ file: CONFIG_FILE, path: '', message: `不是合法 JSON：${message}` })
+    return { dirs: { ...DEFAULT_DIRS }, errors, configured: true }
+  }
+
+  if (!isPlainObject(raw)) {
+    errors.push({ file: CONFIG_FILE, path: '', message: '必须是对象，例如 { "dirs": { "views": "src/pages" } }' })
+    return { dirs: { ...DEFAULT_DIRS }, errors, configured: true }
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (key !== 'dirs') {
+      errors.push({ file: CONFIG_FILE, path: key, message: '不认识的配置项；只支持 dirs' })
+    }
+  }
+
+  const dirs = { ...DEFAULT_DIRS }
+  const value = raw.dirs
+
+  if (value === undefined) return { dirs, errors, configured: true }
+
+  if (!isPlainObject(value)) {
+    errors.push({ file: CONFIG_FILE, path: 'dirs', message: '必须是对象，例如 { "views": "src/pages" }' })
+    return { dirs, errors, configured: true }
+  }
+
+  for (const key of Object.keys(value)) {
+    const at = `dirs.${key}`
+    if (!DIR_KEYS.includes(key)) {
+      errors.push({ file: CONFIG_FILE, path: at, message: `不认识的目录键；可用：${DIR_KEYS.join('、')}` })
+      continue
+    }
+    const dirValue = value[key]
+    if (typeof dirValue !== 'string' || !dirValue.trim()) {
+      errors.push({ file: CONFIG_FILE, path: at, message: '必须是非空字符串，例如 "src/pages"' })
+      continue
+    }
+    const normalized = dirValue.trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '')
+    if (!SAFE_PATH.test(normalized) || normalized.split('/').some((part) => part === '..' || part === '.')) {
+      errors.push({ file: CONFIG_FILE, path: at, message: '必须是项目内的相对路径，不能写绝对路径或 ..' })
+      continue
+    }
+    dirs[key] = normalized
+  }
+
+  return { dirs, errors, configured: true }
+}
+
+/**
+ * 相对项目根的路径
+ * @returns 例如 src/views/doc/Index.vue
+ */
+export function relPath(dirs, key, ...rest) {
+  return [dirs[key], ...rest].filter(Boolean).join('/')
+}
+
+/**
+ * 绝对路径
+ */
+export function absPath(root, dirs, key, ...rest) {
+  return path.join(root, relPath(dirs, key, ...rest))
+}
+
+/**
+ * 生成代码里的 import 路径（@ 是项目源码别名）
+ * @returns 例如 @/views/doc/Index.vue
+ */
+export function importSpec(dirs, key, ...rest) {
+  const base = dirs[key].startsWith('src/') ? dirs[key].slice('src/'.length) : dirs[key]
+  return ['@', base, ...rest].filter(Boolean).join('/')
+}
+
+export { CONFIG_FILE }
+
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}

package/tha/config/project.mjs

@@ -0,0 +1,52 @@
+// ============ 项目装载：config 驱动模块 + 手写模块 ============
+// 两件事分开：domains 是「构造机管的」，manual 是「人写的但仍在架构里」。
+// 后者不参与生成与漂移比较，但一样要过契约与护栏检查。
+
+import { loadConfigs } from './load.mjs'
+import { validateProject } from './schema.mjs'
+import { loadDirs, absPath, relPath } from './paths.mjs'
+import { exists } from '../utils/files.mjs'
+import { scanManualModules } from '../verify/scan.mjs'
+
+export function loadProject(root) {
+  // 目录映射先读：所有路径推导都依赖它，读错就全错
+  const { dirs, errors: dirErrors } = loadDirs(root)
+
+  if (dirErrors.length > 0) {
+    return { domains: [], manual: [], errors: dirErrors, dirs }
+  }
+
+  const domainsDir = absPath(root, dirs, 'domains')
+
+  // 目录本身不存在 = 项目还没初始化；目录存在但没有 config = 合法的空项目（删光模块后 sync 仍要能跑）
+  if (!exists(domainsDir)) {
+    return {
+      domains: [],
+      manual: [],
+      errors: [
+        {
+          file: relPath(dirs, 'domains'),
+          path: '',
+          message: `没有 ${relPath(dirs, 'domains')} 目录：先运行 tha init <模块>`
+        }
+      ],
+      dirs
+    }
+  }
+
+  const { configs, errors: parseErrors } = loadConfigs(root, dirs)
+  const manual = scanManualModules(root, new Set(configs.map((config) => config.dirName)), dirs)
+
+  if (configs.length === 0) {
+    return { domains: [], manual, errors: parseErrors, dirs }
+  }
+
+  const result = validateProject(configs)
+
+  return {
+    domains: result.domains,
+    manual,
+    errors: [...parseErrors, ...result.errors],
+    dirs
+  }
+}

package/tha/config/rules.mjs

@@ -0,0 +1,85 @@
+// 小写字母开头，允许小驼峰（提示文案里一直写着支持 userProfile，正则必须跟上）
+export const NAME_RE = /^[a-z][a-zA-Z0-9]*$/
+export const PATH_RE = /^\/(?:[a-zA-Z0-9_-]+)(?:\/[a-zA-Z0-9_-]+)*$/
+export const API_RE = /^\/(?:[a-zA-Z0-9_-]+)(?:\/[a-zA-Z0-9_-]+)*$/
+
+export const FIELD_TYPES = new Set([
+  'string',
+  'text',
+  'number',
+  'boolean',
+  'enum',
+  'date',
+  'datetime'
+])
+
+export const SEARCH_TYPES = new Set(['string', 'enum', 'number', 'date', 'datetime'])
+export const ENUM_COLORS = new Set(['gray', 'ok', 'warn', 'red', 'blue'])
+
+export const TOP_KEYS = new Set([
+  'name',
+  'title',
+  'path',
+  'api',
+  'fields',
+  'list',
+  'crud',
+  'permissions',
+  'pages'
+])
+
+// api 只认两个键：接口地址 + 可选的后端契约文件（OpenAPI）
+export const API_KEYS = new Set(['base', 'contract'])
+
+// 页面模板：list 必生成，detail / form 按需开启
+export const PAGE_NAMES = new Set(['list', 'detail', 'form'])
+export const DEFAULT_PAGES = ['list', 'detail']
+
+export const FIELD_KEYS = new Set([
+  'label',
+  'type',
+  'required',
+  'list',
+  'form',
+  'search',
+  'readonly',
+  'options',
+  'default'
+])
+
+export const OPTION_KEYS = new Set(['label', 'value', 'color'])
+export const LIST_KEYS = new Set(['pageSize', 'orderBy', 'order'])
+
+// 只有这几种类型能用来排序：布尔、枚举排出来没有业务含义
+export const SORT_TYPES = new Set(['string', 'text', 'number', 'date', 'datetime'])
+export const CRUD_KEYS = new Set(['create', 'update', 'remove'])
+export const PERMISSION_KEYS = new Set(['view', 'create', 'update', 'remove'])
+
+export const RESERVED_NAMES = new Set([
+  'api',
+  'stores',
+  'domains',
+  'views',
+  'router',
+  'layouts',
+  'components',
+  'utils',
+  'composables'
+])
+
+export function normalizeUrlPath(value, fallback) {
+  let result = String(value ?? fallback ?? '').trim()
+  if (!result) result = String(fallback ?? '').trim()
+  if (!result) return ''
+  if (!result.startsWith('/')) result = `/${result}`
+  result = result.replace(/\/+$/, '')
+  return result
+}
+
+export function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}
+
+export function error(errors, file, at, message) {
+  errors.push({ file, path: at, message })
+}