moluoxixi-ai-rules 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/LICENSE +21 -0
  2. package/README-zh.md +246 -0
  3. package/README.md +246 -0
  4. package/dist/constants/hosts.d.ts +34 -0
  5. package/dist/constants/hosts.js +71 -0
  6. package/dist/constants/skills.d.ts +91 -0
  7. package/dist/constants/skills.js +156 -0
  8. package/dist/scripts/cli.d.ts +2 -0
  9. package/dist/scripts/cli.js +145 -0
  10. package/dist/scripts/host-setup.d.ts +2 -0
  11. package/dist/scripts/host-setup.js +147 -0
  12. package/dist/scripts/lib/install.d.ts +78 -0
  13. package/dist/scripts/lib/install.js +367 -0
  14. package/dist/scripts/lib/links.d.ts +8 -0
  15. package/dist/scripts/lib/links.js +18 -0
  16. package/dist/scripts/lib/skill-projection.d.ts +14 -0
  17. package/dist/scripts/lib/skill-projection.js +54 -0
  18. package/dist/scripts/lib/tool.d.ts +40 -0
  19. package/dist/scripts/lib/tool.js +125 -0
  20. package/dist/scripts/lib/vendor-sync.d.ts +3 -0
  21. package/dist/scripts/lib/vendor-sync.js +129 -0
  22. package/dist/scripts/lib/vendors.d.ts +29 -0
  23. package/dist/scripts/lib/vendors.js +155 -0
  24. package/dist/scripts/lib/verify.d.ts +7 -0
  25. package/dist/scripts/lib/verify.js +84 -0
  26. package/dist/scripts/sync-vendors.d.ts +1 -0
  27. package/dist/scripts/sync-vendors.js +173 -0
  28. package/dist/scripts/verify-host.d.ts +2 -0
  29. package/dist/scripts/verify-host.js +42 -0
  30. package/package.json +60 -0
  31. package/rules/AGENTS.md +30 -0
  32. package/skills/skill-validation-standard/SKILL.md +45 -0
  33. package/skills/skill-validation-standard/__test__/verify-rules.test.ts +108 -0
  34. package/skills/skill-validation-standard/scripts/verify-rules.mjs +186 -0
  35. package/skills/workflow/frontend-code-standard/SKILL.md +58 -0
  36. package/skills/workflow/frontend-code-standard/__test__/verify-rules.test.ts +227 -0
  37. package/skills/workflow/frontend-code-standard/scripts/verify-rules.mjs +537 -0
  38. package/skills/workflow/java-code-standard/SKILL.md +58 -0
  39. package/skills/workflow/java-code-standard/__test__/verify-rules.test.ts +48 -0
  40. package/skills/workflow/java-code-standard/scripts/verify-rules.mjs +215 -0
  41. package/skills/workflow/nestjs-code-standard/SKILL.md +61 -0
  42. package/skills/workflow/nestjs-code-standard/__test__/verify-rules.test.ts +48 -0
  43. package/skills/workflow/nestjs-code-standard/scripts/verify-rules.mjs +219 -0
  44. package/skills/workflow/node-code-standard/SKILL.md +62 -0
  45. package/skills/workflow/node-code-standard/__test__/verify-rules.test.ts +48 -0
  46. package/skills/workflow/node-code-standard/scripts/verify-rules.mjs +213 -0
  47. package/skills/workflow/project-knowledge-read-workflow/SKILL.md +102 -0
  48. package/skills/workflow/project-knowledge-refresh-workflow/SKILL.md +149 -0
  49. package/skills/workflow/software-development-workflow/SKILL.md +85 -0
@@ -0,0 +1,215 @@
1
+ #!/usr/bin/env node
2
+ import fs from 'node:fs'
3
+ import path from 'node:path'
4
+ import { fileURLToPath } from 'node:url'
5
+
6
+ // Resolve the skill root once so all file checks stay anchored to this skill package.
7
+ const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
8
+
9
+ function readSkillFile(...segments) {
10
+ return fs.readFileSync(path.join(skillRoot, ...segments), 'utf8')
11
+ }
12
+
13
+ function assertContains(content, pattern, message) {
14
+ if (!pattern.test(content))
15
+ throw new Error(message)
16
+ }
17
+
18
+ function printPass(message, details = {}) {
19
+ console.log(`PASS ${message}`)
20
+
21
+ for (const [key, value] of Object.entries(details))
22
+ console.log(`${key}: ${value}`)
23
+ }
24
+
25
+ function createHoistBoundaryError(message, details) {
26
+ // Hoist risk signals are explicit failures so automated checks cannot report a risky scan as PASS.
27
+ const detailLines = Object.entries(details)
28
+ .map(([key, value]) => `${key}: ${value}`)
29
+ .join('\n')
30
+
31
+ return new Error(`[HOIST_BOUNDARY_RISK] ${message}\n${detailLines}`)
32
+ }
33
+
34
+ function printHelp() {
35
+ console.log(`用法: node verify-rules.mjs [command] [options]
36
+
37
+ 命令:
38
+ self 校验本 skill 的规则完整性(默认)
39
+ hoist 执行共享边界风险扫描(只作机械线索)
40
+ --help 显示帮助信息
41
+
42
+ 选项:
43
+ --target <path> 指定抽离目标 package
44
+ --uses <path1> <path2> ... 指定至少 2 个使用点路径
45
+
46
+ 示例:
47
+ cd skills/workflow/java-code-standard
48
+ node scripts/verify-rules.mjs
49
+ node scripts/verify-rules.mjs 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
50
+ `)
51
+ }
52
+
53
+ function getOption(args, name) {
54
+ const index = args.indexOf(name)
55
+
56
+ if (index === -1)
57
+ throw new Error(`缺少参数 ${name}`)
58
+
59
+ const value = args[index + 1]
60
+
61
+ if (!value || value.startsWith('--'))
62
+ throw new Error(`参数 ${name} 必须提供值`)
63
+
64
+ return value
65
+ }
66
+
67
+ function normalizeSegments(filePath) {
68
+ return path.resolve(process.cwd(), filePath).split(path.sep)
69
+ }
70
+
71
+ // Compute the nearest shared boundary for all usage sites.
72
+ function nearestCommonAncestor(paths) {
73
+ const segmentsList = paths.map(normalizeSegments)
74
+ const first = segmentsList[0]
75
+ const shared = []
76
+
77
+ for (let index = 0; index < first.length; index += 1) {
78
+ const segment = first[index]
79
+
80
+ if (segmentsList.every(segments => segments[index] === segment))
81
+ shared.push(segment)
82
+ else
83
+ break
84
+ }
85
+
86
+ return shared
87
+ }
88
+
89
+ function isUnderAncestor(targetSegments, ancestorSegments) {
90
+ if (targetSegments.length < ancestorSegments.length)
91
+ return false
92
+
93
+ return ancestorSegments.every((segment, index) => targetSegments[index] === segment)
94
+ }
95
+
96
+ // Use the mechanical boundary as an explicit failure signal; semantic ownership still needs human review.
97
+ function scanHoistTarget(args) {
98
+ const target = getOption(args, '--target')
99
+ const usesIndex = args.indexOf('--uses')
100
+
101
+ if (usesIndex === -1)
102
+ throw new Error('缺少参数 --uses')
103
+
104
+ const uses = args.slice(usesIndex + 1)
105
+
106
+ if (uses.length < 2)
107
+ throw new Error('--uses 至少需要两个使用点')
108
+
109
+ const ancestorSegments = nearestCommonAncestor(uses)
110
+ const targetSegments = normalizeSegments(target)
111
+ const targetPath = path.resolve(process.cwd(), target)
112
+ const ancestor = ancestorSegments.join('/')
113
+
114
+ if (!isUnderAncestor(targetSegments, ancestorSegments)) {
115
+ throw createHoistBoundaryError('抽离目标不在允许的共享边界内,请人工确认它是否应该进入全局共享层或独立共享包', {
116
+ target: targetPath,
117
+ sharedBoundary: ancestor,
118
+ })
119
+ }
120
+ else if (targetSegments.length !== ancestorSegments.length + 1) {
121
+ throw createHoistBoundaryError('抽离目标位于更深层级,请人工确认它是否应留在局部业务内部,或者提升到全局共享层', {
122
+ target: targetPath,
123
+ sharedBoundary: ancestor,
124
+ })
125
+ }
126
+
127
+ printPass('java hoist domain-boundary scan completed', {
128
+ target: targetPath,
129
+ sharedBoundary: ancestor,
130
+ advisory: 'The boundary signal is mechanical only; review domain semantics before changing ownership.',
131
+ })
132
+ }
133
+
134
+ function verifySelf() {
135
+ const skill = readSkillFile('SKILL.md')
136
+
137
+ assertContains(skill, /name: java-code-standard/, 'SKILL.md 必须保持 java-code-standard 名称')
138
+ assertContains(skill, /触发时机:当用户要求新建、编写、重构、拆分、优化、评审或校验 Java\/Spring Boot 后端代码时触发/, 'SKILL.md 必须声明完整触发场景')
139
+ assertContains(skill, /# Java & Spring Boot 工程架构与代码规范/, 'SKILL.md 必须使用 Java 规范标题')
140
+ assertContains(skill, /当前任务目标与改动范围内严格遵守/, 'SKILL.md 必须限定任务范围')
141
+ assertContains(skill, /本文件是唯一规则源/, 'SKILL.md 必须声明唯一规则源')
142
+ assertContains(skill, /Java/, 'SKILL.md 必须覆盖 Java')
143
+ assertContains(skill, /Spring Boot/, 'SKILL.md 必须覆盖 Spring Boot')
144
+ assertContains(skill, /## 一、核心架构与设计纪律/, 'SKILL.md 必须包含核心架构 section')
145
+ assertContains(skill, /## 二、Spring Boot 框架强制约束/, 'SKILL.md 必须包含 Spring Boot section')
146
+ assertContains(skill, /## 三、数据与持久化契约 \(JPA\/Hibernate\)/, 'SKILL.md 必须包含 JPA/Hibernate section')
147
+ assertContains(skill, /## 四、强制验证与交付动作 \(Mandatory Actions\)/, 'SKILL.md 必须包含交付动作 section')
148
+ assertContains(skill, /domain.*org\.springframework/, 'SKILL.md 必须声明 domain 与 Spring 隔离')
149
+ assertContains(skill, /domain.*jakarta\.persistence/, 'SKILL.md 必须声明 domain 与 JPA 隔离')
150
+ assertContains(skill, /拆分领域模型与持久化实体/, 'SKILL.md 必须说明旧 JPA domain 模型的拆分语义')
151
+ assertContains(skill, /严禁 `domain` 依赖 `infrastructure`/, 'SKILL.md 必须禁止 domain 依赖 infrastructure')
152
+ assertContains(skill, /全局 `utils` 目录/, 'SKILL.md 必须禁止无语义全局 utils')
153
+ assertContains(skill, /Map/, 'SKILL.md 必须禁止宽泛 Map 契约')
154
+ assertContains(skill, /裸 `JSON`/, 'SKILL.md 必须禁止裸 JSON 契约')
155
+ assertContains(skill, /Object/, 'SKILL.md 必须禁止 Object 契约')
156
+ assertContains(skill, /List\.copyOf\(\)/, 'SKILL.md 必须覆盖集合防泄漏复制')
157
+ assertContains(skill, /Collections\.unmodifiableList\(\)/, 'SKILL.md 必须覆盖领域集合不可变视图')
158
+ assertContains(skill, /java\.util\.Date/, 'SKILL.md 必须禁用 java.util.Date')
159
+ assertContains(skill, /Calendar/, 'SKILL.md 必须禁用 Calendar')
160
+ assertContains(skill, /java\.sql\.Timestamp/, 'SKILL.md 必须禁用 java.sql.Timestamp')
161
+ assertContains(skill, /java\.time/, 'SKILL.md 必须强制使用 java.time')
162
+ assertContains(skill, /@Autowired/, 'SKILL.md 必须覆盖禁止 @Autowired 字段注入')
163
+ assertContains(skill, /final/, 'SKILL.md 必须要求依赖 final')
164
+ assertContains(skill, /@Valid/, 'SKILL.md 必须覆盖 @Valid')
165
+ assertContains(skill, /@Validated/, 'SKILL.md 必须覆盖 @Validated')
166
+ assertContains(skill, /this\.xxx\(\)/, 'SKILL.md 必须禁止 this.xxx() 事务自调用')
167
+ assertContains(skill, /AopContext\.currentProxy\(\)/, 'SKILL.md 必须禁止 AopContext.currentProxy() 绕行')
168
+ assertContains(skill, /@Transactional\(readOnly = true\)/, 'SKILL.md 必须覆盖查询只读事务')
169
+ assertContains(skill, /Dirty Checking/, 'SKILL.md 必须说明 Hibernate Dirty Checking 开销')
170
+ assertContains(skill, /OSIV/, 'SKILL.md 必须覆盖 OSIV')
171
+ assertContains(skill, /spring\.jpa\.open-in-view: false/, 'SKILL.md 必须强制关闭 OSIV')
172
+ assertContains(skill, /循环体内执行 SQL/, 'SKILL.md 必须禁止循环 SQL')
173
+ assertContains(skill, /@EntityGraph/, 'SKILL.md 必须覆盖 JPA EntityGraph')
174
+ assertContains(skill, /JOIN FETCH/, 'SKILL.md 必须覆盖 JOIN FETCH')
175
+ assertContains(skill, /Projection/, 'SKILL.md 必须覆盖 DTO Projection')
176
+ assertContains(skill, /@Data/, 'SKILL.md 必须覆盖 JPA Entity 禁用 Lombok @Data')
177
+ assertContains(skill, /@EqualsAndHashCode/, 'SKILL.md 必须覆盖 JPA Entity 禁用 Lombok @EqualsAndHashCode')
178
+ assertContains(skill, /@ToString/, 'SKILL.md 必须覆盖 JPA Entity 禁用 Lombok @ToString')
179
+ assertContains(skill, /Business Key/, 'SKILL.md 必须覆盖 JPA Entity equals/hashCode 业务唯一键')
180
+ assertContains(skill, /Repository 仅限持久化存取/, 'SKILL.md 必须约束 Repository 职责')
181
+ assertContains(skill, /### 代码合规自校验报告/, 'SKILL.md 必须包含代码合规自校验报告模板')
182
+ assertContains(skill, /### 脚本执行结果 \(Status: PASS \/ FAIL \/ MISSING \/ NOT RUN\)/, 'SKILL.md 必须包含脚本状态模板')
183
+ assertContains(skill, /### 评审异常点/, 'SKILL.md 必须包含评审异常点模板')
184
+ assertContains(skill, /scripts\/verify-rules\.mjs/, 'SKILL.md 必须声明自带验证脚本')
185
+ assertContains(skill, /不得用 Skill 自检脚本替代目标项目自身/, 'SKILL.md 必须禁止用 skill 自检替代项目测试')
186
+ assertContains(skill, /MISSING/, 'SKILL.md 必须覆盖 MISSING 状态')
187
+ assertContains(skill, /NOT RUN/, 'SKILL.md 必须覆盖 NOT RUN 状态')
188
+ assertContains(skill, /PASS/, 'SKILL.md 必须覆盖 PASS 状态')
189
+ assertContains(skill, /FAIL/, 'SKILL.md 必须覆盖 FAIL 状态')
190
+
191
+ printPass('java-code-standard self rules are valid')
192
+ }
193
+
194
+ function main() {
195
+ const [command = 'self', ...args] = process.argv.slice(2)
196
+
197
+ if (command === '--help' || command === '-h')
198
+ return printHelp()
199
+
200
+ if (command === 'self')
201
+ return verifySelf()
202
+
203
+ if (command === 'hoist')
204
+ return scanHoistTarget(args)
205
+
206
+ throw new Error(`未知命令:${command},使用 --help 查看帮助`)
207
+ }
208
+
209
+ try {
210
+ main()
211
+ }
212
+ catch (error) {
213
+ console.error(`FAIL ${error.message}`)
214
+ process.exitCode = 1
215
+ }
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: nestjs-code-standard
3
+ description: 触发时机:当用户要求新建、编写、重构、拆分、优化、评审 NestJS 后端代码时触发。用于强制执行 DTO 契约、事务防腐层、序列化显式脱敏、依赖边界划分及 E2E 测试交付。
4
+ ---
5
+
6
+ # NestJS 工程架构与代码规范 (NestJS Architecture & Code Standards)
7
+
8
+ 在执行任何 NestJS 后端代码生成、重构或评审任务时,必须没有任何例外地严格遵守以下物理边界与编码红线。本文件是唯一规则源,绝不为了兼容历史写法而保留无价值的过渡层或破坏边界。
9
+
10
+ ## 一、 输入防腐与安全边界 (Input & Security Boundaries)
11
+
12
+ - **强校验红线**:全局强制启用 `ValidationPipe` 并配置 `whitelist: true`, `forbidNonWhitelisted: true`, `transform: true`。彻底阻断未声明字段。
13
+ - **DTO 纯洁性**:严禁在 DTO 中使用 `any`、`Record<string, any>` 或开放索引签名。进入 Application/Domain 层后,禁止重复编写手动的防御性代码(如 `typeof` 或空值检查)。
14
+ - **查询边界**:列表查询 DTO 必须显式定义**分页最大上限**与**排序字段白名单**。绝对禁止将前端传入的任意 Query 对象直接透传给底层 ORM Builder。
15
+ - **租户隔离**:操作 Tenant-scoped 数据时,必须从服务端可信会话获取 `tenantId` 并强制作为 DB 查询边界,严禁信任客户端载荷。
16
+
17
+ ## 二、 核心架构与事务防腐 (Architecture & Transaction Anti-Corruption)
18
+
19
+ - **分层死线**:
20
+ - **Controller** 仅处理路由与 DTO 映射,严禁编排业务或操作 ORM。
21
+ - **Domain** 必须保持纯粹,严禁依赖 HTTP 宿主对象、ORM 注解(仅允许 Domain Service 使用 `@Injectable()`)。
22
+ - **事务句柄隔离**:`EntityManager`、`QueryRunner` 等底层事务句柄只能存在于 Infrastructure 层。**绝对禁止**跨越至 Controller、Application 或 Domain。
23
+ - **长流程隔离**:严禁将远程网络调用或文件 I/O 隐式裹挟在数据库事务中。同库事务使用 UnitOfWork;跨系统调用必须使用 Transactional Outbox 模式。
24
+
25
+ ## 三、 依赖注入与作用域安全 (DI & Scope Safety)
26
+
27
+ - **禁用字段注入**:所有 Provider 依赖必须通过构造函数显式声明。
28
+ - **禁用请求级作用域**:严禁在底层模块滥用 `Scope.REQUEST` 或注入 `REQUEST`。AsyncLocalStorage (ALS) 必须封装为统一的 `RequestContext`,且禁止 Domain 直接读取。
29
+ - **禁用环形依赖**:视 `forwardRef()` 为设计缺陷。强制通过领域事件或解耦重构消除环形依赖。
30
+
31
+ ## 四、 序列化脱敏与错误映射 (Serialization & Error Mapping)
32
+
33
+ - **默认拒绝序列化**:响应数据默认不暴露。必须通过实例化 Response DTO 进行映射,或严格执行 `plainToInstance(..., { excludeExtraneousValues: true })` 确保未被 `@Expose()` 标记的字段被安全拦截。
34
+ - **环境变量控制**:业务逻辑严禁直接读取 `process.env`,必须通过强类型的 Config Provider 注入。
35
+ - **全局错误处理**:业务代码只抛出自定义领域/应用错误(必须通过 `cause` 保留原始异常)。HTTP 状态码转换统一交由全局 Exception Filter 处理。
36
+
37
+ ## 五、 强制验证与交付动作 (Mandatory Deliverables)
38
+
39
+ 代码修改完成后,必须同步交付相应的测试代码,并严格按以下模板输出报告:
40
+
41
+ 1. **执行自检脚本**:尝试执行 `node scripts/verify-rules.mjs`。
42
+ 2. **强制交付模板**:必须按照以下 Markdown 格式输出最终结论,禁止任何套话:
43
+
44
+ ```markdown
45
+ ### 代码合规自校验报告
46
+ - [ ] **输入防御**:所有 DTO 已去除 `any`,列表查询已配置上限与排序白名单。
47
+ - [ ] **依赖与容器**:未引入任何新的 `forwardRef()` 或 `Scope.REQUEST`。
48
+ - [ ] **事务防腐**:ORM 句柄未泄漏至 Infrastructure 外部,事务内无网络 I/O。
49
+ - [ ] **显式脱敏**:响应对象已通过 `excludeExtraneousValues: true` 或严格映射进行脱敏。
50
+ - [ ] **测试覆盖**:已同步交付包含 Negative Cases 的 E2E 测试或真实的 DB 集成测试。
51
+
52
+ ### 脚本执行结果 (Status: PASS / FAIL / MISSING / NOT RUN)
53
+ - 脚本执行输出简述,或说明为何无法执行(MISSING)。
54
+
55
+ ### 评审异常点 (仅在审查或重构失败时输出)
56
+ *(如无异常,填“无”)*
57
+ - **级别**:[Critical/Major/Minor]
58
+ - **文件与位置**:`xxx.ts:41`
59
+ - **违规说明**:... (如:在 Application 层直接注入了 EntityManager)
60
+ - **修复建议**:...
61
+ ```
@@ -0,0 +1,48 @@
1
+ import assert from 'node:assert/strict'
2
+ import { execFileSync, spawnSync } from 'node:child_process'
3
+ import path from 'node:path'
4
+ import process from 'node:process'
5
+ import { fileURLToPath } from 'node:url'
6
+ import { it } from 'vitest'
7
+
8
+ const __dirname = path.dirname(fileURLToPath(import.meta.url))
9
+ const skillRoot = path.resolve(__dirname, '..')
10
+ const projectRoot = path.resolve(skillRoot, '..', '..', '..')
11
+ const scriptPath = path.join(skillRoot, 'scripts', 'verify-rules.mjs')
12
+
13
+ function runScript(...args: string[]) {
14
+ return execFileSync(process.execPath, [scriptPath, ...args], {
15
+ cwd: projectRoot,
16
+ encoding: 'utf8',
17
+ })
18
+ }
19
+
20
+ it('verify-rules 校验自检和领域提升扫描', () => {
21
+ assert.match(runScript(), /PASS nestjs-code-standard self rules are valid/)
22
+ assert.match(
23
+ runScript(
24
+ 'hoist',
25
+ '--target',
26
+ 'src/modules/orders/shared',
27
+ '--uses',
28
+ 'src/modules/orders/create/create-order.service.ts',
29
+ 'src/modules/orders/update/update-order.service.ts',
30
+ 'src/modules/orders/cancel/cancel-order.service.ts',
31
+ ),
32
+ /PASS nestjs hoist domain-boundary scan completed/,
33
+ )
34
+
35
+ const nestedHoistResult = spawnSync(process.execPath, [
36
+ scriptPath,
37
+ 'hoist',
38
+ '--target',
39
+ 'src/modules/orders/create/shared',
40
+ '--uses',
41
+ 'src/modules/orders/create/create-order.service.ts',
42
+ 'src/modules/orders/update/update-order.service.ts',
43
+ 'src/modules/orders/cancel/cancel-order.service.ts',
44
+ ], { cwd: projectRoot, encoding: 'utf8' })
45
+ assert.equal(nestedHoistResult.status, 1)
46
+ assert.match(nestedHoistResult.stderr, /FAIL \[HOIST_BOUNDARY_RISK\]/)
47
+ assert.doesNotMatch(nestedHoistResult.stdout, /PASS nestjs hoist domain-boundary scan completed/)
48
+ })
@@ -0,0 +1,219 @@
1
+ #!/usr/bin/env node
2
+ import fs from 'node:fs'
3
+ import path from 'node:path'
4
+ import { fileURLToPath } from 'node:url'
5
+
6
+ // Resolve the skill root once so every file check stays anchored to this skill package.
7
+ const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
8
+
9
+ function readSkillFile(...segments) {
10
+ return fs.readFileSync(path.join(skillRoot, ...segments), 'utf8')
11
+ }
12
+
13
+ function assertContains(content, pattern, message) {
14
+ if (!pattern.test(content))
15
+ throw new Error(message)
16
+ }
17
+
18
+ function printPass(message, details = {}) {
19
+ console.log(`PASS ${message}`)
20
+
21
+ for (const [key, value] of Object.entries(details))
22
+ console.log(`${key}: ${value}`)
23
+ }
24
+
25
+ function createHoistBoundaryError(message, details) {
26
+ // Hoist risk signals are explicit failures so automated checks cannot report a risky scan as PASS.
27
+ const detailLines = Object.entries(details)
28
+ .map(([key, value]) => `${key}: ${value}`)
29
+ .join('\n')
30
+
31
+ return new Error(`[HOIST_BOUNDARY_RISK] ${message}\n${detailLines}`)
32
+ }
33
+
34
+ function printHelp() {
35
+ console.log(`用法: node verify-rules.mjs [command] [options]
36
+
37
+ 命令:
38
+ self 校验本 skill 的规则完整性(默认)
39
+ hoist 执行共享边界风险扫描(只作机械线索)
40
+ --help 显示帮助信息
41
+
42
+ 选项:
43
+ --target <path> 指定抽离目标目录
44
+ --uses <path1> <path2> ... 指定至少 2 个使用点路径
45
+
46
+ 示例:
47
+ node scripts/verify-rules.mjs
48
+ node scripts/verify-rules.mjs hoist --target src/shared/order-presenter.ts --uses src/modules/orders/controllers/orders.controller.ts src/modules/orders/application/create-order.service.ts src/modules/orders/infrastructure/persistence/typeorm-order.repository.ts
49
+ `)
50
+ }
51
+
52
+ function getOption(args, name) {
53
+ const index = args.indexOf(name)
54
+
55
+ if (index === -1)
56
+ throw new Error(`缺少参数 ${name}`)
57
+
58
+ const value = args[index + 1]
59
+
60
+ if (!value || value.startsWith('--'))
61
+ throw new Error(`参数 ${name} 必须提供值`)
62
+
63
+ return value
64
+ }
65
+
66
+ function normalizeSegments(filePath) {
67
+ return path.resolve(process.cwd(), filePath).split(path.sep)
68
+ }
69
+
70
+ // Compute the nearest shared boundary for all usage sites.
71
+ function nearestCommonAncestor(paths) {
72
+ const segmentsList = paths.map(normalizeSegments)
73
+ const first = segmentsList[0]
74
+ const shared = []
75
+
76
+ for (let index = 0; index < first.length; index += 1) {
77
+ const segment = first[index]
78
+
79
+ if (segmentsList.every(segments => segments[index] === segment))
80
+ shared.push(segment)
81
+ else
82
+ break
83
+ }
84
+
85
+ return shared
86
+ }
87
+
88
+ function isUnderAncestor(targetSegments, ancestorSegments) {
89
+ if (targetSegments.length < ancestorSegments.length)
90
+ return false
91
+
92
+ return ancestorSegments.every((segment, index) => targetSegments[index] === segment)
93
+ }
94
+
95
+ // Use the mechanical boundary as an explicit failure signal; semantic ownership still needs human review.
96
+ function scanHoistTarget(args) {
97
+ const target = getOption(args, '--target')
98
+ const usesIndex = args.indexOf('--uses')
99
+
100
+ if (usesIndex === -1)
101
+ throw new Error('缺少参数 --uses')
102
+
103
+ const uses = args.slice(usesIndex + 1)
104
+
105
+ if (uses.length < 2)
106
+ throw new Error('--uses 至少需要两个使用点')
107
+
108
+ const ancestorSegments = nearestCommonAncestor(uses)
109
+ const targetSegments = normalizeSegments(target)
110
+ const targetPath = path.resolve(process.cwd(), target)
111
+ const ancestor = ancestorSegments.join('/')
112
+
113
+ if (!isUnderAncestor(targetSegments, ancestorSegments)) {
114
+ throw createHoistBoundaryError('抽离目标不在允许的共享边界内,请人工确认它是否应该进入全局共享层或独立共享包', {
115
+ target: targetPath,
116
+ sharedBoundary: ancestor,
117
+ })
118
+ }
119
+ else if (targetSegments.length !== ancestorSegments.length + 1) {
120
+ throw createHoistBoundaryError('抽离目标位于更深层级,请人工确认它是否应留在局部业务内部,或者提升到全局共享层', {
121
+ target: targetPath,
122
+ sharedBoundary: ancestor,
123
+ })
124
+ }
125
+
126
+ printPass('nestjs hoist domain-boundary scan completed', {
127
+ target: targetPath,
128
+ sharedBoundary: ancestor,
129
+ advisory: 'The boundary signal is mechanical only; review domain semantics before changing ownership.',
130
+ })
131
+ }
132
+
133
+ function verifySelf() {
134
+ const skill = readSkillFile('SKILL.md')
135
+
136
+ assertContains(skill, /name: nestjs-code-standard/, 'SKILL.md 必须声明正确的 skill name')
137
+ assertContains(skill, /触发时机:当用户要求新建、编写、重构、拆分、优化、评审 NestJS 后端代码时触发/, 'SKILL.md 必须声明用户给定的触发时机')
138
+ assertContains(skill, /# NestJS 工程架构与代码规范/, 'SKILL.md 必须使用用户给定的规范标题')
139
+ assertContains(skill, /唯一规则源/, 'SKILL.md 必须声明唯一规则源')
140
+
141
+ assertContains(skill, /## 一、 输入防腐与安全边界/, 'SKILL.md 必须包含输入防腐与安全边界章节')
142
+ assertContains(skill, /ValidationPipe/, 'SKILL.md 必须覆盖 ValidationPipe')
143
+ assertContains(skill, /whitelist: true/, 'SKILL.md 必须强制 whitelist')
144
+ assertContains(skill, /forbidNonWhitelisted: true/, 'SKILL.md 必须强制 forbidNonWhitelisted')
145
+ assertContains(skill, /transform: true/, 'SKILL.md 必须强制 transform')
146
+ assertContains(skill, /DTO 纯洁性/, 'SKILL.md 必须覆盖 DTO 纯洁性')
147
+ assertContains(skill, /`any`/, 'SKILL.md 必须禁止 any')
148
+ assertContains(skill, /Record<string, any>/, 'SKILL.md 必须禁止 Record<string, any>')
149
+ assertContains(skill, /分页最大上限/, 'SKILL.md 必须覆盖分页最大上限')
150
+ assertContains(skill, /排序字段白名单/, 'SKILL.md 必须覆盖排序字段白名单')
151
+ assertContains(skill, /Tenant-scoped/, 'SKILL.md 必须覆盖租户隔离')
152
+ assertContains(skill, /tenantId/, 'SKILL.md 必须声明 tenantId 服务端可信来源')
153
+
154
+ assertContains(skill, /## 二、 核心架构与事务防腐/, 'SKILL.md 必须包含核心架构与事务防腐章节')
155
+ assertContains(skill, /Controller/, 'SKILL.md 必须覆盖 Controller 边界')
156
+ assertContains(skill, /Application/, 'SKILL.md 必须覆盖 Application 边界')
157
+ assertContains(skill, /Domain/, 'SKILL.md 必须覆盖 Domain 边界')
158
+ assertContains(skill, /Infrastructure/, 'SKILL.md 必须覆盖 Infrastructure 边界')
159
+ assertContains(skill, /@Injectable\(\)/, 'SKILL.md 必须覆盖 Domain Service 的 Injectable 例外')
160
+ assertContains(skill, /EntityManager/, 'SKILL.md 必须限制 EntityManager 泄漏')
161
+ assertContains(skill, /QueryRunner/, 'SKILL.md 必须限制 QueryRunner 泄漏')
162
+ assertContains(skill, /UnitOfWork/, 'SKILL.md 必须覆盖 UnitOfWork')
163
+ assertContains(skill, /Transactional Outbox/, 'SKILL.md 必须覆盖 Transactional Outbox')
164
+
165
+ assertContains(skill, /## 三、 依赖注入与作用域安全/, 'SKILL.md 必须包含依赖注入与作用域安全章节')
166
+ assertContains(skill, /构造函数/, 'SKILL.md 必须要求构造函数注入')
167
+ assertContains(skill, /Scope\.REQUEST/, 'SKILL.md 必须禁用 Scope.REQUEST 滥用')
168
+ assertContains(skill, /REQUEST/, 'SKILL.md 必须禁用 REQUEST 注入滥用')
169
+ assertContains(skill, /AsyncLocalStorage/, 'SKILL.md 必须覆盖 AsyncLocalStorage')
170
+ assertContains(skill, /RequestContext/, 'SKILL.md 必须覆盖统一 RequestContext')
171
+ assertContains(skill, /forwardRef\(\)/, 'SKILL.md 必须限制 forwardRef')
172
+
173
+ assertContains(skill, /## 四、 序列化脱敏与错误映射/, 'SKILL.md 必须包含序列化脱敏与错误映射章节')
174
+ assertContains(skill, /默认拒绝序列化/, 'SKILL.md 必须覆盖默认拒绝序列化')
175
+ assertContains(skill, /plainToInstance/, 'SKILL.md 必须覆盖响应 DTO 实例化')
176
+ assertContains(skill, /excludeExtraneousValues/, 'SKILL.md 必须覆盖响应字段白名单映射')
177
+ assertContains(skill, /@Expose\(\)/, 'SKILL.md 必须覆盖响应字段显式暴露策略')
178
+ assertContains(skill, /process\.env/, 'SKILL.md 必须禁止业务代码直接读取 process.env')
179
+ assertContains(skill, /Config Provider/, 'SKILL.md 必须覆盖强类型 Config Provider')
180
+ assertContains(skill, /Exception Filter/, 'SKILL.md 必须覆盖异常映射 Filter')
181
+ assertContains(skill, /cause/, 'SKILL.md 必须覆盖错误 cause 上下文')
182
+
183
+ assertContains(skill, /## 五、 强制验证与交付动作/, 'SKILL.md 必须包含强制验证与交付动作章节')
184
+ assertContains(skill, /node scripts\/verify-rules\.mjs/, 'SKILL.md 必须要求执行自检脚本')
185
+ assertContains(skill, /### 代码合规自校验报告/, 'SKILL.md 必须包含用户给定的自校验报告模板')
186
+ assertContains(skill, /输入防御/, 'SKILL.md 必须覆盖输入防御报告项')
187
+ assertContains(skill, /依赖与容器/, 'SKILL.md 必须覆盖依赖与容器报告项')
188
+ assertContains(skill, /事务防腐/, 'SKILL.md 必须覆盖事务防腐报告项')
189
+ assertContains(skill, /显式脱敏/, 'SKILL.md 必须覆盖显式脱敏报告项')
190
+ assertContains(skill, /测试覆盖/, 'SKILL.md 必须覆盖测试覆盖报告项')
191
+ assertContains(skill, /Status: PASS \/ FAIL \/ MISSING \/ NOT RUN/, 'SKILL.md 必须声明脚本执行状态枚举')
192
+ assertContains(skill, /评审异常点/, 'SKILL.md 必须包含评审异常点模板')
193
+ assertContains(skill, /Critical\/Major\/Minor/, 'SKILL.md 必须包含异常级别枚举')
194
+
195
+ printPass('nestjs-code-standard self rules are valid')
196
+ }
197
+
198
+ function main() {
199
+ const [command = 'self', ...args] = process.argv.slice(2)
200
+
201
+ if (command === '--help' || command === '-h')
202
+ return printHelp()
203
+
204
+ if (command === 'self')
205
+ return verifySelf()
206
+
207
+ if (command === 'hoist')
208
+ return scanHoistTarget(args)
209
+
210
+ throw new Error(`未知命令:${command},使用 --help 查看帮助`)
211
+ }
212
+
213
+ try {
214
+ main()
215
+ }
216
+ catch (error) {
217
+ console.error(`FAIL ${error.message}`)
218
+ process.exitCode = 1
219
+ }
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: node-code-standard
3
+ description: 触发时机:当用户要求新建、编写、重构、拆分、优化、评审非 NestJS 的 Node.js/TypeScript 后端代码时触发。用于强制执行分层边界、Schema 强校验、隔离底层事务句柄、Express/Fastify 错误处理及强制测试验证。
4
+ ---
5
+
6
+ # Node.js 后端工程架构与代码规范 (Node.js Architecture & Code Standards)
7
+
8
+ 在执行任何非 NestJS 的 Node.js 后端代码生成、重构或评审任务时,必须没有任何例外地严格遵守以下物理边界与编码红线。
9
+
10
+ ## 一、分层架构与防腐红线 (Layered Architecture & Boundaries)
11
+
12
+ - **依赖倒置**:`Domain` 承载核心规则,绝对禁止依赖 HTTP 框架、ORM、SDK 或第三方工具。`Infrastructure` 负责封装数据库和 SDK,禁止反向污染业务类型的定义。
13
+ - **职责死线**:
14
+ - **Transport 层 (Router/Controller)**:仅处理参数提取、输入校验与协议映射。严禁在此直接编写业务逻辑或操作数据库。
15
+ - **Application 层 (UseCase)**:负责编排业务流程与界定事务边界。严禁透传 HTTP 框架原生对象(如 `req`, `res`, `reply`)至此层。
16
+ - **禁止垃圾桶**:业务 Helper 必须就近留在 Feature 模块内。全局 `shared/utils` 仅限纯技术工具,严禁存放带有业务语义的代码。
17
+
18
+ ## 二、契约边界与强类型安全 (Contracts & Type Safety)
19
+
20
+ - **Schema 唯一真实源 (SSOT)**:所有外部输入输出边界(HTTP、RPC、Event)必须使用 Schema 库(如 Zod, TypeBox)进行运行时强校验。严禁手写同名 Interface,静态类型必须由 Schema 推导(如 `z.infer`)。
21
+ - **校验边界隔离**:Schema 校验仅用于 Transport 边界。进入 Application/Domain 后,禁止重复编写防御性代码(如 `typeof`、空值检查、正则校验)。
22
+ - **领域纯粹性**:Domain Entity 和 UseCase Command 的类型必须是纯业务语义的,禁止直接复用或被迫继承自 Transport 层的 Schema 推导类型。
23
+
24
+ ## 三、事务与错误传播 (Transactions & Error Handling)
25
+
26
+ - **事务防腐**:绝对禁止将 `Knex.Transaction`、`Prisma.TransactionClient`、`EntityManager` 等底层数据库句柄透传给 Domain 或 Application 层。必须通过 UnitOfWork 或 AsyncLocalStorage 进行上下文隔离。
27
+ - **长事务隔离**:禁止将远程 RPC 调用或耗时外部 I/O 裹挟在数据库同步事务中,必须采用 Outbox 模式或异步补偿机制。
28
+ - **框架级错误传播**:
29
+ - **Express 4 降级防线**:所有 `async` Route Handler 强制使用 `asyncHandler` 包裹,防止 Promise Rejection 导致进程静默或请求挂起。
30
+ - **Fastify 全局收口**:必须注册 `setErrorHandler` 或统一 error plugin。Route 内部不得 catch 后返回伪装的 200/成功状态。
31
+ - **全局收口**:必须在框架顶级(Global Error Middleware / `setErrorHandler`)统一处理业务抛出的明确错误,严禁在 Route 内部吞错或直接返回伪装的 200/成功状态。
32
+
33
+ ## 四、运行时性能与安全底线 (Runtime & Security)
34
+
35
+ - **Event Loop 保护**:严禁在主线程执行同步深拷贝、超大 JSON 序列化或容易引发 ReDoS 的高风险正则。
36
+ - **Graceful Shutdown**:Entrypoint 必须拦截 `SIGINT/SIGTERM` 信号,停止接收新请求并安全销毁数据库/Redis 连接,严禁直接进程退出。
37
+ - **ALS 传递**:传递 Trace ID、Tenant ID 等横切关注点时,强制使用 Node 原生的 `AsyncLocalStorage`,禁止侵入业务函数的参数签名。
38
+
39
+ ## 五、强制验证与交付动作 (Mandatory Deliverables)
40
+
41
+ 任务完成后,必须自动执行以下操作,并严格按模板输出报告:
42
+
43
+ 1. **执行自校验**:必须尝试在终端执行 `lint`、`typecheck` 或相关自动化测试。
44
+ 2. **强制交付模板**:必须按照以下 Markdown 格式输出最终结论,禁止任何套话或角色扮演:
45
+
46
+ ```markdown
47
+ ### 代码合规自校验报告
48
+ - [ ] **依赖与防腐**:Application/Domain 未直接引入 req/res 对象或 ORM 事务句柄。
49
+ - [ ] **强类型契约**:外部输入已通过 Schema (Zod/TypeBox) 校验,无手写重复 Interface。
50
+ - [ ] **错误与生命周期**:Async 路由的 Rejection 已被接管,Entrypoint 已配置优雅退出。
51
+ - [ ] **测试覆盖**:已同步交付对应的集成或单元测试代码。
52
+
53
+ ### 执行结果 (Status: PASS / FAIL / MISSING / NOT RUN)
54
+ - 脚本执行输出简述,或说明为何无法执行(MISSING)。
55
+
56
+ ### 评审异常点 (仅在审查或重构失败时输出)
57
+ *(如无异常,填“无”)*
58
+ - **级别**:[Critical/Major/Minor]
59
+ - **文件与位置**:`xxx.ts:41`
60
+ - **违规说明**:... (如:在 Controller 层直接调起了 Prisma Transaction)
61
+ - **修复建议**:...
62
+ ```
@@ -0,0 +1,48 @@
1
+ import assert from 'node:assert/strict'
2
+ import { execFileSync, spawnSync } from 'node:child_process'
3
+ import path from 'node:path'
4
+ import process from 'node:process'
5
+ import { fileURLToPath } from 'node:url'
6
+ import { it } from 'vitest'
7
+
8
+ const __dirname = path.dirname(fileURLToPath(import.meta.url))
9
+ const skillRoot = path.resolve(__dirname, '..')
10
+ const projectRoot = path.resolve(skillRoot, '..', '..', '..')
11
+ const scriptPath = path.join(skillRoot, 'scripts', 'verify-rules.mjs')
12
+
13
+ function runScript(...args: string[]) {
14
+ return execFileSync(process.execPath, [scriptPath, ...args], {
15
+ cwd: projectRoot,
16
+ encoding: 'utf8',
17
+ })
18
+ }
19
+
20
+ it('verify-rules 校验自检和领域提升扫描', () => {
21
+ assert.match(runScript(), /PASS node-code-standard self rules are valid/)
22
+ assert.match(
23
+ runScript(
24
+ 'hoist',
25
+ '--target',
26
+ 'src/modules/orders/utils',
27
+ '--uses',
28
+ 'src/modules/orders/create/service.ts',
29
+ 'src/modules/orders/update/service.ts',
30
+ 'src/modules/orders/delete/service.ts',
31
+ ),
32
+ /PASS backend hoist domain-boundary scan completed/,
33
+ )
34
+
35
+ const nestedHoistResult = spawnSync(process.execPath, [
36
+ scriptPath,
37
+ 'hoist',
38
+ '--target',
39
+ 'src/modules/orders/create/utils',
40
+ '--uses',
41
+ 'src/modules/orders/create/service.ts',
42
+ 'src/modules/orders/update/service.ts',
43
+ 'src/modules/orders/delete/service.ts',
44
+ ], { cwd: projectRoot, encoding: 'utf8' })
45
+ assert.equal(nestedHoistResult.status, 1)
46
+ assert.match(nestedHoistResult.stderr, /FAIL \[HOIST_BOUNDARY_RISK\]/)
47
+ assert.doesNotMatch(nestedHoistResult.stdout, /PASS backend hoist domain-boundary scan completed/)
48
+ })