Skip to content

Commit fdf4ba4

Browse files
author
branch-coverage-leader
committed
docs+thresh(stage7): final review + ratchet G8 thresholds
Adds Stage-7 spec set (70-plan / 71-gap / 72-tc / 79-review) and ratchets coverage_threshold.sh per-file thresholds to Stage-7 actual - 5pp: ff_ini_parser branch 78 -> 84 (actual 89.7%) ff_host_interface branch 87 -> 93 (actual 98.1%) ff_epoll branch 84 -> 92 (actual 97.8%) ff_config line 70 -> 78 (actual 83.5%) branch 65 -> 73 (actual 78.5%) ff_dpdk_pcap branch 84 -> 89 (actual 94.4%) Project merged branch 57.21% -> 59.92% (+2.71pp). G8 still PASS 10/10. valgrind 12/12. ahead-of-upstream 16 -> 21.
1 parent 8bce8a9 commit fdf4ba4

5 files changed

Lines changed: 647 additions & 7 deletions

File tree

‎docs/unit_test_spec/zh_cn/70-stage7-branch-boost-plan.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Stage-7 Branch-Coverage Boost — Master Plan
2+
3+
| Field | Value |
4+
|---|---|
5+
| Plan ID | stage7-branch-coverage-boost |
6+
| Version | v1.0-draft (Phase 1 skeleton) |
7+
| Status | BUILDING |
8+
| Author | unit-test-impl-leader (主 agent) |
9+
| Bounce Counter | 0 / 3 (max-allowed per phase) |
10+
| Last Updated | 2026-06-10 (Phase 1) |
11+
| Local-only | YES (匹配 .gitignore `plan-*.md` 规则；最终若提交需重命名为 `plan-stage7-branch-boost.md`) |
12+
13+
---
14+
15+
## §1 Goals & Acceptance Gates
16+
17+
### 1.1 Top-level Goal
18+
19+
在 Stage-6 已闭环（merged branch 57.2%）的基础上，对 10 个已纳入 unit 测试集的 lib 文件**深挖异常与边界 case 的 branch 覆盖率**，配套必要的 lib safe-patch（含小重构），项目整体 branch ≥ 65%。
20+
21+
### 1.2 Acceptance Gates
22+
23+
| Gate | 描述 | 起点 | 目标 | 度量来源 |
24+
|---|---|---|---|---|
25+
| **G-CB-7-1** | merged project branch | 57.2% | **≥ 65%** | `tests/run_full_coverage.sh` |
26+
| **G-CB-7-2** | per-headroom-file branch +10~15pp | 见 §3 | 见 §3 | `tests/unit/coverage_threshold.sh` |
27+
| **G-CB-7-3** | 全部 unit + integration TC PASS | 142+8=150 | ≥ 175 | `make test` |
28+
| **G-CB-7-4** | valgrind 0 definite leak（不依赖 supp）| 12/12 PASS | 12/12 PASS | `make check` (unit + integ) |
29+
| **G-CB-7-5** | G8 阈值表 10/10 PASS（按 Stage-7 actual ratchet up）| 10/10 PASS | 10/10 PASS | `coverage_threshold.sh` |
30+
| **G-CB-7-6** | lib safe-patch 单 commit ≤ 30 行 | n/a | enforced | `git diff --stat` |
31+
| **G-CB-7-7** | 每个新 TC 可追溯到 71 gap 条目 | n/a | 1:1 | 71/72 cross-ref |
32+
33+
---
34+
35+
## §2 Per-File Targets
36+
37+
| 文件 | baseline branch | missing | Stage-7 目标 | Δbranches | 优先级 |
38+
|---|---|---|---|---|---|
39+
| **ff_config.c** | 75.18% (512/681) | **169** | **≥85% (~580/681)** | **+68** | **P0** |
40+
| **ff_dpdk_kni.c** | 40.91% (36/88) | **52** | **≥55% (~49/88)** | **+13** | **P0** |
41+
| ff_ini_parser.c | 83.82% (57/68) | 11 | ≥92% (63/68) | +6 | P1 |
42+
| ff_epoll.c | 89.13% (41/46) | 5 | ≥95% (44/46) | +3 | P1 |
43+
| ff_dpdk_pcap.c | 88.89% (16/18) | 2 | ≥95% (17/18) | +1 | P2 |
44+
| ff_host_interface.c | 92.45% (98/106) | 8 | ≥95% (101/106) | +3 | P2 |
45+
| ff_init.c | 100% | 0 | unchanged | 0 | capped |
46+
| ff_log.c | 100% | 0 | unchanged | 0 | capped |
47+
| ff_thread.c | 100% | 0 | unchanged | 0 | capped |
48+
| ff_dpdk_if.c | 22.64% | 427 | unchanged (受 unit mock 限) | 0 | out-of-scope |
49+
| **Σ headroom** | – | **247** | – | **+94 (min)** | – |
50+
51+
**+94 branches → 项目整体 +6.0pp → 57.2% + 6.0 = 63.2%**（仍未达 65% G-CB-7-1）
52+
53+
**ratchet-up plan**：ff_config 实际可冲到 90% (+102) + ff_dpdk_kni 冲到 65% (+21) → 总 +146 → 66.5% ≥ 65% ✓
54+
55+
---
56+
57+
## §3 Phase Schedule
58+
59+
| Phase | 内容 | 模式 | Owner | 验收 |
60+
|---|---|---|---|---|
61+
| **0** | baseline 实测 | sync | leader | merged branch=57.2% / valgrind 12/12 / git ahead=16 (✅ DONE) |
62+
| **1** | spec 骨架落盘（本文档 + 71/72/79）| sync | leader | 4 篇 .md 创建 (← 当前) |
63+
| **2** | async-team gap analysis | **async** | 4 analysts | 71 文档完整 / ≥40 gap 条目 |
64+
| **3** | ff_config.c 实施 | sync | test-author + c-precision-surgery | branch 75→85%+ / +8~12 TC / commit |
65+
| **4** | ff_ini_parser.c 实施 | sync | test-author + c-precision-surgery | branch 84→92%+ / +5~8 TC / commit |
66+
| **5** | ff_dpdk_pcap + ff_epoll 双文件 | sync | test-author + c-precision-surgery | 各 branch ≥95% / +6~10 TC / commit |
67+
| **6** | ff_dpdk_kni + ff_host_iface | sync | test-author + c-precision-surgery | kni 41→55%+ / host ≥95% / +6~10 TC / commit |
68+
| **8** | 全套门禁 | sync | gatekeeper | G-CB-7-1..G-CB-7-7 全 PASS |
69+
| **9** | review + EN mirror + commit | sync | leader | 79 review v1.0-final / 4 篇 EN 落 docs/unit_test_spec/ 根 |
70+
71+
（Phase 7 在原计划合并入 Phase 6，故无 Phase 7）
72+
73+
---
74+
75+
## §4 Agent Team Topology
76+
77+
```
78+
┌──────────────────────────┐
79+
│ Stage-7 Leader (主) │
80+
│ 统筹 / 仲裁 / 失败回滚 │
81+
└──────────┬───────────────┘
82+
│
83+
┌───────────────┼───────────────┐
84+
│ Phase 2 async │ Phase 3-7 │ Phase 8-9
85+
│ (并行) │ (串行) │ (串行)
86+
▼ ▼ ▼
87+
┌────────────┐ ┌────────────┐ ┌────────────┐
88+
│ analyst- │ │ test-author│ │ gatekeeper │
89+
│ config │ │ (leader) │ │ (leader) │
90+
├────────────┤ ├────────────┤ ├────────────┤
91+
│ analyst- │ │ c-precision│ │ EN mirror │
92+
│ pcap-epoll │ │ -surgery │ │ │
93+
├────────────┤ ├────────────┤ └────────────┘
94+
│ analyst- │ │ build- │
95+
│ iniparser- │ │ runner │
96+
│ kni │ ├────────────┤
97+
├────────────┤ │ coverage- │
98+
│ analyst- │ │ runner │
99+
│ host-iface │ ├────────────┤
100+
└────────────┘ │ reviewer │
101+
└────────────┘
102+
```
103+
104+
### 4.1 职责矩阵
105+
106+
| Agent | 阶段 | 模式 | 职责 |
107+
|---|---|---|---|
108+
| Leader (主) | 全局 | – | spec 骨架 / 调度 / 失败仲裁 / commit / EN mirror |
109+
| analyst-config | P2 | async | ff_config.c branch gap → 71 文档 §A |
110+
| analyst-pcap-epoll | P2 | async | ff_dpdk_pcap + ff_epoll → 71 §B+C |
111+
| analyst-iniparser-kni | P2 | async | ff_ini_parser + ff_dpdk_kni → 71 §D+E |
112+
| analyst-host-iface | P2 | async | ff_host_interface → 71 §F |
113+
| code-explorer | P2-7 | sync subagent | gap 验证 / 函数实现深挖 |
114+
| c-precision-surgery | P3-6 | sync skill | lib safe-patch 最小 diff 修改 |
115+
| test-author (leader 自任) | P3-6 | sync inline | 写 TC + fixture + 注册 main runner |
116+
| build-runner (leader 自任) | P3-6, P8 | sync inline | make clean && make test |
117+
| coverage-runner (leader 自任) | P3-6, P8 | sync inline | run_coverage.sh + lcov 实测对照 71 |
118+
| reviewer (leader 自任) | P3-6, P8 | sync inline | 4 维 review (assertions / boundary / mock / determinism) |
119+
| gatekeeper (leader 自任) | P8 | sync inline | G-CB-7-1..G-CB-7-7 |
120+
121+
### 4.2 失败回滚 SOP
122+
123+
| 失败点 | 立即操作 | bounce 计数 |
124+
|---|---|---|
125+
| Build fail | reviewer 重审 TC + 修 → 重 build | +1 |
126+
| Test fail | 检查断言粒度 / mock 缺失 → 修 → 重跑 | +1 |
127+
| Coverage 未达 G-CB-7-2 | analyst 重出 gap 或扩展 lib safe-patch → 重做 | +1 |
128+
| Valgrind fail | 优先排查新 lib patch → c-precision-surgery 二次修 | +1 |
129+
| 同 phase bounce ≥ 3 | leader 升级到用户介入 | – |
130+
131+
---
132+
133+
## §5 Lib Safe-Patch Plan (Q4 扩展授权 ≤30 行 / commit)
134+
135+
### 5.1 候选 patch 清单（Phase 2 分析后细化）
136+
137+
| 文件 | 候选 patch | 行数预估 | 配套 TC |
138+
|---|---|---|---|
139+
| ff_config.c | vlan_cfg_handler / bond_cfg_handler / vdev_cfg_handler 的 free-before-strdup（Stage-6 仅修了 log.dir/filename/proc_type）| ~24 行（×4 处 ×6 行）| TC-S7-CFG-* |
140+
| ff_config.c | port_cfg_handler 的 OOM 路径 / NULL guard | ~10 行 | TC-S7-CFG-* |
141+
| ff_ini_parser.c | BOM (0xEF 0xBB 0xBF) 处理 / 全空白 line 跳过 | ~8 行 | TC-S7-INI-* |
142+
| ff_dpdk_pcap.c | write 失败 fd 关闭 / save_path 长度上限 | ~6 行 | TC-S7-PCAP-* |
143+
| ff_epoll.c | EBADF 早期返回 / fd 表满 | ~10 行 | TC-S7-EPOLL-* |
144+
| ff_dpdk_kni.c | proto_filter NULL 入参 / 无效 port_id 边界 | ~12 行 | TC-S7-KNI-* |
145+
146+
**总计预估：~70 行 lib 改动，分 5~6 个 commit（每个 ≤30 行）**
147+
148+
### 5.2 重构候选（Q4 扩展授权）
149+
150+
仅当无法通过 ≤30 行 safe-patch 触达边界时启用。当前预估**不需要**进入扩展模式。
151+
152+
---
153+
154+
## §6 New Test Cases List
155+
156+
详见 `72-stage7-test-cases-and-acceptance.md`（Phase 1 同步落盘）。
157+
158+
预估总量：**+30~50 TC**，按 6 大边界分类（NULL / 0 / 最大值 / 越界 / 重复调用 / 错误返回路径）。命名规范：`test_<func>_<scenario>_<expected>`。
159+
160+
---
161+
162+
## §7 Risk & Rollback
163+
164+
| Risk | Likelihood | Mitigation |
165+
|---|---|---|
166+
| ff_config 复杂 INI corner case 难以模拟 | M | 复用 fixtures/ 现有 INI 模板 + 新增 minimal corner fixture |
167+
| lib safe-patch 引入新 leak | L | 每 patch 配 valgrind 即时验证；G-CB-7-4 守护 |
168+
| 跨文件改动相互影响 | L | sync 模式串行；每 phase 独立 commit |
169+
| ff_dpdk_kni 41% → 55% 实际不可达 | M | 71 gap 分析阶段提前评估，必要时调降至 50% |
170+
| async team 协调失败 | L | 4 个 analyst 互相隔离（不同文件），无依赖 |
171+
172+
---
173+
174+
## §8 Reproducibility Commands
175+
176+
```bash
177+
# unit-only
178+
cd /data/workspace/f-stack/tests/unit
179+
make clean && make test
180+
make clean && make check
181+
make clean && ./run_coverage.sh
182+
183+
# integration-only
184+
cd /data/workspace/f-stack/tests/integration
185+
make clean && make test
186+
make clean && make check
187+
188+
# merged
189+
cd /data/workspace/f-stack/tests
190+
./run_full_coverage.sh
191+
```
192+
193+
---
194+
195+
## §9 Stage-6 Diff & Stage-8 Future Work
196+
197+
### 9.1 Stage-6 已完成（不重复）
198+
199+
- 10 文件 line/branch baseline 建立
200+
- ff_dpdk_if integration（FU-CB-DPDKIF-INTEGRATION）
201+
- ff_unload_config 引入（FU-S2-2-CFG-UNLOAD）
202+
- ff_dpdk_if_send NULL guard（FU-CB-DPDKIF-NULLGUARD）
203+
204+
### 9.2 Stage-8 Out-of-Scope
205+
206+
- 新增未覆盖 lib 文件 unit 测试（ff_kern_* / ff_route / ff_lock 等）
207+
- ff_dpdk_if integration 扩容
208+
- CI 接入（GitHub/GitLab Actions）
209+
- libFuzzer 接入
210+
211+
---
212+
213+
## §10 Bounce Counter
214+
215+
```
216+
Phase 0 baseline : 0 bounces
217+
Phase 1 spec skeleton : 0 bounces
218+
Phase 2 gap analysis : (pending)
219+
Phase 3 ff_config : (pending)
220+
Phase 4 ff_ini_parser : (pending)
221+
Phase 5 pcap+epoll : (pending)
222+
Phase 6 kni+host_iface : (pending)
223+
Phase 8 gating : (pending)
224+
Phase 9 review+mirror : (pending)
225+
```
226+
227+
EOF

0 commit comments

Comments
 (0)