@elvis1513/auto-coding-skill 2.0.4 → 2.0.5
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.
- package/README.md +68 -6
- package/cli/assets/agents/explorer.toml +9 -6
- package/cli/assets/agents/fixer.toml +8 -6
- package/cli/assets/agents/reviewer.toml +7 -6
- package/cli/assets/skill/SKILL.md +24 -7
- package/cli/assets/skill/data/templates/ENGINEERING.md +85 -0
- package/cli/assets/skill/data/templates/bridges/CLAUDE.md +4 -1
- package/cli/assets/skill/data/templates/bridges/CODEX.md +4 -1
- package/cli/assets/skill/data/templates/docs/architecture/adr/_TEMPLATE-ADR.md +38 -0
- package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +67 -0
- package/cli/assets/skill/data/templates/docs/design/_TEMPLATE-DD.md +17 -11
- package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +16 -6
- package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +24 -0
- package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +63 -0
- package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +1 -0
- package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +1 -0
- package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +3 -0
- package/cli/assets/skill/scripts/ap.py +380 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -23,6 +23,13 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
|
|
|
23
23
|
|
|
24
24
|
## Release Notes
|
|
25
25
|
|
|
26
|
+
### v2.0.5
|
|
27
|
+
|
|
28
|
+
- Added generic engineering-structure governance: `docs/architecture/structure-standard.md`, ADR template, project health baseline, and optimization backlog templates.
|
|
29
|
+
- Added `ap.py structure-check --scope auto|changed|standard|full` for large-file thresholds, large-file growth blocking, function-size warnings, and baseline-doc checks.
|
|
30
|
+
- Integrated `structure-check` into `light-gate` when `structure.enabled: true` or `commands.structure_check` is configured.
|
|
31
|
+
- Added baseline-aware optimization policy so “optimization complete” means scoped P0/P1/P2 closure plus tracked/accepted remaining debt, not “no future optimizations exist.”
|
|
32
|
+
|
|
26
33
|
### v2.0.4
|
|
27
34
|
|
|
28
35
|
- Added a generic impact-aware gate engine: `ap.py impact`, `light-gate --scope auto|changed|standard|full`, and `--explain`.
|
|
@@ -156,6 +163,8 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
156
163
|
- `workflow.mode`
|
|
157
164
|
- `commands.*`
|
|
158
165
|
- `gate.*`
|
|
166
|
+
- `structure.*`
|
|
167
|
+
- `optimization.*`
|
|
159
168
|
- `target_env.*`
|
|
160
169
|
- `jenkins.*`
|
|
161
170
|
- `docs.*`
|
|
@@ -189,6 +198,9 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
189
198
|
4. Start AI development by constraints:
|
|
190
199
|
|
|
191
200
|
- `docs/ENGINEERING.md`
|
|
201
|
+
- `docs/architecture/structure-standard.md`
|
|
202
|
+
- `docs/reviews/project-health-baseline.md`
|
|
203
|
+
- `docs/reviews/optimization-backlog.md`
|
|
192
204
|
- `docs/tasks/taskbook.md`
|
|
193
205
|
- `docs/tasks/closure-log.md`
|
|
194
206
|
- `docs/interfaces/**`
|
|
@@ -211,6 +223,26 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
211
223
|
- If the client cannot run subagents, execute the same role sequence in the main agent.
|
|
212
224
|
- Keep one main agent responsible for scope, integration, quality gates, docs closure, git state, and final delivery.
|
|
213
225
|
|
|
226
|
+
## Structure Governance
|
|
227
|
+
|
|
228
|
+
The default project scaffold includes a generic professional structure standard:
|
|
229
|
+
|
|
230
|
+
- `docs/architecture/structure-standard.md`: layer boundaries, reuse-first rules, file/function size rules, and review priority definitions.
|
|
231
|
+
- `docs/architecture/adr/_TEMPLATE-ADR.md`: architectural decision record template.
|
|
232
|
+
- `docs/reviews/project-health-baseline.md`: accepted current structure, closed optimizations, accepted debt, and completion standard.
|
|
233
|
+
- `docs/reviews/optimization-backlog.md`: ongoing P0/P1/P2/P3 optimization backlog.
|
|
234
|
+
|
|
235
|
+
Useful commands:
|
|
236
|
+
|
|
237
|
+
```bash
|
|
238
|
+
python3 docs/tools/autopipeline/ap.py structure-check --scope auto
|
|
239
|
+
python3 docs/tools/autopipeline/ap.py structure-check --scope full
|
|
240
|
+
python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
`structure-check` is intentionally generic. Project-specific paths and stricter rules belong in `docs/ENGINEERING.md` under `structure.*`, `optimization.*`, and optional `commands.structure_check`.
|
|
244
|
+
Historical large-file debt can be listed in `structure.accepted_debt_paths` after it is recorded in the health baseline or optimization backlog; continued large additions to those files still fail.
|
|
245
|
+
|
|
214
246
|
## AGENTS.md Constraint Example
|
|
215
247
|
|
|
216
248
|
```md
|
|
@@ -218,7 +250,11 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
218
250
|
- Always use `auto-coding-skill` for implementation tasks.
|
|
219
251
|
- Before any code change, read and obey:
|
|
220
252
|
1) docs/ENGINEERING.md
|
|
221
|
-
2) docs/
|
|
253
|
+
2) docs/architecture/structure-standard.md
|
|
254
|
+
3) docs/tasks/taskbook.md
|
|
255
|
+
- Before any optimization review, also read:
|
|
256
|
+
1) docs/reviews/project-health-baseline.md
|
|
257
|
+
2) docs/reviews/optimization-backlog.md
|
|
222
258
|
- Execute workflow commands using `python3 docs/tools/autopipeline/ap.py`.
|
|
223
259
|
- If required docs are missing, create/update docs first, then code.
|
|
224
260
|
|
|
@@ -244,12 +280,21 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
244
280
|
## Default Gate Policy
|
|
245
281
|
- Default local gate is lightweight only.
|
|
246
282
|
- Use `python3 docs/tools/autopipeline/ap.py impact --scope auto` to inspect changed files, matched project rules, and selected gate scope.
|
|
283
|
+
- Use `python3 docs/tools/autopipeline/ap.py structure-check --scope auto` to catch file growth, large-file extension, and missing structure baseline docs.
|
|
247
284
|
- Use `python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain` for small-step development after a project declares `gate.default_scope: auto`, `commands.gate_changed`, or matching `gate.rules`.
|
|
248
285
|
- Use `light-gate --scope standard` for the backward-compatible configured gate, and `light-gate --scope full` before release/deploy-sensitive closure.
|
|
249
286
|
- The gate engine is generic. Project-specific path mapping belongs in `docs/ENGINEERING.md` under `gate.rules`; unknown or high-risk impact should upgrade to standard/full rather than silently skipping checks.
|
|
287
|
+
- The structure gate is generic. Project-specific thresholds and accepted generated/vendor paths belong in `docs/ENGINEERING.md` under `structure.*`.
|
|
250
288
|
- Do not require local Docker Compose or full local regression unless the task explicitly needs local runtime diagnosis.
|
|
251
289
|
- In `dev` mode, push is the finish line after `DEV-CLOSED` is recorded.
|
|
252
290
|
- In `verify` mode, Jenkins success, target environment verification, and closure record are mandatory.
|
|
291
|
+
|
|
292
|
+
## Structure Policy
|
|
293
|
+
- Before coding, identify the right layer and reuse points.
|
|
294
|
+
- Do not add new responsibilities to already-large files.
|
|
295
|
+
- Prefer existing libraries, helpers, components, and scripts over new local frameworks.
|
|
296
|
+
- Self-built concurrency/performance/tooling primitives require a reason plus tests or runtime evidence.
|
|
297
|
+
- For optimization review, read the health baseline and backlog first; accepted debt is not a fresh blocker.
|
|
253
298
|
```
|
|
254
299
|
|
|
255
300
|
## Docs Structure and Recording Rules
|
|
@@ -269,34 +314,51 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
269
314
|
- Purpose: master task ledger.
|
|
270
315
|
- How to record:
|
|
271
316
|
- Every task writes scope, risk, impact area, minimal design note, acceptance, evidence links.
|
|
317
|
+
- For code changes, record structure placement, reuse check, and whether ADR is needed.
|
|
272
318
|
|
|
273
319
|
### 3) docs/tasks/closure-log.md
|
|
274
320
|
- Purpose: default lightweight closure record.
|
|
275
321
|
- How to record:
|
|
276
322
|
- Append one record per task.
|
|
277
|
-
- Required fields: task, commit, Jenkins build, target env verification, result, follow-up.
|
|
323
|
+
- Required fields: task, commit, Jenkins build, target env verification, structure check, result, follow-up.
|
|
278
324
|
- If Jenkins failed then was fixed, also record failure reason and fix commit.
|
|
279
325
|
|
|
280
|
-
### 4) docs/
|
|
326
|
+
### 4) docs/architecture/
|
|
327
|
+
- Files:
|
|
328
|
+
- `docs/architecture/structure-standard.md`
|
|
329
|
+
- `docs/architecture/adr/_TEMPLATE-ADR.md`
|
|
330
|
+
- Rule:
|
|
331
|
+
- Read the structure standard before adding or relocating code.
|
|
332
|
+
- Create an ADR for decisions that affect long-term structure, module boundaries, framework-like helpers, or major tradeoffs.
|
|
333
|
+
|
|
334
|
+
### 5) docs/reviews/
|
|
335
|
+
- Files:
|
|
336
|
+
- `docs/reviews/project-health-baseline.md`
|
|
337
|
+
- `docs/reviews/optimization-backlog.md`
|
|
338
|
+
- Rule:
|
|
339
|
+
- Structure and optimization reviews must read these before listing findings.
|
|
340
|
+
- Accepted debt is not a fresh blocker unless it worsened or needs priority upgrade.
|
|
341
|
+
|
|
342
|
+
### 6) docs/design/
|
|
281
343
|
- Purpose: DD for cross-module / API / DB / deployment / Jenkins / key-page-flow changes.
|
|
282
344
|
- How to record:
|
|
283
345
|
- Small changes do not need a standalone DD file.
|
|
284
346
|
- Higher-risk changes create `docs/design/<TASK_ID>-<slug>.md`.
|
|
285
347
|
|
|
286
|
-
###
|
|
348
|
+
### 7) docs/interfaces/
|
|
287
349
|
- Files:
|
|
288
350
|
- `docs/interfaces/api.md`
|
|
289
351
|
- `docs/interfaces/api-change-log.md`
|
|
290
352
|
- Rule:
|
|
291
353
|
- Any API change updates both files in the same task.
|
|
292
354
|
|
|
293
|
-
###
|
|
355
|
+
### 8) docs/testing/regression-matrix.md
|
|
294
356
|
- Purpose: on-demand regression evidence, not default gate for every small change.
|
|
295
357
|
- Rule:
|
|
296
358
|
- Only real executed items can be marked `PASS`.
|
|
297
359
|
- `check-matrix` is used only when full regression is explicitly required.
|
|
298
360
|
|
|
299
|
-
###
|
|
361
|
+
### 9) docs/tasks/summaries/
|
|
300
362
|
- Purpose: optional long-form summary.
|
|
301
363
|
- Rule:
|
|
302
364
|
- Only for high-risk changes, milestones, or tasks that need full retrospective.
|
|
@@ -9,19 +9,22 @@ developer_instructions = """
|
|
|
9
9
|
|
|
10
10
|
工作要求:
|
|
11
11
|
1. 优先用 rg / git / 项目脚本快速定位真实入口,再向下追踪调用链。
|
|
12
|
-
2.
|
|
13
|
-
3.
|
|
14
|
-
4.
|
|
12
|
+
2. 先读项目已有文档、配置、路由、任务记录;涉及结构/优化时还要读结构标准、健康基线和优化 backlog。
|
|
13
|
+
3. 输出根因时说明当前代码应归属的层级、现有同类模块、可复用 helper / 组件 / 脚本。
|
|
14
|
+
4. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
|
|
15
|
+
5. 输出内容必须尽量具体到:
|
|
15
16
|
- 文件路径
|
|
16
17
|
- 函数名 / 方法名
|
|
17
18
|
- 关键结构体 / 类 / 接口
|
|
18
19
|
- 关键配置项
|
|
19
|
-
|
|
20
|
-
|
|
20
|
+
6. 不要泛泛而谈,不要直接给大段修复方案。
|
|
21
|
+
7. 输出格式:
|
|
21
22
|
- 问题入口
|
|
22
23
|
- 调用链
|
|
23
24
|
- 关键文件
|
|
25
|
+
- 当前层级 / 归属模块
|
|
26
|
+
- 既有复用点
|
|
24
27
|
- 根因候选
|
|
25
28
|
- 建议交给哪个代理继续处理
|
|
26
|
-
|
|
29
|
+
8. 优先快速精准搜索,避免全仓库无差别扫描。
|
|
27
30
|
"""
|
|
@@ -12,14 +12,16 @@ developer_instructions = """
|
|
|
12
12
|
2. 坚持“最小可辩护修改”原则。
|
|
13
13
|
3. 除非明确要求,否则不要重构、不做大面积改名、不改无关文件。
|
|
14
14
|
4. 先跟随项目现有模式、helper、组件、脚本和文档约束,不新造不必要抽象。
|
|
15
|
-
5.
|
|
16
|
-
6.
|
|
17
|
-
7.
|
|
18
|
-
8.
|
|
19
|
-
9.
|
|
15
|
+
5. 改代码前先确认业务层、应用层、基础设施层、接口/UI层、shared/tooling 的正确落位;不要把新职责塞进已经偏大的文件。
|
|
16
|
+
6. 新增工具、并发/缓存/请求封装、格式转换、权限判断、校验逻辑前,先搜索既有 helper、库、组件和脚本。
|
|
17
|
+
7. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
|
|
18
|
+
8. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
|
|
19
|
+
9. 如果修改涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界,交给 reviewer / 安全能力做只读复核。
|
|
20
|
+
10. 修改后运行聚焦门禁:优先项目 light gate,其次 structure-check、相关测试、typecheck、lint、git diff --check。
|
|
21
|
+
11. 修改后输出:
|
|
20
22
|
- 修改文件
|
|
21
23
|
- 修改点
|
|
22
24
|
- 修改原因
|
|
23
25
|
- 验证方法
|
|
24
|
-
|
|
26
|
+
12. 如发现问题超出小修范围,要立即停止并上报,不要自行扩大战场。
|
|
25
27
|
"""
|
|
@@ -9,14 +9,15 @@ developer_instructions = """
|
|
|
9
9
|
|
|
10
10
|
工作要求:
|
|
11
11
|
1. 优先检查:正确性、安全性、边界条件、异常路径、并发风险、事务一致性、缓存一致性、兼容性。
|
|
12
|
-
2.
|
|
13
|
-
3.
|
|
14
|
-
4.
|
|
15
|
-
5.
|
|
12
|
+
2. 结构/优化 review 必须先读 project-health-baseline 和 optimization-backlog;不要把 accepted debt 重新报告为当前 blocker。
|
|
13
|
+
3. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
|
|
14
|
+
4. 以 git diff、相关测试、接口契约、真实运行证据、结构标准为基础,不凭风格偏好输出问题。
|
|
15
|
+
5. 优先输出真实问题,不要输出样式洁癖式意见。
|
|
16
|
+
6. 每条问题尽量包含:
|
|
16
17
|
- 问题点
|
|
17
18
|
- 影响范围
|
|
18
19
|
- 复现条件
|
|
19
20
|
- 建议修法
|
|
20
|
-
|
|
21
|
-
|
|
21
|
+
7. 发现测试不足时,指出应补哪些测试或验证路径。
|
|
22
|
+
8. 结论要按严重程度排序:P0 / P1 / P2 / P3,并明确是否影响当前任务完成。
|
|
22
23
|
"""
|
|
@@ -79,6 +79,8 @@ This contains all manual fields:
|
|
|
79
79
|
- `workflow.mode`
|
|
80
80
|
- `commands.*`
|
|
81
81
|
- `gate.*`
|
|
82
|
+
- `structure.*`
|
|
83
|
+
- `optimization.*`
|
|
82
84
|
- `runtime.*` (only for optional local diagnostics)
|
|
83
85
|
- `target_env.*`
|
|
84
86
|
- `jenkins.*`
|
|
@@ -126,13 +128,14 @@ Read `workflow.mode` from `docs/ENGINEERING.md` before choosing the path.
|
|
|
126
128
|
`dev` mode:
|
|
127
129
|
|
|
128
130
|
1) read `docs/ENGINEERING.md`
|
|
129
|
-
2) read
|
|
130
|
-
3)
|
|
131
|
-
4)
|
|
132
|
-
5)
|
|
133
|
-
6)
|
|
134
|
-
7)
|
|
135
|
-
8)
|
|
131
|
+
2) read `docs/architecture/structure-standard.md` when the change adds or relocates code
|
|
132
|
+
3) read / update `docs/tasks/taskbook.md`
|
|
133
|
+
4) write minimal design notes; create a DD or ADR only when the change is cross-module, API, DB, deployment, Jenkins, key-page-flow, or long-term structure related
|
|
134
|
+
5) implement only the necessary changes
|
|
135
|
+
6) run the default local lightweight gate
|
|
136
|
+
7) append `docs/tasks/closure-log.md` with `Result: DEV-CLOSED`
|
|
137
|
+
8) commit + push
|
|
138
|
+
9) stop and start the next development task
|
|
136
139
|
|
|
137
140
|
`verify` mode:
|
|
138
141
|
|
|
@@ -151,6 +154,7 @@ Default commands:
|
|
|
151
154
|
```bash
|
|
152
155
|
python3 docs/tools/autopipeline/ap.py doctor
|
|
153
156
|
python3 docs/tools/autopipeline/ap.py impact --scope auto
|
|
157
|
+
python3 docs/tools/autopipeline/ap.py structure-check --scope auto
|
|
154
158
|
python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
|
|
155
159
|
python3 docs/tools/autopipeline/ap.py light-gate --scope full
|
|
156
160
|
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
|
|
@@ -164,14 +168,27 @@ On-demand commands:
|
|
|
164
168
|
python3 docs/tools/autopipeline/ap.py runtime-up
|
|
165
169
|
python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
|
|
166
170
|
python3 docs/tools/autopipeline/ap.py runtime-down
|
|
171
|
+
python3 docs/tools/autopipeline/ap.py structure-check --scope full
|
|
167
172
|
python3 docs/tools/autopipeline/ap.py check-matrix
|
|
168
173
|
python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
|
|
169
174
|
```
|
|
170
175
|
|
|
176
|
+
## Engineering structure policy
|
|
177
|
+
|
|
178
|
+
- Before coding, locate the existing layer, module owner, helper APIs, scripts, and tests for the behavior being changed.
|
|
179
|
+
- Put new code in the correct layer: domain rules stay out of controllers/pages, orchestration belongs in application/service/usecase code, external systems belong behind infrastructure adapters, and UI components should not own deep business workflows.
|
|
180
|
+
- Reuse before building: search existing utilities, components, clients, validation, permissions, caching, retry, formatting, and automation scripts before adding another helper.
|
|
181
|
+
- Do not add new responsibilities to large files. If a file exceeds `structure.max_file_lines_warn`, prefer extracting a focused module or component; if it exceeds `structure.max_file_lines_block`, only small fixes are acceptable unless the path is explicitly allowed.
|
|
182
|
+
- Historical large files can be listed in `structure.accepted_debt_paths` only after they are recorded in the health baseline or optimization backlog; this does not permit large new additions to those files.
|
|
183
|
+
- Self-built algorithms, concurrency controls, caches, protocol clients, or framework-like helpers require a concrete reason such as performance, concurrency, offline/deploy constraints, licensing, security, or compatibility, plus tests or benchmark/runtime evidence.
|
|
184
|
+
- For structural reviews, read `docs/reviews/project-health-baseline.md` and `docs/reviews/optimization-backlog.md` first. Do not re-report accepted debt as a fresh blocker; report only new, worsened, unrecorded P0/P1, or backlog items that now deserve priority upgrade.
|
|
185
|
+
- “Optimization complete” means the scoped P0/P1/P2 work is closed, local gate passes, no new unclassified P0/P1 exists, and remaining P2/P3 work is tracked or accepted debt.
|
|
186
|
+
|
|
171
187
|
## Quality policy
|
|
172
188
|
|
|
173
189
|
- Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/Jenkins checks.
|
|
174
190
|
- For small-step development, prefer the generic impact-aware gate: `light-gate --scope auto`. The skill provides the gate engine; each project owns its commands and optional `gate.rules` path mapping in `docs/ENGINEERING.md`.
|
|
191
|
+
- `light-gate` automatically runs `structure-check` when `structure.enabled: true` or `commands.structure_check` is configured.
|
|
175
192
|
- Keep `standard` as the backward-compatible default when no `gate.*` policy is configured. Use `changed` only when project commands/rules make the reduced scope explicit.
|
|
176
193
|
- Automatically upgrade to `full` for CI/deploy/build-tool/lockfile/autopipeline config changes, project-declared full rules, unknown impact when configured, or release/verify tasks.
|
|
177
194
|
- `workflow.mode: dev` closes development after light gate, closure record, commit, and push.
|
|
@@ -16,6 +16,7 @@ commands:
|
|
|
16
16
|
gate_changed: ""
|
|
17
17
|
gate_standard: ""
|
|
18
18
|
gate_full: ""
|
|
19
|
+
structure_check: ""
|
|
19
20
|
light_gate: ""
|
|
20
21
|
build: ""
|
|
21
22
|
test: ""
|
|
@@ -53,6 +54,46 @@ gate:
|
|
|
53
54
|
- "settings.gradle*"
|
|
54
55
|
rules: []
|
|
55
56
|
|
|
57
|
+
structure:
|
|
58
|
+
enabled: true
|
|
59
|
+
architecture_standard: "clean-architecture-ddd-lite"
|
|
60
|
+
max_file_lines_warn: 800
|
|
61
|
+
max_file_lines_block: 1500
|
|
62
|
+
max_function_lines_warn: 120
|
|
63
|
+
max_added_lines_to_large_file: 80
|
|
64
|
+
require_reuse_search: true
|
|
65
|
+
block_new_responsibility_in_large_file: true
|
|
66
|
+
allow_large_files:
|
|
67
|
+
- ".agents/skills/**"
|
|
68
|
+
- ".claude/skills/**"
|
|
69
|
+
- "docs/tools/autopipeline/**"
|
|
70
|
+
- "generated/**"
|
|
71
|
+
- "**/generated/**"
|
|
72
|
+
- "**/__generated__/**"
|
|
73
|
+
- "vendor/**"
|
|
74
|
+
- "dist/**"
|
|
75
|
+
- "build/**"
|
|
76
|
+
- "target/**"
|
|
77
|
+
- "node_modules/**"
|
|
78
|
+
- "**/*.generated.*"
|
|
79
|
+
- "**/*.gen.*"
|
|
80
|
+
- "**/*.min.js"
|
|
81
|
+
- "**/*.bundle.js"
|
|
82
|
+
- "**/*.map"
|
|
83
|
+
accepted_debt_paths: []
|
|
84
|
+
reusable_tool_dirs:
|
|
85
|
+
- "docs/tools/**"
|
|
86
|
+
- "scripts/**"
|
|
87
|
+
- "tools/**"
|
|
88
|
+
- "packages/*/src/**"
|
|
89
|
+
- "src/**/shared/**"
|
|
90
|
+
- "src/**/utils/**"
|
|
91
|
+
|
|
92
|
+
optimization:
|
|
93
|
+
completion_policy: "baseline-aware"
|
|
94
|
+
require_baseline_for_global_review: true
|
|
95
|
+
report_accepted_debt_as_findings: false
|
|
96
|
+
|
|
56
97
|
runtime:
|
|
57
98
|
docker_compose_file: ""
|
|
58
99
|
docker_service: ""
|
|
@@ -92,6 +133,10 @@ docs:
|
|
|
92
133
|
closure_log: "docs/tasks/closure-log.md"
|
|
93
134
|
design_dir: "docs/design"
|
|
94
135
|
review_dir: "docs/reviews"
|
|
136
|
+
health_baseline: "docs/reviews/project-health-baseline.md"
|
|
137
|
+
optimization_backlog: "docs/reviews/optimization-backlog.md"
|
|
138
|
+
structure_standard: "docs/architecture/structure-standard.md"
|
|
139
|
+
adr_dir: "docs/architecture/adr"
|
|
95
140
|
api_doc: "docs/interfaces/api.md"
|
|
96
141
|
api_change_log: "docs/interfaces/api-change-log.md"
|
|
97
142
|
regression_matrix: "docs/testing/regression-matrix.md"
|
|
@@ -130,6 +175,10 @@ docs:
|
|
|
130
175
|
- `workflow.mode`:`dev` 或 `verify`,默认推荐 `dev`
|
|
131
176
|
- `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`:推荐配置分层门禁命令;旧项目也可以继续只配置 `commands.light_gate`
|
|
132
177
|
- `gate.*`:按项目声明路径规则和高风险升级规则;未配置时保持标准门禁行为
|
|
178
|
+
- `commands.structure_check`:可覆盖内置结构检查;留空时使用通用 `ap.py structure-check`
|
|
179
|
+
- `structure.*`:通用工程结构阈值、允许的大文件模式、复用搜索目录
|
|
180
|
+
- `optimization.*`:健康基线感知的优化闭环口径,避免重复把已接受债务判定为当前未完成
|
|
181
|
+
- `docs.health_baseline` / `docs.optimization_backlog` / `docs.structure_standard` / `docs.adr_dir`:项目结构治理文档位置
|
|
133
182
|
- `target_env.*`:目标环境前端 / 后端地址、用户名、密码引用,必须全部填写且真实可用
|
|
134
183
|
- `jenkins.*`:Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境,必须全部填写且真实可用
|
|
135
184
|
|
|
@@ -169,6 +218,12 @@ docs:
|
|
|
169
218
|
按需填写:
|
|
170
219
|
- `gate.default_scope`:默认 `standard`;需要小步快跑时设为 `auto` 或 `changed`
|
|
171
220
|
- `gate.rules`:项目自定义路径规则。每条规则可包含 `name`、`paths`、`commands`、`scope`
|
|
221
|
+
- `structure.enabled`:是否把结构检查纳入 `light-gate`
|
|
222
|
+
- `structure.max_file_lines_warn` / `structure.max_file_lines_block`:文件长度预警 / 阻塞阈值
|
|
223
|
+
- `structure.max_added_lines_to_large_file`:禁止在已偏大的文件里继续大块堆职责
|
|
224
|
+
- `structure.allow_large_files`:生成物、供应商代码、构建产物等允许超长或跳过结构检查的路径
|
|
225
|
+
- `structure.accepted_debt_paths`:已记录为接受债务的历史大文件;只豁免历史体量,不豁免继续大幅新增
|
|
226
|
+
- `optimization.completion_policy`:默认 `baseline-aware`,表示“优化完成”按本轮范围和已记录基线判断,不等于仓库没有任何可优化点
|
|
172
227
|
- `runtime.*`:仅在本地运行诊断时使用
|
|
173
228
|
- `commands.build` / `commands.test` / `commands.quick_test` / `commands.lint` / `commands.typecheck` / `commands.format`:按项目实际情况保留
|
|
174
229
|
|
|
@@ -269,6 +324,36 @@ docs:
|
|
|
269
324
|
|
|
270
325
|
---
|
|
271
326
|
|
|
327
|
+
## 1.7 工程结构与优化标准
|
|
328
|
+
|
|
329
|
+
默认采用 `docs/architecture/structure-standard.md` 中的通用结构标准。具体项目可以按技术栈细化目录名,但不得降低以下要求:
|
|
330
|
+
|
|
331
|
+
1) 分层清晰
|
|
332
|
+
- 业务规则、用例编排、外部适配、接口入口、共享工具必须有清晰边界。
|
|
333
|
+
- 新代码先落到对应层;没有合适位置时,先补最小设计或 ADR,再新增目录 / 模块。
|
|
334
|
+
|
|
335
|
+
2) 复用优先
|
|
336
|
+
- 新增工具、并发控制、缓存、请求封装、格式转换、权限判断、校验逻辑前,必须先搜索已有 helper、库、组件、脚本。
|
|
337
|
+
- 正常情况下复用成熟库或项目既有工具;只有明确的性能、并发、部署、许可证、兼容性约束才允许自研,并记录理由和验证。
|
|
338
|
+
|
|
339
|
+
3) 单文件容量控制
|
|
340
|
+
- 超过 `structure.max_file_lines_warn` 的文件只允许小修和缺陷修复,新增职责应优先抽取模块。
|
|
341
|
+
- 超过 `structure.max_file_lines_block` 的文件不得继续承载新职责,除非该文件在 `structure.allow_large_files` 中声明为生成物或外部产物。
|
|
342
|
+
- 已记录为接受债务的历史大文件可放入 `structure.accepted_debt_paths`,但继续大幅新增仍会被阻塞。
|
|
343
|
+
- 对已偏大的文件一次性增加超过 `structure.max_added_lines_to_large_file` 行时,`structure-check` 会阻塞,要求拆分或写明例外理由。
|
|
344
|
+
|
|
345
|
+
4) 优化完成标准
|
|
346
|
+
- “优化完成”不表示仓库没有任何可优化点。
|
|
347
|
+
- 默认定义为:本轮约定范围内的 P0/P1/P2 scoped items 已闭环,本地 gate 通过,没有新增未分级 P0/P1,剩余 P2/P3 已进入 backlog 或被接受为债务。
|
|
348
|
+
- 新会话做整体分析时,必须先读 `docs/reviews/project-health-baseline.md` 和 `docs/reviews/optimization-backlog.md`,只报告新增、恶化、未记录 P0/P1,或已记录但需要升级优先级的问题。
|
|
349
|
+
|
|
350
|
+
5) 本地执行
|
|
351
|
+
- 小步快跑默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope auto`
|
|
352
|
+
- 发布、跨模块重构、架构调整默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope full`
|
|
353
|
+
- `light-gate` 在 `structure.enabled: true` 时会自动纳入结构检查;如项目需要更强规则,可配置 `commands.structure_check` 覆盖内置实现。
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
272
357
|
## 2. 标准流程(默认)
|
|
273
358
|
|
|
274
359
|
### 2.1 开发模式:`workflow.mode: "dev"`
|
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
|
|
2
|
+
Before code changes, read the configured structure standard and place new code in the correct layer; do not add new responsibilities to already-large files.
|
|
3
|
+
Before optimization reviews, read the project health baseline and optimization backlog, and report only new, worsened, unrecorded P0/P1, or upgraded-priority items.
|
|
2
4
|
Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
|
|
3
5
|
Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
|
|
4
|
-
Default to the lightweight local gate first
|
|
6
|
+
Default to the lightweight local gate first; when `structure.enabled` is true, the gate includes `structure-check`.
|
|
7
|
+
Use Jenkins build verification and real target-environment verification as the primary completion gate in verify mode.
|
|
5
8
|
Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
|
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
|
|
2
|
+
Before code changes, read the configured structure standard and place new code in the correct layer; do not add new responsibilities to already-large files.
|
|
3
|
+
Before optimization reviews, read the project health baseline and optimization backlog, and report only new, worsened, unrecorded P0/P1, or upgraded-priority items.
|
|
2
4
|
Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
|
|
3
5
|
Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
|
|
4
|
-
Default to the lightweight local gate first
|
|
6
|
+
Default to the lightweight local gate first; when `structure.enabled` is true, the gate includes `structure-check`.
|
|
7
|
+
Use Jenkins build verification and real target-environment verification as the primary completion gate in verify mode.
|
|
5
8
|
Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# ADR-0000 — <Decision Title>
|
|
2
|
+
|
|
3
|
+
- Status: Proposed | Accepted | Superseded
|
|
4
|
+
- Date: YYYY-MM-DD
|
|
5
|
+
- Owner: <name / team>
|
|
6
|
+
- Related task: <task id / link>
|
|
7
|
+
|
|
8
|
+
## 1. Context
|
|
9
|
+
|
|
10
|
+
What problem or structural pressure requires an architectural decision?
|
|
11
|
+
|
|
12
|
+
## 2. Decision
|
|
13
|
+
|
|
14
|
+
What decision is being made? Keep it specific and actionable.
|
|
15
|
+
|
|
16
|
+
## 3. Alternatives Considered
|
|
17
|
+
|
|
18
|
+
| Option | Pros | Cons | Reason not selected |
|
|
19
|
+
| --- | --- | --- | --- |
|
|
20
|
+
| A | | | |
|
|
21
|
+
| B | | | |
|
|
22
|
+
|
|
23
|
+
## 4. Consequences
|
|
24
|
+
|
|
25
|
+
- Positive:
|
|
26
|
+
- Negative / tradeoffs:
|
|
27
|
+
- Migration impact:
|
|
28
|
+
- Compatibility impact:
|
|
29
|
+
|
|
30
|
+
## 5. Validation
|
|
31
|
+
|
|
32
|
+
- Tests:
|
|
33
|
+
- Gate:
|
|
34
|
+
- Runtime / benchmark / security evidence:
|
|
35
|
+
|
|
36
|
+
## 6. Rollback
|
|
37
|
+
|
|
38
|
+
How can this decision be reverted or superseded if it proves wrong?
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Project Structure Standard
|
|
2
|
+
|
|
3
|
+
> 通用工程结构标准。项目可以按技术栈调整目录名,但不能降低分层、复用、可维护性和验证要求。
|
|
4
|
+
|
|
5
|
+
## 1. 目标
|
|
6
|
+
|
|
7
|
+
- 目录结构能表达业务边界、技术边界和变更边界。
|
|
8
|
+
- 单个文件、类、组件、函数只承担清晰职责。
|
|
9
|
+
- 新代码优先复用成熟库、项目已有 helper、组件、脚本和平台能力。
|
|
10
|
+
- 优化结论按健康基线和 backlog 判断,避免反复把已接受债务当成当前阻塞。
|
|
11
|
+
|
|
12
|
+
## 2. 推荐分层
|
|
13
|
+
|
|
14
|
+
不同语言和框架可以使用不同目录名,但职责应保持一致:
|
|
15
|
+
|
|
16
|
+
| 层级 | 常见目录名 | 职责 | 不应包含 |
|
|
17
|
+
| --- | --- | --- | --- |
|
|
18
|
+
| Domain | `domain`, `model`, `entity`, `value-object`, `policy` | 业务概念、规则、不可变约束 | HTTP、DB、UI、第三方 SDK 细节 |
|
|
19
|
+
| Application | `application`, `service`, `usecase`, `workflow` | 用例编排、事务边界、跨领域协调 | 控制器入参解析、SQL 细节、组件渲染 |
|
|
20
|
+
| Infrastructure | `infrastructure`, `adapter`, `repository`, `client`, `gateway` | DB、缓存、消息、外部 API、文件系统、运行时适配 | 核心业务规则 |
|
|
21
|
+
| Interface | `api`, `controller`, `handler`, `route`, `page`, `component`, `view` | HTTP/CLI/UI 入口、协议转换、展示逻辑 | 复杂业务编排和持久化细节 |
|
|
22
|
+
| Shared | `shared`, `common`, `utils`, `lib` | 稳定通用工具、类型、组件 | 业务专属逻辑、临时拼凑函数 |
|
|
23
|
+
| Tooling | `scripts`, `tools`, `docs/tools` | 自动化脚本、门禁、迁移辅助 | 在线业务运行逻辑 |
|
|
24
|
+
|
|
25
|
+
## 3. 落位规则
|
|
26
|
+
|
|
27
|
+
- 修改前先定位现有同类实现、模块边界、调用链和测试入口。
|
|
28
|
+
- 新增业务规则优先进入 Domain 或 Application,不直接塞进 Controller/Page/Component。
|
|
29
|
+
- 新增外部依赖访问优先进入 Infrastructure,并通过接口或窄适配暴露给 Application。
|
|
30
|
+
- UI 组件应拆分为容器、状态/数据适配、纯展示组件;不要在单个页面里混合远程请求、权限、复杂计算和大段渲染。
|
|
31
|
+
- 跨模块、跨层、数据库、API、部署、权限、并发、缓存、核心页面流的变更,需要最小设计;影响长期结构的决策需要 ADR。
|
|
32
|
+
|
|
33
|
+
## 4. 文件和函数规模
|
|
34
|
+
|
|
35
|
+
默认阈值来自 `docs/ENGINEERING.md`:
|
|
36
|
+
|
|
37
|
+
- 文件超过 `structure.max_file_lines_warn`:只允许小修、缺陷修复、类型补充;新增职责应先抽取模块。
|
|
38
|
+
- 文件超过 `structure.max_file_lines_block`:不得继续承载新职责,除非是生成物、外部产物或已在 `structure.allow_large_files` 中声明。
|
|
39
|
+
- 历史大文件如果已进入健康基线 / backlog,可在 `structure.accepted_debt_paths` 中登记;登记只豁免历史体量,不豁免继续大幅新增。
|
|
40
|
+
- 函数 / 方法 / 组件超过 `structure.max_function_lines_warn`:应拆分为命名清晰的子函数、hook、service、query、mapper 或 view component。
|
|
41
|
+
- 对大文件新增超过 `structure.max_added_lines_to_large_file` 行:默认阻塞,必须拆分或记录例外理由。
|
|
42
|
+
|
|
43
|
+
## 5. 复用优先规则
|
|
44
|
+
|
|
45
|
+
新增以下能力前必须先搜索现有实现:
|
|
46
|
+
|
|
47
|
+
- HTTP/API client、认证、权限、表单校验、错误处理、日志、缓存、重试、并发控制。
|
|
48
|
+
- 日期、金额、单位、国际化、文件处理、导入导出、分页、排序、过滤、权限判断。
|
|
49
|
+
- UI 基础组件、布局、表格、弹窗、上传、图表、状态管理、路由守卫。
|
|
50
|
+
- 自动化脚本、部署脚本、测试工具、mock、fixture、数据迁移 helper。
|
|
51
|
+
|
|
52
|
+
允许自研的前提:
|
|
53
|
+
|
|
54
|
+
- 成熟库不能满足性能、并发、部署、许可证、离线、兼容性或安全边界。
|
|
55
|
+
- ADR 或设计记录说明取舍。
|
|
56
|
+
- 有测试、benchmark、压测或真实运行证据支撑。
|
|
57
|
+
|
|
58
|
+
## 6. Review 口径
|
|
59
|
+
|
|
60
|
+
结构 review 不应只说“还能优化”。必须分级:
|
|
61
|
+
|
|
62
|
+
- P0 阻塞:构建 / 发布 / 数据 / 安全 / 核心流程风险。
|
|
63
|
+
- P1 必修:明显架构违规、契约漂移、重要测试缺失、近期高风险改动。
|
|
64
|
+
- P2 计划债务:大文件、热点目录、可拆分模块、测试增强。
|
|
65
|
+
- P3 可选建议:命名、风格、进一步抽象、审美类优化。
|
|
66
|
+
|
|
67
|
+
“优化完成”只表示当前约定范围闭环,不表示没有任何后续可优化点。新会话必须先读健康基线和 backlog,只报告新增、恶化、未记录 P0/P1,或需要升级优先级的已记录问题。
|
|
@@ -8,10 +8,16 @@
|
|
|
8
8
|
## 2. 范围与非目标
|
|
9
9
|
## 3. 现状与问题
|
|
10
10
|
## 4. 方案与取舍
|
|
11
|
-
## 5.
|
|
12
|
-
|
|
11
|
+
## 5. 架构落位与复用检查
|
|
12
|
+
- 目标层级:Domain / Application / Infrastructure / Interface / Shared / Tooling
|
|
13
|
+
- 既有复用点:
|
|
14
|
+
- 是否需要 ADR:Yes / No;如 Yes,记录到 `docs/architecture/adr/`
|
|
15
|
+
- 是否触及大文件 / 大组件:
|
|
13
16
|
|
|
14
|
-
##
|
|
17
|
+
## 6. 接口设计(与 docs/interfaces/api.md 对齐)
|
|
18
|
+
## 7. 数据设计(迁移/回滚)
|
|
19
|
+
|
|
20
|
+
## 8. 时序图(强制)
|
|
15
21
|
```mermaid
|
|
16
22
|
sequenceDiagram
|
|
17
23
|
participant C as Client
|
|
@@ -26,7 +32,7 @@ sequenceDiagram
|
|
|
26
32
|
A-->>C: response
|
|
27
33
|
```
|
|
28
34
|
|
|
29
|
-
##
|
|
35
|
+
## 9. ER 图(强制)
|
|
30
36
|
```mermaid
|
|
31
37
|
erDiagram
|
|
32
38
|
ENTITY_A ||--o{ ENTITY_B : relates
|
|
@@ -34,10 +40,10 @@ erDiagram
|
|
|
34
40
|
ENTITY_B { string id string a_id }
|
|
35
41
|
```
|
|
36
42
|
|
|
37
|
-
##
|
|
38
|
-
##
|
|
39
|
-
##
|
|
40
|
-
##
|
|
41
|
-
##
|
|
42
|
-
##
|
|
43
|
-
##
|
|
43
|
+
## 10. 接口时序/调用编排(强制)
|
|
44
|
+
## 11. 测试方案(必须自动化 + 覆盖历史 bug)
|
|
45
|
+
## 12. 安全与合规
|
|
46
|
+
## 13. 性能与容量
|
|
47
|
+
## 14. 风险清单
|
|
48
|
+
## 15. 回滚方案
|
|
49
|
+
## 16. 影响面与发布计划
|
|
@@ -3,22 +3,32 @@
|
|
|
3
3
|
> 仅在任务需要独立 review 记录时使用;不是每个小改动的默认强制文档。
|
|
4
4
|
|
|
5
5
|
## 1. 静态分析结果
|
|
6
|
-
- Command:light_gate / diff_check / verify_api_docs / verify_jenkins
|
|
6
|
+
- Command:structure-check / light_gate / diff_check / verify_api_docs / verify_jenkins
|
|
7
7
|
- Summary:
|
|
8
8
|
- Issues:
|
|
9
9
|
|
|
10
|
-
## 2.
|
|
10
|
+
## 2. 结构与优化基线
|
|
11
|
+
- Structure standard:`docs/architecture/structure-standard.md`
|
|
12
|
+
- Health baseline read:Yes / No / N/A
|
|
13
|
+
- Optimization backlog read:Yes / No / N/A
|
|
14
|
+
- New / worsened issues:
|
|
15
|
+
- Accepted debt not repeated:
|
|
16
|
+
- Completion standard:Met / Not met / N/A
|
|
17
|
+
|
|
18
|
+
## 3. 本地轻量校验
|
|
11
19
|
- light_gate or quick_test/test/build:
|
|
20
|
+
- structure-check:
|
|
12
21
|
- api docs:
|
|
13
22
|
- jenkins:
|
|
14
23
|
|
|
15
|
-
##
|
|
24
|
+
## 4. 按需本地运行验证(如果有)
|
|
16
25
|
- runtime-up / health:
|
|
17
26
|
|
|
18
|
-
##
|
|
27
|
+
## 5. Jenkins 与目标环境
|
|
19
28
|
- Jenkins readiness:
|
|
20
29
|
- Target env verification:
|
|
21
30
|
|
|
22
|
-
##
|
|
31
|
+
## 6. 风险与结论
|
|
23
32
|
- Risk:
|
|
24
|
-
-
|
|
33
|
+
- Priority:P0 / P1 / P2 / P3 / N/A
|
|
34
|
+
- Conclusion:Pass / Blocked / Accepted debt
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Optimization Backlog
|
|
2
|
+
|
|
3
|
+
> 这里记录持续优化项。被记录为 `accepted-debt` 的项目不等于当前任务未完成;只有新增、恶化或升级优先级时才需要重新报告。
|
|
4
|
+
|
|
5
|
+
## Status Values
|
|
6
|
+
|
|
7
|
+
- `open`: 已确认,等待排期。
|
|
8
|
+
- `accepted-debt`: 当前接受的债务,按触发条件再处理。
|
|
9
|
+
- `in-progress`: 正在处理。
|
|
10
|
+
- `closed`: 已闭环,证据写在表格中。
|
|
11
|
+
- `superseded`: 被其他方案或任务替代。
|
|
12
|
+
|
|
13
|
+
## Backlog
|
|
14
|
+
|
|
15
|
+
| ID | Priority | Status | Scope | Item | Reason | Acceptance | Last reviewed |
|
|
16
|
+
| --- | --- | --- | --- | --- | --- | --- | --- |
|
|
17
|
+
| OPT-000 | P2 | open | `<path/module>` | | | | YYYY-MM-DD |
|
|
18
|
+
|
|
19
|
+
## Review Rules
|
|
20
|
+
|
|
21
|
+
- P0/P1 不能长期停留在 backlog;应进入当前迭代或明确升级。
|
|
22
|
+
- P2 可以排队,但必须有范围、原因和验收标准。
|
|
23
|
+
- P3 只在低成本或同域修改时顺手处理,不影响“优化完成”结论。
|
|
24
|
+
- 新会话整体分析只允许新增、升级或关闭条目,不要重复制造同义优化项。
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Project Health Baseline
|
|
2
|
+
|
|
3
|
+
> 用于固定“当前项目结构是否达标”的判断口径。整体分析、结构优化和新会话复盘必须先读本文件,再读 `docs/reviews/optimization-backlog.md`。
|
|
4
|
+
|
|
5
|
+
- Baseline date: YYYY-MM-DD
|
|
6
|
+
- Baseline commit: `<git-sha>`
|
|
7
|
+
- Owner: <name / team>
|
|
8
|
+
- Review scope: <repo / module / subsystem>
|
|
9
|
+
- Standard: `docs/architecture/structure-standard.md`
|
|
10
|
+
|
|
11
|
+
## 1. Current Accepted Structure
|
|
12
|
+
|
|
13
|
+
记录当前被接受的目录结构、主要模块边界、已知历史原因和不再重复争论的事实。
|
|
14
|
+
|
|
15
|
+
| Area | Current state | Accepted because | Review date |
|
|
16
|
+
| --- | --- | --- | --- |
|
|
17
|
+
| <module/path> | | | |
|
|
18
|
+
|
|
19
|
+
## 2. Closed Optimization Scope
|
|
20
|
+
|
|
21
|
+
记录已经闭环的优化项。新会话不能把这些项重复判定为“当前未完成”。
|
|
22
|
+
|
|
23
|
+
| ID | Closed date | Scope | Acceptance evidence |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| OPT-000 | YYYY-MM-DD | | |
|
|
26
|
+
|
|
27
|
+
## 3. Accepted Debt
|
|
28
|
+
|
|
29
|
+
这些是已知但暂不处理的问题。除非新增风险、影响扩大或优先级升级,否则只保留在 backlog,不作为当前任务失败原因。
|
|
30
|
+
|
|
31
|
+
| ID | Priority | Scope | Debt | Why accepted | Revisit trigger |
|
|
32
|
+
| --- | --- | --- | --- | --- | --- |
|
|
33
|
+
| DEBT-000 | P2 | | | | |
|
|
34
|
+
|
|
35
|
+
## 4. Priority Rules
|
|
36
|
+
|
|
37
|
+
- P0: blocks build, release, deploy, core user flow, data integrity, security, or compliance.
|
|
38
|
+
- P1: clear architectural violation, contract drift, missing test around high-risk change, or recently introduced maintainability risk.
|
|
39
|
+
- P2: planned debt such as large files, hot directories, module extraction, stronger tests, or tool consolidation.
|
|
40
|
+
- P3: optional naming, style, polish, or further abstraction.
|
|
41
|
+
|
|
42
|
+
## 5. Completion Standard
|
|
43
|
+
|
|
44
|
+
An optimization task is complete when all are true:
|
|
45
|
+
|
|
46
|
+
- The scoped P0/P1/P2 items listed for this task are closed.
|
|
47
|
+
- Local gate passed, including structure check when enabled.
|
|
48
|
+
- No new unclassified P0/P1 was introduced.
|
|
49
|
+
- Remaining P2/P3 items are either in `docs/reviews/optimization-backlog.md` or accepted debt above.
|
|
50
|
+
- Review output says explicitly whether the project meets this baseline.
|
|
51
|
+
|
|
52
|
+
## 6. New Review Instructions
|
|
53
|
+
|
|
54
|
+
When asked to analyze structure or optimization:
|
|
55
|
+
|
|
56
|
+
- Read this baseline first.
|
|
57
|
+
- Read `docs/reviews/optimization-backlog.md` second.
|
|
58
|
+
- Report only:
|
|
59
|
+
- new or worsened issues;
|
|
60
|
+
- unrecorded P0/P1;
|
|
61
|
+
- backlog items whose priority should now be upgraded;
|
|
62
|
+
- baseline drift.
|
|
63
|
+
- Do not repeat accepted debt as fresh findings.
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
- Jenkins Build: <build url>
|
|
16
16
|
- Target Env: <env name / health url / page path>
|
|
17
17
|
- Verification: <health / key api / key page / business path>
|
|
18
|
+
- Structure Check: <passed / blocked / skipped with reason>
|
|
18
19
|
- Result: DEV-CLOSED / PASS / FAIL / PARTIAL
|
|
19
20
|
- Follow-up: <none or todo>
|
|
20
21
|
- Jenkins Failure: <optional>
|
|
@@ -15,6 +15,9 @@
|
|
|
15
15
|
- 是否高风险(Yes/No):
|
|
16
16
|
- 高风险分类(如有):DB / Auth / Payment / Jenkins / Gateway / Upload / Prod Config
|
|
17
17
|
- 影响面(API / DB / Jenkins / Page / Config / Deploy):
|
|
18
|
+
- 结构落位(Domain / Application / Infrastructure / Interface / Shared / Tooling / N/A):
|
|
19
|
+
- 复用检查(已有 helper / 组件 / 脚本 / 库):
|
|
20
|
+
- 是否需要 ADR(Yes/No):
|
|
18
21
|
- 最小设计记录:
|
|
19
22
|
- 验收标准:
|
|
20
23
|
- 子任务(如有):
|
|
@@ -10,6 +10,7 @@ import datetime as _dt
|
|
|
10
10
|
import fnmatch
|
|
11
11
|
import json
|
|
12
12
|
import os
|
|
13
|
+
import re
|
|
13
14
|
import time
|
|
14
15
|
import urllib.parse
|
|
15
16
|
import urllib.error
|
|
@@ -468,6 +469,7 @@ def cmd_gen_summary(args: argparse.Namespace) -> None:
|
|
|
468
469
|
|
|
469
470
|
## 4. 质量证据
|
|
470
471
|
- 本地轻量校验:light_gate or quick_test/test/build / api docs / jenkins / diff-check — TODO
|
|
472
|
+
- 结构检查:structure-check — TODO
|
|
471
473
|
- Jenkins Build:TODO
|
|
472
474
|
- 目标环境验证:TODO
|
|
473
475
|
- 闭环记录:TODO
|
|
@@ -935,6 +937,362 @@ def _run_git_diff_check(repo: Path, cfg: dict) -> None:
|
|
|
935
937
|
print("[diff-check] OK")
|
|
936
938
|
|
|
937
939
|
|
|
940
|
+
_DEFAULT_STRUCTURE_ALLOW_PATTERNS = [
|
|
941
|
+
".git/**",
|
|
942
|
+
".agents/skills/**",
|
|
943
|
+
".claude/skills/**",
|
|
944
|
+
".next/**",
|
|
945
|
+
".nuxt/**",
|
|
946
|
+
".svelte-kit/**",
|
|
947
|
+
".turbo/**",
|
|
948
|
+
"coverage/**",
|
|
949
|
+
"dist/**",
|
|
950
|
+
"build/**",
|
|
951
|
+
"out/**",
|
|
952
|
+
"target/**",
|
|
953
|
+
"vendor/**",
|
|
954
|
+
"node_modules/**",
|
|
955
|
+
"generated/**",
|
|
956
|
+
"**/generated/**",
|
|
957
|
+
"**/__generated__/**",
|
|
958
|
+
"docs/tools/autopipeline/**",
|
|
959
|
+
"**/*.generated.*",
|
|
960
|
+
"**/*.gen.*",
|
|
961
|
+
"**/*.min.js",
|
|
962
|
+
"**/*.bundle.js",
|
|
963
|
+
"**/*.map",
|
|
964
|
+
"package-lock.json",
|
|
965
|
+
"pnpm-lock.yaml",
|
|
966
|
+
"yarn.lock",
|
|
967
|
+
"bun.lockb",
|
|
968
|
+
"go.sum",
|
|
969
|
+
"Cargo.lock",
|
|
970
|
+
]
|
|
971
|
+
_TEXT_SOURCE_EXTENSIONS = {
|
|
972
|
+
".bash",
|
|
973
|
+
".c",
|
|
974
|
+
".cc",
|
|
975
|
+
".cfg",
|
|
976
|
+
".conf",
|
|
977
|
+
".cpp",
|
|
978
|
+
".cs",
|
|
979
|
+
".css",
|
|
980
|
+
".go",
|
|
981
|
+
".gradle",
|
|
982
|
+
".graphql",
|
|
983
|
+
".h",
|
|
984
|
+
".hpp",
|
|
985
|
+
".html",
|
|
986
|
+
".java",
|
|
987
|
+
".js",
|
|
988
|
+
".json",
|
|
989
|
+
".jsx",
|
|
990
|
+
".kt",
|
|
991
|
+
".kts",
|
|
992
|
+
".less",
|
|
993
|
+
".m",
|
|
994
|
+
".md",
|
|
995
|
+
".mm",
|
|
996
|
+
".php",
|
|
997
|
+
".properties",
|
|
998
|
+
".py",
|
|
999
|
+
".rb",
|
|
1000
|
+
".rs",
|
|
1001
|
+
".scala",
|
|
1002
|
+
".scss",
|
|
1003
|
+
".sh",
|
|
1004
|
+
".sql",
|
|
1005
|
+
".swift",
|
|
1006
|
+
".toml",
|
|
1007
|
+
".ts",
|
|
1008
|
+
".tsx",
|
|
1009
|
+
".vue",
|
|
1010
|
+
".xml",
|
|
1011
|
+
".yaml",
|
|
1012
|
+
".yml",
|
|
1013
|
+
".zsh",
|
|
1014
|
+
}
|
|
1015
|
+
_TEXT_SOURCE_FILENAMES = {
|
|
1016
|
+
"Dockerfile",
|
|
1017
|
+
"Jenkinsfile",
|
|
1018
|
+
"Makefile",
|
|
1019
|
+
"go.mod",
|
|
1020
|
+
"package.json",
|
|
1021
|
+
"requirements.txt",
|
|
1022
|
+
"pyproject.toml",
|
|
1023
|
+
"tsconfig.json",
|
|
1024
|
+
}
|
|
1025
|
+
_FUNCTION_START_RE = re.compile(
|
|
1026
|
+
r"^\s*(?:export\s+)?(?:async\s+)?(?:def|function|func)\s+[A-Za-z_][\w]*\b"
|
|
1027
|
+
r"|^\s*(?:public|private|protected|static|final|async|\s)+\s*[\w<>\[\], ?]+\s+[A-Za-z_]\w*\s*\([^;]*\)\s*\{"
|
|
1028
|
+
r"|^\s*(?:export\s+)?(?:const|let|var)\s+[A-Za-z_]\w*\s*=\s*(?:async\s*)?\([^)]*\)\s*=>"
|
|
1029
|
+
)
|
|
1030
|
+
|
|
1031
|
+
|
|
1032
|
+
def _structure_cfg(cfg: dict) -> dict:
|
|
1033
|
+
value = cfg.get("structure") or {}
|
|
1034
|
+
return value if isinstance(value, dict) else {}
|
|
1035
|
+
|
|
1036
|
+
|
|
1037
|
+
def _optimization_cfg(cfg: dict) -> dict:
|
|
1038
|
+
value = cfg.get("optimization") or {}
|
|
1039
|
+
return value if isinstance(value, dict) else {}
|
|
1040
|
+
|
|
1041
|
+
|
|
1042
|
+
def _bool_config(value: object, default: bool = False) -> bool:
|
|
1043
|
+
if value is None:
|
|
1044
|
+
return default
|
|
1045
|
+
if isinstance(value, bool):
|
|
1046
|
+
return value
|
|
1047
|
+
raw = _text(value).lower()
|
|
1048
|
+
if not raw:
|
|
1049
|
+
return default
|
|
1050
|
+
if raw in {"1", "true", "yes", "on"}:
|
|
1051
|
+
return True
|
|
1052
|
+
if raw in {"0", "false", "no", "off"}:
|
|
1053
|
+
return False
|
|
1054
|
+
return default
|
|
1055
|
+
|
|
1056
|
+
|
|
1057
|
+
def _int_config(value: object, default: int) -> int:
|
|
1058
|
+
try:
|
|
1059
|
+
return int(value)
|
|
1060
|
+
except Exception:
|
|
1061
|
+
return default
|
|
1062
|
+
|
|
1063
|
+
|
|
1064
|
+
def _tracked_files(repo: Path) -> list[str]:
|
|
1065
|
+
return _unique_paths(_git_lines(repo, ["git", "ls-files"]))
|
|
1066
|
+
|
|
1067
|
+
|
|
1068
|
+
def _structure_allow_patterns(structure_cfg: dict) -> list:
|
|
1069
|
+
patterns = list(_DEFAULT_STRUCTURE_ALLOW_PATTERNS)
|
|
1070
|
+
patterns.extend(_as_list(structure_cfg.get("allow_large_files")))
|
|
1071
|
+
patterns.extend(_as_list(structure_cfg.get("exclude")))
|
|
1072
|
+
return patterns
|
|
1073
|
+
|
|
1074
|
+
|
|
1075
|
+
def _structure_accepted_debt_patterns(structure_cfg: dict) -> list:
|
|
1076
|
+
return _as_list(structure_cfg.get("accepted_debt_paths"))
|
|
1077
|
+
|
|
1078
|
+
|
|
1079
|
+
def _is_structure_accepted_debt(path: str, structure_cfg: dict) -> bool:
|
|
1080
|
+
return _path_matches(path, _structure_accepted_debt_patterns(structure_cfg))
|
|
1081
|
+
|
|
1082
|
+
|
|
1083
|
+
def _is_structure_candidate(path: str, structure_cfg: dict) -> bool:
|
|
1084
|
+
normalized = path.replace("\\", "/").lstrip("./")
|
|
1085
|
+
if _path_matches(normalized, _structure_allow_patterns(structure_cfg)):
|
|
1086
|
+
return False
|
|
1087
|
+
name = Path(normalized).name
|
|
1088
|
+
suffix = Path(normalized).suffix.lower()
|
|
1089
|
+
return suffix in _TEXT_SOURCE_EXTENSIONS or name in _TEXT_SOURCE_FILENAMES
|
|
1090
|
+
|
|
1091
|
+
|
|
1092
|
+
def _structure_paths_for_scope(repo: Path, scope: str, base_ref: str, structure_cfg: dict) -> list[str]:
|
|
1093
|
+
if scope == "full":
|
|
1094
|
+
paths = _tracked_files(repo)
|
|
1095
|
+
else:
|
|
1096
|
+
paths = _changed_files(repo, base_ref=base_ref)
|
|
1097
|
+
return [path for path in paths if _is_structure_candidate(path, structure_cfg)]
|
|
1098
|
+
|
|
1099
|
+
|
|
1100
|
+
def _read_text_lines(repo: Path, path: str) -> Optional[list[str]]:
|
|
1101
|
+
file_path = repo / path
|
|
1102
|
+
if not file_path.exists() or not file_path.is_file():
|
|
1103
|
+
return None
|
|
1104
|
+
try:
|
|
1105
|
+
return file_path.read_text(encoding="utf-8").splitlines()
|
|
1106
|
+
except UnicodeDecodeError:
|
|
1107
|
+
return None
|
|
1108
|
+
except OSError:
|
|
1109
|
+
return None
|
|
1110
|
+
|
|
1111
|
+
|
|
1112
|
+
def _parse_numstat_line(line: str) -> tuple[str, int]:
|
|
1113
|
+
parts = line.split("\t", 2)
|
|
1114
|
+
if len(parts) < 3:
|
|
1115
|
+
return "", 0
|
|
1116
|
+
added_raw, _, path = parts
|
|
1117
|
+
if added_raw == "-":
|
|
1118
|
+
return "", 0
|
|
1119
|
+
try:
|
|
1120
|
+
added = int(added_raw)
|
|
1121
|
+
except ValueError:
|
|
1122
|
+
return "", 0
|
|
1123
|
+
return path.replace("\\", "/").strip(), added
|
|
1124
|
+
|
|
1125
|
+
|
|
1126
|
+
def _added_lines_by_path(repo: Path, base_ref: str = "") -> dict[str, int]:
|
|
1127
|
+
added: dict[str, int] = {}
|
|
1128
|
+
commands: list[list[str]] = []
|
|
1129
|
+
effective_base = base_ref or _default_base_ref(repo)
|
|
1130
|
+
if effective_base:
|
|
1131
|
+
commands.append(["git", "diff", "--numstat", f"{effective_base}...HEAD"])
|
|
1132
|
+
commands.extend([
|
|
1133
|
+
["git", "diff", "--numstat"],
|
|
1134
|
+
["git", "diff", "--cached", "--numstat"],
|
|
1135
|
+
])
|
|
1136
|
+
|
|
1137
|
+
for cmd in commands:
|
|
1138
|
+
for line in _git_lines(repo, cmd):
|
|
1139
|
+
path, count = _parse_numstat_line(line)
|
|
1140
|
+
if path:
|
|
1141
|
+
added[path] = added.get(path, 0) + count
|
|
1142
|
+
|
|
1143
|
+
for path in _git_lines(repo, ["git", "ls-files", "--others", "--exclude-standard"]):
|
|
1144
|
+
lines = _read_text_lines(repo, path)
|
|
1145
|
+
if lines is not None:
|
|
1146
|
+
added[path] = added.get(path, 0) + len(lines)
|
|
1147
|
+
return added
|
|
1148
|
+
|
|
1149
|
+
|
|
1150
|
+
def _function_size_warnings(path: str, lines: list[str], threshold: int) -> list[str]:
|
|
1151
|
+
if threshold <= 0:
|
|
1152
|
+
return []
|
|
1153
|
+
starts: list[int] = []
|
|
1154
|
+
for index, line in enumerate(lines):
|
|
1155
|
+
if _FUNCTION_START_RE.search(line):
|
|
1156
|
+
starts.append(index)
|
|
1157
|
+
warnings: list[str] = []
|
|
1158
|
+
for pos, start in enumerate(starts):
|
|
1159
|
+
end = starts[pos + 1] if pos + 1 < len(starts) else len(lines)
|
|
1160
|
+
size = end - start
|
|
1161
|
+
if size > threshold:
|
|
1162
|
+
warnings.append(f"{path}:{start + 1} function-like block has {size} lines (warn>{threshold})")
|
|
1163
|
+
return warnings
|
|
1164
|
+
|
|
1165
|
+
|
|
1166
|
+
def _configured_structure_docs(cfg: dict) -> dict[str, str]:
|
|
1167
|
+
docs_cfg = cfg.get("docs") or {}
|
|
1168
|
+
return {
|
|
1169
|
+
"docs.health_baseline": _text(docs_cfg.get("health_baseline")),
|
|
1170
|
+
"docs.optimization_backlog": _text(docs_cfg.get("optimization_backlog")),
|
|
1171
|
+
"docs.structure_standard": _text(docs_cfg.get("structure_standard")),
|
|
1172
|
+
}
|
|
1173
|
+
|
|
1174
|
+
|
|
1175
|
+
def _structure_gate_enabled(cfg: dict) -> bool:
|
|
1176
|
+
if _configured_command(cfg, "structure_check"):
|
|
1177
|
+
return True
|
|
1178
|
+
structure_cfg = cfg.get("structure")
|
|
1179
|
+
if not isinstance(structure_cfg, dict):
|
|
1180
|
+
return False
|
|
1181
|
+
return _bool_config(structure_cfg.get("enabled"), default=True)
|
|
1182
|
+
|
|
1183
|
+
|
|
1184
|
+
def _print_limited(label: str, items: list[str], max_items: int = 60) -> None:
|
|
1185
|
+
if not items:
|
|
1186
|
+
return
|
|
1187
|
+
print(label)
|
|
1188
|
+
for item in items[:max_items]:
|
|
1189
|
+
print(f"- {item}")
|
|
1190
|
+
remaining = len(items) - max_items
|
|
1191
|
+
if remaining > 0:
|
|
1192
|
+
print(f"- ... {remaining} more")
|
|
1193
|
+
|
|
1194
|
+
|
|
1195
|
+
def cmd_structure_check(args: argparse.Namespace) -> None:
|
|
1196
|
+
repo = Path(args.repo).resolve()
|
|
1197
|
+
ensure_git_repo(repo)
|
|
1198
|
+
cfg = _load_cfg(repo)
|
|
1199
|
+
requested_scope = str(getattr(args, "scope", "") or "").strip().lower()
|
|
1200
|
+
impact = _impact_summary(cfg, repo, requested_scope=requested_scope, base_ref=str(getattr(args, "base", "") or ""))
|
|
1201
|
+
selected_scope = str(impact["selected_scope"])
|
|
1202
|
+
base_ref = str(getattr(args, "base", "") or "")
|
|
1203
|
+
|
|
1204
|
+
structure_cfg = _structure_cfg(cfg)
|
|
1205
|
+
optimization_cfg = _optimization_cfg(cfg)
|
|
1206
|
+
warn_file_lines = _int_config(structure_cfg.get("max_file_lines_warn"), 800)
|
|
1207
|
+
block_file_lines = _int_config(structure_cfg.get("max_file_lines_block"), 1500)
|
|
1208
|
+
warn_function_lines = _int_config(structure_cfg.get("max_function_lines_warn"), 120)
|
|
1209
|
+
max_added_to_large = _int_config(structure_cfg.get("max_added_lines_to_large_file"), 80)
|
|
1210
|
+
block_large_growth = _bool_config(structure_cfg.get("block_new_responsibility_in_large_file"), True)
|
|
1211
|
+
|
|
1212
|
+
paths = _structure_paths_for_scope(repo, selected_scope, base_ref, structure_cfg)
|
|
1213
|
+
added_by_path = _added_lines_by_path(repo, base_ref=base_ref) if selected_scope != "full" else {}
|
|
1214
|
+
|
|
1215
|
+
blocking: list[str] = []
|
|
1216
|
+
warnings: list[str] = []
|
|
1217
|
+
inspected = 0
|
|
1218
|
+
|
|
1219
|
+
for path in paths:
|
|
1220
|
+
lines = _read_text_lines(repo, path)
|
|
1221
|
+
if lines is None:
|
|
1222
|
+
continue
|
|
1223
|
+
inspected += 1
|
|
1224
|
+
line_count = len(lines)
|
|
1225
|
+
accepted_debt = _is_structure_accepted_debt(path, structure_cfg)
|
|
1226
|
+
if block_file_lines > 0 and line_count > block_file_lines:
|
|
1227
|
+
message = f"{path} has {line_count} lines (block>{block_file_lines}); split responsibilities before adding more work"
|
|
1228
|
+
if accepted_debt:
|
|
1229
|
+
warnings.append(message + " [accepted_debt_paths]")
|
|
1230
|
+
else:
|
|
1231
|
+
blocking.append(message)
|
|
1232
|
+
elif warn_file_lines > 0 and line_count > warn_file_lines:
|
|
1233
|
+
warnings.append(f"{path} has {line_count} lines (warn>{warn_file_lines}); prefer extraction before extending it")
|
|
1234
|
+
|
|
1235
|
+
added_lines = added_by_path.get(path, 0)
|
|
1236
|
+
if (
|
|
1237
|
+
block_large_growth
|
|
1238
|
+
and selected_scope != "full"
|
|
1239
|
+
and warn_file_lines > 0
|
|
1240
|
+
and max_added_to_large > 0
|
|
1241
|
+
and line_count > warn_file_lines
|
|
1242
|
+
and added_lines > max_added_to_large
|
|
1243
|
+
):
|
|
1244
|
+
blocking.append(
|
|
1245
|
+
f"{path} adds {added_lines} lines to an already large file ({line_count} lines); "
|
|
1246
|
+
"extract a module/helper or document why this is intentionally co-located"
|
|
1247
|
+
)
|
|
1248
|
+
|
|
1249
|
+
warnings.extend(_function_size_warnings(path, lines, warn_function_lines))
|
|
1250
|
+
|
|
1251
|
+
missing_docs: list[str] = []
|
|
1252
|
+
for key, rel_path in _configured_structure_docs(cfg).items():
|
|
1253
|
+
if rel_path and not Path(repo, rel_path).exists():
|
|
1254
|
+
missing_docs.append(f"{key} missing on disk: {rel_path}")
|
|
1255
|
+
require_baseline = _bool_config(optimization_cfg.get("require_baseline_for_global_review"), True)
|
|
1256
|
+
if missing_docs and selected_scope == "full" and require_baseline:
|
|
1257
|
+
blocking.extend(missing_docs)
|
|
1258
|
+
else:
|
|
1259
|
+
warnings.extend(missing_docs)
|
|
1260
|
+
|
|
1261
|
+
result = {
|
|
1262
|
+
"scope": selected_scope,
|
|
1263
|
+
"inspected_files": inspected,
|
|
1264
|
+
"blocking": blocking,
|
|
1265
|
+
"warnings": warnings,
|
|
1266
|
+
}
|
|
1267
|
+
if getattr(args, "json", False):
|
|
1268
|
+
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
1269
|
+
else:
|
|
1270
|
+
_print_limited("[structure-check] blocking", blocking)
|
|
1271
|
+
_print_limited("[structure-check] warnings", warnings)
|
|
1272
|
+
|
|
1273
|
+
if blocking:
|
|
1274
|
+
raise APError(f"structure-check failed with {len(blocking)} blocking issue(s)")
|
|
1275
|
+
|
|
1276
|
+
print(f"[structure-check] OK scope={selected_scope} inspected={inspected} warnings={len(warnings)}")
|
|
1277
|
+
|
|
1278
|
+
|
|
1279
|
+
def _run_structure_check_for_gate(repo: Path, cfg: dict, selected_scope: str, base_ref: str) -> list[str]:
|
|
1280
|
+
if not _structure_gate_enabled(cfg):
|
|
1281
|
+
return []
|
|
1282
|
+
if _configured_command(cfg, "structure_check"):
|
|
1283
|
+
_run_configured_command(repo, cfg, "structure_check")
|
|
1284
|
+
return ["structure_check"]
|
|
1285
|
+
cmd_structure_check(
|
|
1286
|
+
argparse.Namespace(
|
|
1287
|
+
repo=str(repo),
|
|
1288
|
+
scope=selected_scope,
|
|
1289
|
+
base=base_ref,
|
|
1290
|
+
json=False,
|
|
1291
|
+
)
|
|
1292
|
+
)
|
|
1293
|
+
return ["structure_check"]
|
|
1294
|
+
|
|
1295
|
+
|
|
938
1296
|
def cmd_run(args: argparse.Namespace) -> None:
|
|
939
1297
|
"""
|
|
940
1298
|
Run any configured gate command by name.
|
|
@@ -970,13 +1328,15 @@ def cmd_light_gate(args: argparse.Namespace) -> None:
|
|
|
970
1328
|
selected_scope = str(impact["selected_scope"])
|
|
971
1329
|
paths = list(impact.get("changed_files") or [])
|
|
972
1330
|
matching_rules = _matching_gate_rules(paths, _gate_cfg(cfg))
|
|
1331
|
+
executed: list[str] = []
|
|
1332
|
+
executed.extend(_run_structure_check_for_gate(repo, cfg, selected_scope, str(getattr(args, "base", "") or "")))
|
|
973
1333
|
|
|
974
1334
|
if selected_scope == "changed":
|
|
975
|
-
executed
|
|
1335
|
+
executed.extend(_run_changed_gate(repo, cfg, paths, matching_rules))
|
|
976
1336
|
elif selected_scope == "full":
|
|
977
|
-
executed
|
|
1337
|
+
executed.extend(_run_full_gate(repo, cfg))
|
|
978
1338
|
else:
|
|
979
|
-
executed
|
|
1339
|
+
executed.extend(_run_standard_gate(repo, cfg))
|
|
980
1340
|
|
|
981
1341
|
_run_git_diff_check(repo, cfg)
|
|
982
1342
|
cmd_verify_api_docs(argparse.Namespace(repo=str(repo)))
|
|
@@ -1367,6 +1727,7 @@ def cmd_record_closure(args: argparse.Namespace) -> None:
|
|
|
1367
1727
|
verification_text = "; ".join(verification_items) if verification_items else "TODO"
|
|
1368
1728
|
follow_up = str(args.follow_up or "").strip() or "none"
|
|
1369
1729
|
jenkins_build = str(args.jenkins or "").strip() or "TODO"
|
|
1730
|
+
structure_check = str(getattr(args, "structure_check", "") or "").strip() or "TODO"
|
|
1370
1731
|
|
|
1371
1732
|
lines = [
|
|
1372
1733
|
f"## {task_id} — {title} — {timestamp}",
|
|
@@ -1375,6 +1736,7 @@ def cmd_record_closure(args: argparse.Namespace) -> None:
|
|
|
1375
1736
|
f"- Jenkins Build: {jenkins_build}",
|
|
1376
1737
|
f"- Target Env: {target_env}",
|
|
1377
1738
|
f"- Verification: {verification_text}",
|
|
1739
|
+
f"- Structure Check: {structure_check}",
|
|
1378
1740
|
f"- Result: {args.result}",
|
|
1379
1741
|
f"- Follow-up: {follow_up}",
|
|
1380
1742
|
]
|
|
@@ -1403,6 +1765,7 @@ def _record_commit_push_closure(
|
|
|
1403
1765
|
verification: List[str],
|
|
1404
1766
|
result: str,
|
|
1405
1767
|
follow_up: str,
|
|
1768
|
+
structure_check: str,
|
|
1406
1769
|
) -> None:
|
|
1407
1770
|
cmd_record_closure(
|
|
1408
1771
|
argparse.Namespace(
|
|
@@ -1415,6 +1778,7 @@ def _record_commit_push_closure(
|
|
|
1415
1778
|
verification=verification,
|
|
1416
1779
|
result=result,
|
|
1417
1780
|
follow_up=follow_up,
|
|
1781
|
+
structure_check=structure_check,
|
|
1418
1782
|
initial_commit=args.initial_commit,
|
|
1419
1783
|
jenkins_failure=args.jenkins_failure,
|
|
1420
1784
|
fix_commit=args.fix_commit,
|
|
@@ -1431,12 +1795,14 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
|
|
|
1431
1795
|
target_cfg = (cfg.get("target_env") or {})
|
|
1432
1796
|
|
|
1433
1797
|
msg = args.msg
|
|
1798
|
+
structure_check_status = "skipped"
|
|
1434
1799
|
|
|
1435
1800
|
if args.require_runtime_health:
|
|
1436
1801
|
cmd_wait_health(argparse.Namespace(repo=str(repo), scope="runtime"))
|
|
1437
1802
|
|
|
1438
1803
|
if mode in {"dev", "verify"} or args.require_light_gate:
|
|
1439
1804
|
cmd_light_gate(argparse.Namespace(repo=str(repo)))
|
|
1805
|
+
structure_check_status = "passed via light-gate" if _structure_gate_enabled(cfg) else "skipped (structure disabled)"
|
|
1440
1806
|
|
|
1441
1807
|
if args.require_jenkins:
|
|
1442
1808
|
cmd_verify_jenkins(argparse.Namespace(repo=str(repo)))
|
|
@@ -1459,6 +1825,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
|
|
|
1459
1825
|
verification=dev_verification,
|
|
1460
1826
|
result=args.result or "DEV-CLOSED",
|
|
1461
1827
|
follow_up=args.follow_up or "Run verify mode when Jenkins and target-environment evidence is required.",
|
|
1828
|
+
structure_check=args.structure_check or structure_check_status,
|
|
1462
1829
|
)
|
|
1463
1830
|
|
|
1464
1831
|
run(["git", "add", "-A"], cwd=repo)
|
|
@@ -1509,6 +1876,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
|
|
|
1509
1876
|
verification=verification,
|
|
1510
1877
|
result=args.result or "PASS",
|
|
1511
1878
|
follow_up=args.follow_up or "none",
|
|
1879
|
+
structure_check=args.structure_check or structure_check_status,
|
|
1512
1880
|
)
|
|
1513
1881
|
run(["git", "add", "-A"], cwd=repo)
|
|
1514
1882
|
closure_diff = run(["git", "diff", "--cached", "--name-only"], cwd=repo).stdout.strip()
|
|
@@ -1525,6 +1893,7 @@ def cmd_commit_push(args: argparse.Namespace) -> None:
|
|
|
1525
1893
|
verification=args.verification or [],
|
|
1526
1894
|
result=args.result or "PARTIAL",
|
|
1527
1895
|
follow_up=args.follow_up or "none",
|
|
1896
|
+
structure_check=args.structure_check or structure_check_status,
|
|
1528
1897
|
)
|
|
1529
1898
|
print(f"[commit-push] OK - mode={mode}")
|
|
1530
1899
|
|
|
@@ -1557,6 +1926,12 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
1557
1926
|
s.add_argument("--json", action="store_true")
|
|
1558
1927
|
s.set_defaults(func=cmd_impact)
|
|
1559
1928
|
|
|
1929
|
+
s = sp.add_parser("structure-check")
|
|
1930
|
+
s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
|
|
1931
|
+
s.add_argument("--base")
|
|
1932
|
+
s.add_argument("--json", action="store_true")
|
|
1933
|
+
s.set_defaults(func=cmd_structure_check)
|
|
1934
|
+
|
|
1560
1935
|
s = sp.add_parser("light-gate")
|
|
1561
1936
|
s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
|
|
1562
1937
|
s.add_argument("--base")
|
|
@@ -1609,6 +1984,7 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
1609
1984
|
s.add_argument("--jenkins")
|
|
1610
1985
|
s.add_argument("--target-env")
|
|
1611
1986
|
s.add_argument("--verification", action="append")
|
|
1987
|
+
s.add_argument("--structure-check")
|
|
1612
1988
|
s.add_argument("--result", choices=["DEV-CLOSED", "PASS", "FAIL", "PARTIAL"], required=True)
|
|
1613
1989
|
s.add_argument("--follow-up")
|
|
1614
1990
|
s.add_argument("--initial-commit")
|
|
@@ -1642,6 +2018,7 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
1642
2018
|
s.add_argument("--jenkins-build")
|
|
1643
2019
|
s.add_argument("--target-env")
|
|
1644
2020
|
s.add_argument("--verification", action="append")
|
|
2021
|
+
s.add_argument("--structure-check")
|
|
1645
2022
|
s.add_argument("--result", choices=["DEV-CLOSED", "PASS", "FAIL", "PARTIAL"])
|
|
1646
2023
|
s.add_argument("--follow-up")
|
|
1647
2024
|
s.add_argument("--initial-commit")
|
package/package.json
CHANGED