inspect-structure

inspect-structure — 代码质量与结构性债务检查器

领域评估准则

1. 范围与操作边界

• 结构性债务与语法格式：分析范围严格限定于模块、类和方法层面的结构性、面向对象及认知负担债务；空白、分号和样式细节应完全交由原生代码检查工具处理。
• 架构内聚性与行数配额（LOC / wc -l）：禁止将原始行数（LOC）或 wc -l 作为判定“上帝类”的主要指标或依据。应评估结构内聚性、职责边界和 I/O 耦合，而非文件长度。区分声明式 UI 组件层级（标记、布局树、响应式样式）和 OOP 上帝类，以及配置／令牌注册表；绑定到单个 presenter/controller 的大型声明式视图组件在架构上是合理的，而将持久化、网络传输和领域状态交织在一起的紧凑类则是危险的上帝类。
• 架构形式与业务逻辑：只审查结构内聚性和可维护性；没有权威规范时，绝不评估领域业务规则、定价逻辑或数学公式（将错误隔离交由 /diagnose 处理；将规范偏差交由 /assay 处理）。
• 只读审查与代码修改：仅交付结构化检查报告；禁止修改磁盘上的文件、生成代码差异或应用自动重构（将补救方案规划交由 /changeset 处理）。

2. 结构检查维度

1. 类内聚性与 SRP（上帝类）

   • 评估标准：
     • 缺乏内聚性（LCOM）：评估方法是否操作共享状态集群，还是划分为彼此隔离、互不相干的状态区块。
     • 职责与参与方聚类：确认该类是否服务于多个外部参与方、不同生命周期或无关的子系统关注点（例如存储、传输、硬件驱动）。
     • 边界分离：确认展示／UI 组件是否直接执行 I/O、管理持久化或发起传输请求，而不是将这些工作委托给领域控制器、presenter 或状态通知器。
   • 真正的反模式：在展示组件中混入直接 I/O 或持久化；在一个服务中协调多个独立的聚合根；违反单一职责（存在多个参与方或变化维度）。
   • 应避免的误报：绝不能仅凭行数（LOC）标记上帝类；对于绑定到单一内聚职责的大型声明式 UI 树、视图样式、序列化表和配置／令牌注册表，应予以接受。
   • 改进方案：拆分为单一职责的领域服务、值对象、控制器／presenter 或策略委托对象。
   • 微型示例：

     异味（OOP 上帝类）：    class OrderManager { calculateTax(); sendEmail(); saveToDb(); renderPdf(); }
     改进方案：              class OrderService 将工作委托给 TaxCalculator、OrderMailer、OrderRepository、PdfRenderer。
     
     异味（UI 边界泄漏）：   class ProfileView { render() { http.get("/user"); db.save(); } }
     改进方案：              ProfileView 绑定到 ProfileController；控制器协调 UserService 和 Repository。
     

2. 方法与流程复杂度（长方法／深层嵌套）

   • 异味：方法长度超出可管理范围、控制流嵌套深度 ≥ 3 层、箭头反模式或认知负担过高。
   • 改进方案：将条件反转为守卫子句、扁平化嵌套代码块，并将工作拆解为专注于单一任务的辅助子程序。
   • 微型示例：

     异味：  void process() { if (a) { while (b) { if (c) { try { ... } } } } }
     改进方案：使用守卫子句提前返回；将循环体提取为私有子程序。
     

3. 系统性重复（宏观与微观 DRY）

   • 异味：在多个类、文件或方法中复制粘贴算法逻辑、多步骤验证流程或错误处理管道。
   • 改进：将共享规则提取为纯函数或组合式辅助函数；只有当重复逻辑具有相同的生命周期、依赖项和所有权时，才考虑使用基类抽象。每个调用点仍需自行验证事务边界。
   • 微型示例：

     异味：  ServiceA 和 ServiceB 在各自的事务中重复相同的决策逻辑。
     改进：提取一个接受状态快照的纯函数；每个服务仍保留自己的事务、锁和状态读取。
     

4. 耦合与封装泄漏

   • 异味：方法操作外部类的内部数据（特性羡慕）；类通过 getter 直接暴露可变的内部集合。
   • 改进：采用“告知，而非询问”原则；通过领域方法封装状态变更；返回不可变快照或防御性副本。
   • 微型示例：

     异味：  if (order.getCustomer().getAddress().getCountry().equals("US")) { ... }
     改进：if (order.isDomesticDelivery()) { ... }
     

5. 多态与策略不足（分散的分支逻辑）

   • 异味：多个类中散布着并行的 switch(type) 或 if (type == A) 分支链，导致变体变更时需要四处修改。
   • 改进：当各个变体独立演进，且新增变体会迫使你修改多个文件时，可考虑使用策略模式或多态。如果各分支是在单一位置体现同一策略的紧密关联情形，则优先使用明确的条件语句；提取之前应评估内聚性和变更成本。
   • 微型示例：

     异味：  PaymentService、InvoiceService 和 EmailService 都维护着并行的 switch (user.getPlanTier())。
     改进：将特定于等级的行为封装到 PlanTier 策略中（每新增一个等级，三个独立服务都要同步变更）。
     

6. 健壮性与资源管理

   • 异味：通过空的 catch 块吞掉错误；流、数据库连接句柄或事件监听器未受管理，也没有清理钩子。
   • 改进：明确处理错误，或在重新抛出时附带上下文元数据；在确定性的释放代码块（defer、finally、using）中封装资源生命周期。
   • 微型示例：

     异味：  try { connect(); } catch (Exception e) {}
     改进：try { connect(); } catch (Exception e) { logger.error("DB connection failed", e); throw new ServiceUnavailableException(e); }
     

规范输出约定

# Structural Inspection Dossier: <Target Scope / Module>

## 1. Executive Summary
- **Target Inspected**: `<file_or_directory_path>`
- **Health Rating**: <CLEAN | MODERATE_DEBT | CRITICAL_DEBT>
- **Primary Bottleneck**: <Single-sentence summary of greatest structural risk>

## 2. Technical Debt Catalog

### [<CRITICAL | MAJOR | MINOR>] <Dimension Name>: `<Target Entity / Symbol>`
- **Location**: [<file>#L<N>-L<M>](file:///path/to/file#L<N>-L<M>)
- **Smell**: <Observable anti-pattern description and maintainability impact>
- **Remedy**: <Exact architectural decomposition or extraction path>

*(Repeat for each distinct structural finding; emit 'No structural code smells observed across rubric dimensions' if clean)*

路由

• 多文件结构重构、上帝类拆分或共享抽象提取 →（通过 /changeset）。
• 怀疑存在运行时功能错误或测试失败 →（通过 /diagnose）。

执行协议

阶段 1：范围分流与宏观定位

1. 接收目标路径（file、directory 或 subsystem）。
2. 使用符号和文件工具识别主要结构锚点（类、模块入口点、共享实用工具）。

阶段 2：自适应规模的检查

• 当前轮次内执行（< 10 个文件或内聚模块）：在当前轮次中直接依据评审标准各维度审查代码。
• 子 Agent 扇出（范围广的多包子系统或代码库）：根据划分的切片或调用方声明的预算，动态启动并发的 research 子 Agent（角色：Structural Inspector (<Slice>)），并向其提供切片坐标、已发现的锚点、领域评审标准和规范输出约定。

阶段 3：综合与轮次终止门控（扇入）

1. 将子 Agent 的发现进行协调和去重，并纳入规范化输出契约。
2. 确定最终健康评级：
   • CLEAN：没有违反评估标准的结构性缺陷。
   • MODERATE_DEBT：存在零散的封装泄漏、散落的条件语句或轻微重复。
   • CRITICAL_DEBT：存在普遍的上帝类、跨子系统的复制粘贴或系统性资源泄漏。
3. 将完整的检查档案输出到对话流中，并立即终止本轮。