moluoxixi-ai-rules 0.1.0

package/skills/workflow/frontend-code-standard/scripts/verify-rules.mjs

@@ -0,0 +1,537 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const PUBLIC_ENTRY_FILENAMES = ['index.ts']
+const STYLE_ENTRY_FILENAMES = ['index.css', 'index.scss', 'index.less']
+const COMPONENT_IMPLEMENTATION_FILENAMES = ['index.vue', 'index.tsx']
+const MODULE_IMPLEMENTATION_FILENAMES = ['index.vue', 'index.tsx']
+const HOST_FRAMEWORK_DEPENDENCIES = ['vue', 'react', 'react-dom']
+const MAX_DEPTH = 10
+const IGNORED_DIRECTORIES = [
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  'generated',
+  '.nuxt',
+  '.output',
+  '.next',
+  '.turbo',
+  '__test__',
+  '__mocks__',
+  '__fixtures__',
+  '__snapshots__',
+  '__demos__',
+  '__stories__',
+  '__e2e__',
+  'assets',
+  'images',
+  'icons',
+  'fonts',
+  'styles',
+  'public',
+]
+
+function readSkillFile(...segments) {
+  return fs.readFileSync(path.join(skillRoot, ...segments), 'utf8')
+}
+
+function assertContains(content, pattern, message) {
+  if (!pattern.test(content))
+    throw new Error(message)
+}
+
+function findExistingFiles(directory, filenames) {
+  return filenames.filter(filename => fs.existsSync(path.join(directory, filename)))
+}
+
+function relativeDirectory(root, directory) {
+  const relative = path.relative(root, directory)
+
+  return relative === '' ? '.' : relative.split(path.sep).join('/')
+}
+
+function assertSingleExistingFile(directory, filenames, label) {
+  const existingFiles = findExistingFiles(directory, filenames)
+
+  if (existingFiles.length === 0)
+    throw new Error(`${label} 缺少唯一入口：${filenames.join('、')}`)
+
+  if (existingFiles.length > 1)
+    throw new Error(`${label} 只能存在一个入口：${filenames.join('、')}`)
+
+  return existingFiles[0]
+}
+
+function assertExplicitValueExports(filePath, label) {
+  const content = fs.readFileSync(filePath, 'utf8')
+  const wildcardExportLine = content
+    .split('\n')
+    .map(line => line.trimStart())
+    .find(line => line.startsWith('export *'))
+
+  if (wildcardExportLine)
+    throw new Error(`${label} 严禁使用 value wildcard export，请改为显式命名导出或 export type *`)
+}
+
+function assertEntryContract(directory, entryFilename, label) {
+  assertExplicitValueExports(path.join(directory, entryFilename), label)
+}
+
+// 组件包的类型门面属于公共 API 契约，必须由根入口显式暴露。
+function assertComponentTypeFacade(componentRoot, srcPath) {
+  const typesPath = path.join(srcPath, 'types')
+
+  if (!fs.existsSync(typesPath) || !fs.statSync(typesPath).isDirectory())
+    throw new Error('组件包缺少 src/types/ 类型契约目录')
+
+  const typeEntry = assertSingleExistingFile(typesPath, PUBLIC_ENTRY_FILENAMES, '组件包 src/types 类型门面')
+  const rootEntryContent = fs.readFileSync(path.join(componentRoot, 'index.ts'), 'utf8')
+
+  assertEntryContract(typesPath, typeEntry, '组件包 src/types 类型门面')
+
+  if (!rootEntryContent.includes('export type') || !rootEntryContent.includes('./src/types'))
+    throw new Error('组件包根目录 index.ts 必须通过 export type * from \'./src/types\' 暴露类型契约')
+
+  return typeEntry
+}
+
+function readPackageJson(directory, label) {
+  const packagePath = path.join(directory, 'package.json')
+
+  if (!fs.existsSync(packagePath))
+    throw new Error(`${label} 缺少 package.json`)
+
+  return JSON.parse(fs.readFileSync(packagePath, 'utf8'))
+}
+
+function assertHostFrameworkDepsInPeerDependencies(packageJson, label) {
+  const dependencies = packageJson.dependencies ?? {}
+
+  for (const dependencyName of HOST_FRAMEWORK_DEPENDENCIES) {
+    if (Object.hasOwn(dependencies, dependencyName))
+      throw new Error(`${label} 宿主框架依赖 ${dependencyName} 必须放在 peerDependencies 中`)
+  }
+}
+
+function printPass(message, details = {}) {
+  console.log(`PASS ${message}`)
+
+  for (const [key, value] of Object.entries(details))
+    console.log(`${key}: ${value}`)
+}
+
+function getOption(args, name) {
+  const index = args.indexOf(name)
+
+  if (index === -1)
+    throw new Error(`缺少参数 ${name}`)
+
+  const value = args[index + 1]
+
+  if (!value || value.startsWith('--'))
+    throw new Error(`参数 ${name} 必须提供值`)
+
+  return value
+}
+
+function getListAfter(args, name, options = {}) {
+  const index = args.indexOf(name)
+
+  if (index === -1)
+    throw new Error(`缺少参数 ${name}`)
+
+  const values = args.slice(index + 1).filter(value => !value.startsWith('--'))
+
+  if (values.length === 2 && options.allowStableTwoUse)
+    return values
+
+  if (values.length < 3)
+    throw new Error(`${name} 至少需要 3 个明确使用点；仅 2 个使用点时必须显式传入 --stable-two-use，表示这是复杂且稳定的拆分例外`)
+
+  return values
+}
+
+function pathLooksLikeFile(inputPath) {
+  return path.extname(inputPath) !== ''
+}
+
+function normalizeDirectory(inputPath) {
+  const resolved = path.resolve(process.cwd(), inputPath)
+
+  return pathLooksLikeFile(resolved) ? path.dirname(resolved) : resolved
+}
+
+function nearestCommonAncestor(paths) {
+  const partsList = paths.map(inputPath => normalizeDirectory(inputPath).split(path.sep))
+  const [firstParts] = partsList
+  const commonParts = []
+
+  for (const [index, part] of firstParts.entries()) {
+    if (!partsList.every(parts => parts[index] === part))
+      break
+
+    commonParts.push(part)
+  }
+
+  if (commonParts.length === 0)
+    throw new Error('无法计算共享边界，请确认使用点路径属于同一文件系统根')
+
+  return commonParts.join(path.sep)
+}
+
+function assertTargetInsideAncestor(target, ancestor, uses) {
+  const resolvedTarget = path.resolve(process.cwd(), target)
+  const relative = path.relative(ancestor, resolvedTarget)
+
+  if (relative.startsWith('..') || path.isAbsolute(relative))
+    throw new Error(`抽离目标必须位于共享边界内：${ancestor}`)
+
+  if (relative === '')
+    return
+
+  const directSegments = relative.split(path.sep).filter(Boolean)
+
+  if (uses.some((usePath) => {
+    const useRelative = path.relative(ancestor, normalizeDirectory(usePath))
+    const [firstSegment] = useRelative.split(path.sep).filter(Boolean)
+
+    return firstSegment === directSegments[0]
+  })) {
+    throw new Error(`抽离目标必须位于允许的共享边界目录：${ancestor}`)
+  }
+
+  if (directSegments.length === 1)
+    return
+
+  throw new Error(`抽离目标必须位于允许的共享边界目录：${ancestor}`)
+}
+
+function assertCodeDirectoryEntries(directory, root, options = {}, depth = 0) {
+  if (depth > MAX_DEPTH)
+    throw new Error(`目录深度超过 ${MAX_DEPTH} 层，可能存在循环引用或目录结构异常`)
+
+  const entries = fs.readdirSync(directory, { withFileTypes: true })
+  const parentHasPublicEntry = findExistingFiles(directory, PUBLIC_ENTRY_FILENAMES).length > 0
+  const implementationEntries = options.implementationEntries ?? COMPONENT_IMPLEMENTATION_FILENAMES
+
+  for (const entry of entries) {
+    if (!entry.isDirectory())
+      continue
+
+    if (IGNORED_DIRECTORIES.includes(entry.name))
+      continue
+
+    const childDirectory = path.join(directory, entry.name)
+    const relative = relativeDirectory(root, childDirectory)
+    const childPublicEntries = findExistingFiles(childDirectory, PUBLIC_ENTRY_FILENAMES)
+    const childImplementationEntries = findExistingFiles(childDirectory, implementationEntries)
+    const isImplementationSrc = entry.name === 'src' && parentHasPublicEntry && childImplementationEntries.length === 1
+
+    if (!isImplementationSrc) {
+      const childEntry = assertSingleExistingFile(childDirectory, PUBLIC_ENTRY_FILENAMES, `目录 ${relative}/ 聚合入口`)
+      assertEntryContract(childDirectory, childEntry, `目录 ${relative}/ 聚合入口`)
+    }
+
+    if (childPublicEntries.length > 0 || isImplementationSrc || options.descendIntoMissingEntryDirectory)
+      assertCodeDirectoryEntries(childDirectory, root, options, depth + 1)
+  }
+}
+
+function assertComponentPackage(root, options = {}) {
+  const componentRoot = path.resolve(process.cwd(), root)
+  const readmePath = path.join(componentRoot, 'README.md')
+  const srcPath = path.join(componentRoot, 'src')
+  const publicEntry = assertSingleExistingFile(componentRoot, PUBLIC_ENTRY_FILENAMES, '复杂组件包根目录公共入口')
+  const rootImplementationEntries = findExistingFiles(componentRoot, COMPONENT_IMPLEMENTATION_FILENAMES)
+  const requiresReadme = !options.privatePackage
+
+  assertEntryContract(componentRoot, publicEntry, '复杂组件包根目录公共入口')
+
+  if (requiresReadme && !fs.existsSync(readmePath))
+    throw new Error('独立公共组件包根目录缺少 README.md')
+
+  if (!fs.existsSync(srcPath) || !fs.statSync(srcPath).isDirectory())
+    throw new Error('复杂组件包根目录缺少 src/ 实现目录')
+
+  if (rootImplementationEntries.length > 0)
+    throw new Error(`复杂组件包根目录不得放置实现入口：${rootImplementationEntries.join('、')}`)
+
+  const srcImplementationEntry = assertSingleExistingFile(srcPath, COMPONENT_IMPLEMENTATION_FILENAMES, '复杂组件包 src/ 实现入口')
+  const typeEntry = assertComponentTypeFacade(componentRoot, srcPath)
+
+  if (fs.existsSync(readmePath)) {
+    const readme = fs.readFileSync(readmePath, 'utf8').trim()
+
+    if (readme.length === 0)
+      throw new Error('复杂组件 README.md 不得为空，必须描述组件如何使用')
+
+    if (!/(使用|用法|Usage|Props|Events|Emits|Expose|Slots|API|Ref|Children)/.test(readme))
+      throw new Error('复杂组件 README.md 必须包含使用方式或接口契约说明')
+  }
+
+  assertCodeDirectoryEntries(componentRoot, componentRoot, { implementationEntries: COMPONENT_IMPLEMENTATION_FILENAMES })
+
+  printPass(options.privatePackage ? 'frontend private complex component package structure is valid' : 'frontend complex component package structure is valid', {
+    componentRoot,
+    entry: publicEntry,
+    implementationEntry: srcImplementationEntry,
+    typeEntry,
+  })
+}
+
+function assertLibraryPackage(root, options = {}) {
+  const libraryRoot = path.resolve(process.cwd(), root)
+  const readmePath = path.join(libraryRoot, 'README.md')
+  const srcPath = path.join(libraryRoot, 'src')
+  const publicEntry = assertSingleExistingFile(libraryRoot, PUBLIC_ENTRY_FILENAMES, '库根目录公共入口')
+  const rootImplementationEntries = findExistingFiles(libraryRoot, COMPONENT_IMPLEMENTATION_FILENAMES)
+  const packageJson = readPackageJson(libraryRoot, '库根目录')
+
+  if (!fs.existsSync(readmePath))
+    throw new Error('库根目录缺少 README.md')
+
+  if (!fs.existsSync(srcPath) || !fs.statSync(srcPath).isDirectory())
+    throw new Error('库根目录缺少 src/ 实现目录')
+
+  if (rootImplementationEntries.length > 0)
+    throw new Error(`库根目录不得放置组件实现入口：${rootImplementationEntries.join('、')}`)
+
+  const srcEntry = assertSingleExistingFile(srcPath, PUBLIC_ENTRY_FILENAMES, '库 src/ 聚合入口')
+
+  assertEntryContract(libraryRoot, publicEntry, '库根目录公共入口')
+  assertEntryContract(srcPath, srcEntry, '库 src/ 聚合入口')
+  assertHostFrameworkDepsInPeerDependencies(packageJson, '库 package.json')
+
+  if (options.requireComponents) {
+    if (!Object.hasOwn(packageJson, 'sideEffects'))
+      throw new Error('UI 组件库 package.json 必须明确声明 sideEffects 范围')
+  }
+  else if (packageJson.sideEffects !== false) {
+    throw new Error('工具库 package.json 必须声明 "sideEffects": false')
+  }
+
+  const readme = fs.readFileSync(readmePath, 'utf8').trim()
+
+  if (readme.length === 0)
+    throw new Error('库 README.md 不得为空，必须描述库如何使用')
+
+  if (!/(使用|用法|Usage|API|Exports|组件|工具|安装|Install)/.test(readme))
+    throw new Error('库 README.md 必须包含使用方式或公开 API 说明')
+
+  if (options.requireComponents) {
+    const componentsPath = path.join(srcPath, 'components')
+
+    if (!fs.existsSync(componentsPath) || !fs.statSync(componentsPath).isDirectory())
+      throw new Error('UI 组件库缺少 src/components/ 组件目录')
+
+    const componentDirs = fs.readdirSync(componentsPath, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+
+    if (componentDirs.length === 0)
+      throw new Error('UI 组件库 src/components/ 下至少需要一个复杂组件包')
+
+    for (const componentDir of componentDirs)
+      assertComponentPackage(path.join(componentsPath, componentDir.name))
+  }
+
+  assertCodeDirectoryEntries(libraryRoot, libraryRoot, { implementationEntries: COMPONENT_IMPLEMENTATION_FILENAMES })
+
+  printPass(options.requireComponents ? 'frontend UI component library structure is valid' : 'frontend utility library structure is valid', {
+    libraryRoot,
+    entry: publicEntry,
+    srcEntry,
+  })
+}
+
+function assertModule(root) {
+  const moduleRoot = path.resolve(process.cwd(), root)
+  const srcPath = path.join(moduleRoot, 'src')
+  const implementationEntry = assertSingleExistingFile(moduleRoot, MODULE_IMPLEMENTATION_FILENAMES, '单个模块根目录实现入口')
+  const publicEntries = findExistingFiles(moduleRoot, PUBLIC_ENTRY_FILENAMES)
+
+  if (fs.existsSync(srcPath))
+    throw new Error('单个模块不得再嵌套 src/ 目录')
+
+  if (publicEntries.length > 0)
+    throw new Error(`单个模块根目录不得创建公共入口：${publicEntries.join('、')}`)
+
+  assertCodeDirectoryEntries(moduleRoot, moduleRoot, { implementationEntries: MODULE_IMPLEMENTATION_FILENAMES })
+
+  printPass('frontend module structure is valid', {
+    moduleRoot,
+    implementationEntry,
+  })
+}
+
+// 私有叶子例外只校验文件边界；源码级 API 识别应交给成熟 SFC/AST 工具。
+function assertPrivateLeafComponent(root) {
+  const componentPath = path.resolve(process.cwd(), root)
+  const filename = path.basename(componentPath)
+  const componentDirectory = path.dirname(componentPath)
+  const componentName = path.basename(filename, path.extname(filename))
+
+  if (!/^[A-Z][\w-]*\.(vue|tsx)$/.test(filename))
+    throw new Error('私有叶子组件例外必须使用 ComponentName.vue 或 ComponentName.tsx 文件')
+
+  if (!fs.existsSync(componentPath) || !fs.statSync(componentPath).isFile())
+    throw new Error('私有叶子组件例外路径必须指向真实文件')
+
+  for (const entry of fs.readdirSync(componentDirectory, { withFileTypes: true })) {
+    if (entry.name === filename)
+      continue
+
+    if (entry.isDirectory()) {
+      if (!['__test__', '__demos__', '__stories__'].includes(entry.name))
+        throw new Error(`私有叶子组件例外同级只允许 __test__、__demos__、__stories__ 目录；发现：${entry.name}，必须升级为 component-package`)
+
+      continue
+    }
+
+    const siblingExt = path.extname(entry.name)
+    const siblingBase = path.basename(entry.name, siblingExt)
+    const isSameNameStyle = siblingBase === componentName && STYLE_ENTRY_FILENAMES.includes(`index${siblingExt}`)
+    const isAnotherSimpleComponent = /^[A-Z][\w-]*\.(vue|tsx)$/.test(entry.name)
+    const isDedicatedCodeFile = /\.(ts|js|vue|tsx|jsx)$/.test(entry.name)
+
+    if (!isSameNameStyle && !isAnotherSimpleComponent && isDedicatedCodeFile)
+      throw new Error(`私有叶子组件例外同级存在专属附属文件：${entry.name}，必须升级为 component-package`)
+  }
+
+  printPass('frontend private leaf component exception is valid', {
+    componentPath,
+  })
+}
+
+function printHelp() {
+  console.log(`用法: node verify-rules.mjs [command] [options]
+
+命令:
+  self                        校验本 skill 的规则完整性（默认）
+  leaf, private-leaf          校验私有叶子组件例外
+  component, package          校验复杂组件包结构
+  module                      校验业务模块结构
+  utility, tool-library       校验工具库结构
+  ui-library, component-library  校验 UI 组件库结构
+  hoist                       校验公共代码抽离位置是否落在允许的共享边界内
+  --help                      显示帮助信息
+
+选项:
+  --root <path>               指定组件、模块或库根目录
+  --private                   将复杂组件包按模块或组件内部私有子组件校验，README.md 不强制
+  --target <path>             指定抽离目标目录
+  --uses <path1> <path2> ...  指定至少 3 个使用点路径
+  --stable-two-use            仅 2 个使用点时，声明这是复杂且稳定的拆分例外
+`)
+}
+
+function verifySelf() {
+  const skill = readSkillFile('SKILL.md')
+
+  assertContains(skill, /frontend-code-standard/, 'SKILL.md 必须声明 skill 名称')
+  assertContains(skill, /触发时机：当用户要求新建、编写、重构、拆分前端组件、业务模块、工具函数或类型声明时触发/, 'SKILL.md 必须声明用户指定的触发时机')
+  assertContains(skill, /目录门面模式（Facade）、禁止深度导入、规范 src\/ 隔离边界、强制同步交付测试用例，并应用 Vue 3\.5\+ 现代语法/, 'SKILL.md 必须说明规则覆盖范围')
+  assertContains(skill, /前端工程架构与代码规范/, 'SKILL.md 必须使用前端工程架构规范标题')
+  assertContains(skill, /适用边界/, 'SKILL.md 必须覆盖适用边界')
+  assertContains(skill, /项目事实优先/, 'SKILL.md 必须声明项目事实优先')
+  assertContains(skill, /Vue 3\.5\+ 约束范围/, 'SKILL.md 必须声明 Vue 3.5+ 约束范围')
+  assertContains(skill, /业务路由模块例外/, 'SKILL.md 必须覆盖业务路由模块例外')
+  assertContains(skill, /严禁为了制造层级再包一层 `src\/`/, 'SKILL.md 必须禁止路由模块无意义 src 层')
+  assertContains(skill, /门面模式与统一入口/, 'SKILL.md 必须覆盖门面模式')
+  assertContains(skill, /职责目录下必须存在 `index\.ts`/, 'SKILL.md 必须覆盖职责目录统一入口')
+  assertContains(skill, /禁止深度导入/, 'SKILL.md 必须覆盖禁止深度导入')
+  assertContains(skill, /import \{ format \} from '@\/utils\/string\/format'/, 'SKILL.md 必须包含 Deep Import 反例')
+  assertContains(skill, /import \{ format \} from '@\/utils'/, 'SKILL.md 必须包含门面导入示例')
+  assertContains(skill, /同一职责目录内部允许通过相对路径引用私有实现文件/, 'SKILL.md 必须覆盖内部私有实现导入')
+  assertContains(skill, /export type \* from '\.\/xxx'/, 'SKILL.md 必须覆盖类型聚合')
+  assertContains(skill, /禁止用无差别 `export \*` 暴露内部实现/, 'SKILL.md 必须覆盖值导出约束')
+  assertContains(skill, /门面例外/, 'SKILL.md 必须覆盖门面例外')
+  assertContains(skill, /独立模块与组件目录骨架/, 'SKILL.md 必须覆盖独立模块骨架')
+  assertContains(skill, /公共契约层（根目录）/, 'SKILL.md 必须覆盖公共契约层')
+  assertContains(skill, /对外生产 API 只能通过唯一的根 `index\.ts` 暴露/, 'SKILL.md 必须覆盖根入口唯一出口')
+  assertContains(skill, /私有实现层 \(`src\/`\)/, 'SKILL.md 必须覆盖 src 私有实现层')
+  assertContains(skill, /所有具体逻辑、组件、样式代码必须收敛在 `src\/` 内部/, 'SKILL.md 必须覆盖 src 隔离边界')
+  assertContains(skill, /类型契约层/, 'SKILL.md 必须覆盖类型契约层')
+  assertContains(skill, /export type \* from '\.\/src\/types'/, 'SKILL.md 必须覆盖根类型门面导出')
+  assertContains(skill, /越界调用拦截/, 'SKILL.md 必须覆盖越界调用拦截')
+  assertContains(skill, /绝对禁止任何直接读取其 `src\/` 内部文件的行为/, 'SKILL.md 必须禁止外部读取 src')
+  assertContains(skill, /私有叶子例外/, 'SKILL.md 必须覆盖私有叶子例外')
+  assertContains(skill, /必须立即升级为独立目录骨架/, 'SKILL.md 必须覆盖叶子组件升级条件')
+  assertContains(skill, /强制测试交付要求/, 'SKILL.md 必须覆盖测试交付')
+  assertContains(skill, /不得留作后续任务/, 'SKILL.md 必须禁止测试延期')
+  assertContains(skill, /验证状态必须标记为 `MISSING`/, 'SKILL.md 必须覆盖缺失验证入口状态')
+  assertContains(skill, /同级的 `__test__\/` 目录/, 'SKILL.md 必须覆盖就近测试目录')
+  assertContains(skill, /项目根级 `__e2e__\/`/, 'SKILL.md 必须覆盖全局 E2E 目录')
+  assertContains(skill, /Vitest/, 'SKILL.md 必须覆盖 Vitest')
+  assertContains(skill, /Playwright/, 'SKILL.md 必须覆盖 Playwright')
+  assertContains(skill, /禁止占位断言/, 'SKILL.md 必须覆盖禁止占位断言')
+  assertContains(skill, /Props、Events\/Emits、Slots\/Children、Model、Expose\/Ref/, 'SKILL.md 必须覆盖实际契约测试边界')
+  assertContains(skill, /现代 Vue 语法强制红线/, 'SKILL.md 必须覆盖现代 Vue 语法红线')
+  assertContains(skill, /defineModel/, 'SKILL.md 必须覆盖 defineModel')
+  assertContains(skill, /emit\('update:xxx'\)/, 'SKILL.md 必须覆盖旧式 model 写法禁令')
+  assertContains(skill, /非 model 事件仍使用 `defineEmits`/, 'SKILL.md 必须保留非 model 事件语义')
+  assertContains(skill, /useTemplateRef/, 'SKILL.md 必须覆盖 useTemplateRef')
+  assertContains(skill, /defineProps/, 'SKILL.md 必须覆盖 defineProps')
+  assertContains(skill, /withDefaults/, 'SKILL.md 必须覆盖 withDefaults')
+  assertContains(skill, /交付状态/, 'SKILL.md 必须覆盖交付状态')
+  assertContains(skill, /按任务风险执行项目已有的 `lint`、`typecheck`、`test`、`build` 或浏览器验证/, 'SKILL.md 必须覆盖验证命令范围')
+  assertContains(skill, /FAIL > MISSING > NOT RUN > PASS/, 'SKILL.md 必须覆盖最终状态优先级')
+  printPass('frontend-code-standard self rules are valid')
+}
+
+function verifyHoist(args) {
+  const target = getOption(args, '--target')
+  const uses = getListAfter(args, '--uses', {
+    allowStableTwoUse: args.includes('--stable-two-use'),
+  })
+  const ancestor = nearestCommonAncestor(uses)
+
+  assertTargetInsideAncestor(target, ancestor, uses)
+
+  printPass('frontend hoist target stays within shared boundary', {
+    sharedBoundary: ancestor,
+    target: path.resolve(process.cwd(), target),
+  })
+}
+
+function main() {
+  const [command = 'self', ...args] = process.argv.slice(2)
+
+  if (command === '--help' || command === '-h')
+    return printHelp()
+
+  if (command === 'self')
+    return verifySelf()
+
+  if (command === 'leaf' || command === 'private-leaf')
+    return assertPrivateLeafComponent(getOption(args, '--root'))
+
+  if (command === 'component' || command === 'package' || command === 'project')
+    return assertComponentPackage(getOption(args, '--root'), { privatePackage: args.includes('--private') })
+
+  if (command === 'module')
+    return assertModule(getOption(args, '--root'))
+
+  if (command === 'utility' || command === 'tool-library')
+    return assertLibraryPackage(getOption(args, '--root'))
+
+  if (command === 'ui-library' || command === 'component-library')
+    return assertLibraryPackage(getOption(args, '--root'), { requireComponents: true })
+
+  if (command === 'hoist')
+    return verifyHoist(args)
+
+  throw new Error(`未知命令：${command}，使用 --help 查看帮助`)
+}
+
+try {
+  main()
+}
+catch (error) {
+  console.error(`FAIL ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}

package/skills/workflow/java-code-standard/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: java-code-standard
+description: 触发时机：当用户要求新建、编写、重构、拆分、优化、评审或校验 Java/Spring Boot 后端代码时触发。
+---
+
+# Java & Spring Boot 工程架构与代码规范
+
+在执行 Java 后端代码生成、重构或评审任务时，必须在当前任务目标与改动范围内严格遵守以下物理边界与编码红线。本文件是唯一规则源，绝不为了兼容目标范围内的历史旧代码而保留过渡层或伪分层。
+
+## 一、核心架构与设计纪律
+
+- **依赖倒置**：`domain` 位于最核心，完全独立。严禁 `domain` 依赖 `infrastructure`、`org.springframework`、`jakarta.persistence`、Servlet、Jackson 或任何技术细节。若现有项目将 JPA Entity、ORM 注解或持久化代理放入 `domain`，必须在当前任务范围内拆分领域模型与持久化实体。
+- **高内聚与反垃圾桶**：类与文件必须保持职责内聚。辅助逻辑（Helper/Mapper）必须就近留在 feature 包内；绝对禁止设立无业务语义的全局 `utils` 目录。
+- **不可变与时间契约**：对外暴露集合时强制使用不可变视图（如 `List.copyOf()` 或 `Collections.unmodifiableList()`）。全局禁用 `java.util.Date`、`Calendar` 与 `java.sql.Timestamp`，强制使用 `java.time` 包下的现代 API（如 `Instant`, `OffsetDateTime`）。
+- **显式 DTO**：API 边界与用例交互必须使用显式 DTO（优先使用 `record`），严禁使用 `Map`、裸 `JSON` 或 `Object` 作为载体。
+
+## 二、Spring Boot 框架强制约束
+
+- **依赖注入**：全局禁用 `@Autowired` 字段注入。所有依赖必须显式声明为 `final` 并通过构造器注入。
+- **校验前置 (Fail-Fast)**：Controller 层的复杂 DTO、集合或入参，必须显式标注 `@Valid` 或 `@Validated`。嵌套 DTO 必须在父级字段标注以触发级联。进入 Application/Domain 层后，禁止重复编写基础防御逻辑（如空值、正则校验或 `.trim()`）。
+- **事务红线 (Transaction Boundaries)**：
+  - **严禁自调用**：绝对禁止 `this.xxx()` 形式的内部事务方法调用，也禁止使用 `AopContext.currentProxy()` 绕过代理。拆分事务必须提取独立 Service 并通过注入调用。
+  - **读写分离标记**：涉及 Repository、EntityManager 或持久化上下文的查询类用例，必须显式标记 `@Transactional(readOnly = true)`，避免无意义的 Hibernate Dirty Checking。
+
+## 三、数据与持久化契约 (JPA/Hibernate)
+
+- **禁用 OSIV**：必须显式配置 `spring.jpa.open-in-view: false`。懒加载必须收敛在 `@Transactional` 边界内，绝对禁止在 Controller 层或序列化阶段触发懒加载。
+- **杜绝 N+1 查询**：严禁在循环体内执行 SQL 或触发懒加载代理。跨聚合查询强制使用 `@EntityGraph`、`JOIN FETCH` 或 DTO 投影（Projection）。
+- **实体纯粹性**：JPA Entity 必须是普通 `class`。绝对禁止在 Entity 上使用 Lombok 的 `@Data`、`@EqualsAndHashCode`、`@ToString` 以防意外触发代理。必须基于稳定业务唯一键 (Business Key) 手写 `equals/hashCode`。
+- **Repository 职责**：Repository 仅限持久化存取，严禁混入 HTTP 上下文、权限校验或跨域编排。
+
+## 四、强制验证与交付动作 (Mandatory Actions)
+
+任务完成后，必须自动执行以下操作，并严格按模板输出报告：
+
+1. **执行 Skill 自检脚本**：在 `skills/workflow/java-code-standard` 目录执行 `node scripts/verify-rules.mjs`。若当前上下文是目标 Java 项目且不存在该脚本，标记为 `MISSING`；不得用 Skill 自检脚本替代目标项目自身的 Maven/Gradle/lint/test。
+2. **执行项目质量检查**：优先运行当前项目已有的 Java 构建、测试或 lint 命令；缺少脚本、配置或依赖时标记为 `MISSING`，未执行时标记为 `NOT RUN`。
+3. **输出交付与评审报告**：严格使用以下 Markdown 格式输出结论，禁止任何套话：
+
+```markdown
+### 代码合规自校验报告
+- **注入合规**：PASS / FAIL / MISSING / NOT RUN / N/A - 已彻底消除 `@Autowired` 字段注入。
+- **校验合规**：PASS / FAIL / MISSING / NOT RUN / N/A - Request DTO/入口已全部覆盖 `@Valid` / `@Validated`。
+- **事务合规**：PASS / FAIL / MISSING / NOT RUN / N/A - 不存在 `this.xxx()` 事务自调用，且只读方法已加 `readOnly = true`。
+- **时间契约**：PASS / FAIL / MISSING / NOT RUN / N/A - 已全部使用 `java.time` API。
+- **JPA 合规**：PASS / FAIL / MISSING / NOT RUN / N/A - Entity 未使用 `@Data`，且循环体内无查询逻辑。
+
+### 脚本执行结果 (Status: PASS / FAIL / MISSING / NOT RUN)
+- `node scripts/verify-rules.mjs`：输出简述；无法执行时说明原因。
+- 项目质量命令：输出简述；缺少命令时标记 `MISSING`。
+
+### 评审异常点
+*(如无异常，填“无”)*
+- **级别**：Critical / Major / Minor
+- **文件与行号**：`xxx.java:41`
+- **违规说明**：...
+- **修复建议**：...
+```

package/skills/workflow/java-code-standard/__test__/verify-rules.test.ts

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict'
+import { execFileSync, spawnSync } from 'node:child_process'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { it } from 'vitest'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const skillRoot = path.resolve(__dirname, '..')
+const projectRoot = path.resolve(skillRoot, '..', '..', '..')
+const scriptPath = path.join(skillRoot, 'scripts', 'verify-rules.mjs')
+
+function runScript(...args: string[]) {
+  return execFileSync(process.execPath, [scriptPath, ...args], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  })
+}
+
+it('verify-rules 校验自检和领域提升扫描', () => {
+  assert.match(runScript(), /PASS java-code-standard self rules are valid/)
+  assert.match(
+    runScript(
+      'hoist',
+      '--target',
+      'src/main/java/com/example/order/shared',
+      '--uses',
+      'src/main/java/com/example/order/create/CreateOrderService.java',
+      'src/main/java/com/example/order/update/UpdateOrderService.java',
+      'src/main/java/com/example/order/cancel/CancelOrderService.java',
+    ),
+    /PASS java hoist domain-boundary scan completed/,
+  )
+
+  const nestedHoistResult = spawnSync(process.execPath, [
+    scriptPath,
+    'hoist',
+    '--target',
+    'src/main/java/com/example/order/create/shared',
+    '--uses',
+    'src/main/java/com/example/order/create/CreateOrderService.java',
+    'src/main/java/com/example/order/update/UpdateOrderService.java',
+    'src/main/java/com/example/order/cancel/CancelOrderService.java',
+  ], { cwd: projectRoot, encoding: 'utf8' })
+  assert.equal(nestedHoistResult.status, 1)
+  assert.match(nestedHoistResult.stderr, /FAIL \[HOIST_BOUNDARY_RISK\]/)
+  assert.doesNotMatch(nestedHoistResult.stdout, /PASS java hoist domain-boundary scan completed/)
+})