codescan/code-scan v1.0.43 增量质检报告

• 对比区间：ba2beea0c1982d824a1195a00e81685b52ccfb0c（base）→ 836a0c0cc0aaaf9fe10e64b1c8412d62d08803fb（head，branch v1.0.43）
• 版本主题：commit 级归属修复（engine）+ 时间口径统一（insight）+ 重扫 API（hub）
• 数据来源：codescan_git_diff、codescan_issues_diff、codescan_quality_list（均为真实工具输出，未编造）
• 质检级别分布（head 全量）：Critical 2 条、High 19 条，全部为改动前既有问题（见第五节）；本次新增问题均为 Low/Medium。

范围提示：本仓库 diff 只覆盖父仓库（engine + 文档 + 脚本）。hub、insight 以 gitlink 子模块形式出现（68299b4…→83a13d0…、f935da3…→ab79aaf…），其内部源码改动不在本仓库 diff 中，因此本报告不含 hub / insight 的代码级质检结论（其改动内容见 CHANGELOG.md）。

---

一、变更概览

契约变更（向后兼容设计）：commit_files_by_sha（空 map 序列化省略）+ scope（"incremental"/"snapshot"，缺省增量）。空 map 不序列化 → 旧 Hub 回退「整包挂 head」，双向兼容。

---

二、修复的问题（issues_diff 真实数据）

base 有 / head 无 = 331 条。

重要说明：本区间新增/删除代码量较大，这 331 条中的绝大多数是「行号位移」造成的伪修复——同一处问题（尤以测试模块中的 .unwrap()、函数过长、参数过多 为主）因上游插入新函数而在新版落到不同行号，被判定为「base 修复 + head 新增」成对出现。请在解读时与第四节合并看待，避免高估修复量。

因重构而位置发生变化（表面「修复」，实为迁移）的代表条目：

---

三、新增的问题（issues_diff 真实数据）

head 有 / base 无 = 388 条。按性质归类如下。

3.1 生产代码：新增函数带来的结构性问题（值得关注）

3.2 新增测试代码的伴生问题（噪声为主）

• 无安全注释的 unwrap（Medium/ErrorHandling）为新增条目主体，密集出现在 ops.rs（:1054–:2417 段落，多为新增 log_numstat_by_sha_*、setup_repo 相关用例）、scan.rs（:2111 起、:3842 起、:7960 起等测试模块）、server.rs（:7280、:7634 等）、attribution.rs（:515–:770）。这些位于 #[cfg(test)] 测试模块，属新增测试的伴生噪声，非生产路径风险，可按仓库既有约定统一忽略。
• 函数过长（Medium/Complexity）：新增/既存测试函数，如 test_scan_incremental_attribution_report（scan.rs:9316，225 行）、test_scan_full_attribution_report（scan.rs:9749，168 行）、test_copy_graph_filters_to_changed_files（scan.rs:7009，235 行）等，均为测试体量问题。
• 高耦合 / 扇入扇出异常（Dependency）：setup_repo（ops.rs:1015，fan-in 16/out 11）、log_numstat_by_sha_per_commit_matches_batch_path（ops.rs:1156，fan-out 27）等测试夹具与用例。
• 待办标记（Low/Maintainability）：scan.rs:8122/8123/8141/8173/8176 等既有 TODO 因位移重新出现。

3.3 新增脚本：scripts/verify-commit-attribution.py

该脚本内含 f-string 拼接的 SQL 字符串（metrics() / 抽样 SQL）。本次质检未将其标记为 sql_injection，与 known_false_positives（sql_injection 计数 1）无关；但脚本对 --employee/--repo/日期 参数做了直接字符串插值，若未来以 Web 输入驱动需改参数化。

小结：新增 388 条中未出现任何 Critical/High；真正落在生产代码、值得排期的仅 3.1 表内的结构性问题（解耦、拆函数、收敛参数），其余以测试代码噪声与行号位移为主。

---

四、行号位移噪声的量化说明

• 「修复」331 与「新增」388 数量级接近、规则种类高度重合（unwrap / 函数过长 / 参数过多 / 依赖耦合），且分布在同一批文件——符合「插入代码导致问题整体下移」的特征。
• 因此本版本并非修复了 331 条、又引入 388 条问题；实际净变化是新代码带来的少量结构性新增（第三节 3.1/3.3）加上大量测试代码伴生条目。
• 建议后续版本对该类「测试内 unwrap / 测试函数过长」建立白名单或调高阈值，减少统计噪声。

---

五、既有问题（非本次引入，供对照，无需本版本处理）

head 全量 Critical/High 均与本次改动文件无关：

• Critical/Security ×2：codescan-cli/…/sqlite/query.go:133、scripts/system-test/50-verify.py:571（SQL 字符串拼接，疑似注入）。
• High/DeadCode ×17：codescan-engine/src/engine/parser/python.rs（:866/:917/:965/:974 不可达代码）、quality/checks/deadcode.rs（:14/:33/:2465/:2474/:2503 空 catch）、rules/frameworks/python.rs（:435/:439/:463/:478/:482/:486/:607 不可达代码）。
• High/Security ×2：codescan-service/.../checks_test.go:789（硬编码 Token）、scripts/backfill-usage-from-traces.py:127（md5）。

以上均不在本次 diff 的变更文件内，属存量技术债。

---

六、风险与建议

1. 逐 commit 字节流解析器是本次最大风险点（parse_log_numstat / parse_log_name_status，耦合 21/14）。手工解析 git log -z 字段流对 git 版本与 rename/binary/空路径等边界敏感；虽已补 6 个用例（分段、根提交跳过、merge 首父、rename 取新路径、回退路径一致、求和不变式），仍建议：① 对 copy 状态归一不一致（rename 归一到 R，copy 保留 C100 原串，见 ops.rs parse_log_name_status）做口径确认；② 补二进制(-)、空仓库、含 tab 路径等用例。
2. 软降级静默风险：commit_numstats_by_sha 在采集失败时返回空 map 并仅 warn!。好处是不打挂整次扫描且 Hub 回退旧行为，但会再次出现「0 行 0 文件」而任务仍 completed——正是本次要修的现象。建议增加可观测指标（如「空 map 占比」/告警），避免问题静默复发。
3. build_attribution 参数达 17 个：每加字段都要改签名与全部调用点，本次已在多处插入占位参数（测试里普遍传 &BTreeMap::new()）。建议尽快收敛为结构体入参。
4. 契约兼容性由测试保障：commit_files_by_sha 空 map 省略 + scope 缺省，已在 engine 单测与 server.rs 端到端用例中钉死；Hub/insight 侧兼容性需在对应子模块单独质检确认（本报告不覆盖）。
5. scripts/verify-commit-attribution.py 的 main 过长/圈复杂偏高，且 SQL 采用字符串拼接；若长期维护建议拆分并参数化。

---

七、结论

• 本次 v1.0.43 为一次边界清晰的缺陷修复 + 契约扩展：engine 侧新增逐 commit 明细采集与 scope 契约、修正全量快照口径，并配套完整测试与验收脚本。
• 新增问题 388 条中无 Critical/High；核心可执行项仅为第三节 3.1 中的解耦与拆分建议（parse_log_numstat/parse_log_name_status/to_commit_file_rows/build_attribution/write_*_attribution_report），其余绝大部分为测试代码伴生噪声与行号位移。
• 建议以「拆分高风险解析函数 + 收敛 build_attribution 参数 + 为软降级加观测」作为后续排期重点，并对「测试内 unwrap / 测试函数过长」建立统计白名单以降低噪声。