venhdev/zenforge

inspect-structure

Audit source code modules for structural smells, God classes, and duplication anti-patterns before refactoring.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/venhdev/zenforge --skill inspect-structure

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

inspect-structure — Code Quality & Structural Debt Inspector

Domain Rubric

1. Scope & Operational Boundaries

  • Structural Debt vs. Syntax Formatting: Confine analysis strictly to structural, OOP, and cognitive debt across module, class, and method tiers; defer whitespace, semicolons, and styling nits entirely to native linters.
  • Architectural Cohesion vs. Line Quotas (LOC / `wc -l`): Prohibit raw line counts (LOC) or wc -l as a primary metric or verdict for "God Class". Assess structural cohesion, actor boundaries, and I/O coupling instead of file length. Distinguish declarative UI component hierarchies (markup, layout trees, responsive styling) and configuration/token registries from OOP God Classes; an expansive declarative view component bound to a single presenter/controller is architecturally valid, whereas a compact class interweaving persistence, network transport, and domain state is a dangerous God Class.
  • Architectural Form vs. Business Logic: Audit structural cohesion and maintainability exclusively; never evaluate domain business rules, pricing logic, or math formulas without authoritative specs (route bug isolation to /diagnose; route spec drift to /assay).
  • Read-Only Audit vs. Code Mutation: Deliver structured inspection dossiers only; forbid modifying files on disk, generating code diffs, or applying automatic refactorings (route remediation planning to /changeset).

2. Structural Inspection Dimensions

  1. Class Cohesion & SRP (God Class)
  • Evaluation Criteria:
  • Lack of Cohesion (LCOM): Assess whether methods operate on a shared state cluster or partition into isolated, disjoint state silos.
  • Responsibility & Actor Clustering: Confirm whether the class serves multiple external actors, disparate lifecycles, or unrelated subsystem concerns (e.g., storage, transport, hardware drivers).
  • Boundary Separation: Verify whether presentation/UI components execute I/O, manage persistence, or perform transport requests directly instead of delegating to domain controllers, presenters, or state notifiers.
  • True Anti-Patterns: Mixing direct I/O or persistence into presentation components; coordinating multiple independent aggregate roots in one service; violating Single Responsibility (multiple actors or axes of change).
  • False Positives to Avoid: Never flag a God class solely on line counts (LOC); tolerate expansive declarative UI trees, view styling, serialization tables, and configuration/token registries when bound to a single cohesive responsibility.
  • Remedy: Decompose into single-responsibility domain services, value objects, controllers/presenters, or strategy delegates.
  • Micro-Snippets:
text
     Smell (OOP God Class):    class OrderManager { calculateTax(); sendEmail(); saveToDb(); renderPdf(); }
     Remedy:                   class OrderService delegates to TaxCalculator, OrderMailer, OrderRepository, PdfRenderer.

     Smell (UI Boundary Leak): class ProfileView { render() { http.get("/user"); db.save(); } }
     Remedy:                   ProfileView binds to ProfileController; controller coordinates UserService and Repository.
  1. Method & Flow Complexity (Long Method / Deep Nesting)
  • Smell: Methods exceeding manageable length, control-flow nesting ≥ 3 levels deep, arrow anti-pattern, or high cognitive load.
  • Remedy: Invert conditions into guard clauses, flatten nested blocks, and decompose into focused single-task helper subroutines.
  • Micro-Snippet:
text
     Smell:  void process() { if (a) { while (b) { if (c) { try { ... } } } } }
     Remedy: Use guard clauses for early returns; extract loop bodies into private subroutines.
  1. Systemic Duplication (Macro & Micro DRY)
  • Smell: Copy-pasted algorithmic routines, multi-step validation sequences, or error handling pipelines spanning multiple classes, files, or methods.
  • Remedy: Extract shared rules into pure functions or composed helpers; consider base abstractions only when duplicated logic shares lifecycle, dependencies, and ownership. Each call site retains its own transaction-boundary verification.
  • Micro-Snippet:
text
     Smell:  ServiceA and ServiceB replicate identical decision logic inside their own transactions.
     Remedy: Extract a pure function accepting a state snapshot; each service retains its own transaction, lock, and state read.
  1. Coupling & Encapsulation Bleed
  • Smell: Methods manipulating internal data of external classes (Feature Envy); classes exposing mutable internal collections directly via getters.
  • Remedy: Apply "Tell, Don't Ask"; encapsulate state mutations behind domain methods; return immutable snapshots or defensive copies.
  • Micro-Snippet:
text
     Smell:  if (order.getCustomer().getAddress().getCountry().equals("US")) { ... }
     Remedy: if (order.isDomesticDelivery()) { ... }
  1. Polymorphism & Strategy Deficits (Scattered Branching)
  • Smell: Parallel switch(type) or if (type == A) cascades scattered across multiple classes, inducing Shotgun Surgery on variant changes.
  • Remedy: Consider Strategy or Polymorphism when variants evolve independently and new variants force multi-file edits. Prefer explicit conditionals when branches are cohesive cases of one policy in one location; evaluate cohesion and change cost before extraction.
  • Micro-Snippet:
text
     Smell:  PaymentService, InvoiceService, and EmailService all maintain parallel switch (user.getPlanTier()).
     Remedy: Encapsulate tier-specific behaviors in PlanTier strategies (three independent services change in lockstep per new tier).
  1. Robustness & Resource Hygiene
  • Smell: Swallowing errors via empty catch blocks; unmanaged streams, database connection handles, or event listeners lacking cleanup hooks.
  • Remedy: Explicitly handle or rethrow with contextual metadata; encapsulate resource lifecycles within deterministic disposal blocks (defer, finally, using).
  • Micro-Snippet:
text
     Smell:  try { connect(); } catch (Exception e) {}
     Remedy: try { connect(); } catch (Exception e) { logger.error("DB connection failed", e); throw new ServiceUnavailableException(e); }

Canonical Output Contract

markdown
# 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)*

Routing

  • Multi-file structural refactoring, God class decomposition, or shared abstraction extraction → (via /changeset).
  • Suspected runtime functional bugs or test failures → (via /diagnose).

Execution Protocol

Phase 1: Scope Triage & Macro Grounding

  1. Ingest target path (file, directory, or subsystem).
  2. Identify primary structural anchors (classes, module entrypoints, shared utilities) using symbol and file tools.

Phase 2: Scale-Adaptive Inspection

  • In-Turn Execution (< 10 files or cohesive module): Audit code directly in-turn against rubric dimensions.
  • Subagent Fan-Out (broad multi-package subsystems or repositories): Launch concurrent research subagents dynamically scaled to partitioned slices or caller-declared budget (Role: Structural Inspector (<Slice>)), seeded with slice coordinates, discovered anchors, Domain Rubric, and Canonical Output Contract.

Phase 3: Synthesis & Turn-Halt Gate (Fan-in)

  1. Reconcile and deduplicate subagent findings into the Canonical Output Contract.
  2. Assign definitive Health Rating:
  • CLEAN: Zero structural defects breaching rubric.
  • MODERATE_DEBT: Isolated encapsulation leaks, scattered conditionals, or minor duplication.
  • CRITICAL_DEBT: Pervasive God classes, cross-subsystem copy-paste, or systemic resource leaks.
  1. Emit the completed Inspection Dossier into conversation stream and halt turn immediately.
같은 저장소의 Skills

더 많은 Skills

모든 Skills