Day 7: AST & Static Analysis Scripts

---
name: spring-boot-unit-tester
schema-version: "1.0.0"
description: >
  Generates and refactors deterministic, isolated Kotlin unit tests for Spring Boot 3.x 
  using MockK and AssertJ. MUST NOT load Spring ApplicationContext.
tools:
  - name: inspect-class-context
    description: Extracts concise AST skeleton (constructor dependencies and public methods) from target source file.
    file: scripts/inspect-class-context.sh
  - name: run-unit-tests
    description: Runs static linting and sandboxed Maven test execution with automatic failure triage.
    file: scripts/run-unit-tests.sh
metadata:
  domain: "backend-quality"
  target-framework: "Spring Boot 3.x / Kotlin 1.9+"
---

# Spring Boot Unit Test Architect Specification

## 1. Two-Phase Execution Protocol
Whenever generating a new unit test for an existing service class, the Host Agent MUST follow this two-phase sequence:

### Phase 1: Pre-flight AST Context Inspection

1. Invoke tool: `bash .github/skills/spring-boot-unit-tester/scripts/inspect-class-context.sh <TARGET_SOURCE_FILE.kt>`
2. Parse the emitted Markdown Skeleton from stdout:
   - Identify constructor dependencies to instantiate via `mockk<T>()`.
   - Identify methods marked with `[SUSPEND]` to stub using `coEvery { ... }` instead of `every { ... }`.
   - Identify parameter types and return signatures to construct realistic mock fixtures.

### Phase 2: Code Generation & Sandboxed Verification
1. Scaffold the pure unit test conforming to Day 3 Negative Invariants and Day 4 PRS Exemplars.
2. Execute verification runner: `bash .github/skills/spring-boot-unit-tester/scripts/run-unit-tests.sh <TARGET_TEST_FILE.kt>`
3. If non-zero exit occurs, parse stderr triage report and self-correct (Max 3 iterations).
          

#!/usr/bin/env python3
"""
scripts/extract-target-ast.py
Extracts class declaration, constructor dependencies, and public method signatures
from Kotlin/Java source files. Emits a dense Markdown Symbol Skeleton (< 120 tokens).
"""
import sys
import re

# // [TODAY'S LESSON PLUGS IN HERE: AST SYMBOL EXTRACTION]
def extract_skeleton(source_text: str) -> dict:
    skeleton = {
        "package": "Unknown",
        "class_name": "Unknown",
        "class_annotations": [],
        "constructor_params": [],
        "methods": []
    }

    # 1. Package Extractor
    pkg_match = re.search(r"package\s+([a-zA-Z0-9_.]+)", source_text)
    if pkg_match:
        skeleton["package"] = pkg_match.group(1)

    # 2. Class Declaration & Primary Constructor
    # Matches: class OrderSettlementService(val repo: OrderRepository, private val client: PaymentClient)
    class_pattern = re.compile(
        r"(?:@([a-zA-Z0-9_]+)\s+)*"
        r"(?:open\s+|data\s+|sealed\s+)?class\s+([a-zA-Z0-9_]+)"
        r"(?:\s*constructor\s*)?"
        r"\s*(?:\(([\s\S]*?)\))?"
    )
    
    class_match = class_pattern.search(source_text)
    if class_match:
        if class_match.group(1):
            skeleton["class_annotations"] = [class_match.group(1)]
        skeleton["class_name"] = class_match.group(2)
        
        raw_params = class_match.group(3)
        if raw_params:
            # Parse individual constructor parameters
            for param in raw_params.split(","):
                param = param.strip()
                if not param:
                    continue
                # Clean out val/var/private/override keywords
                clean_param = re.sub(r"\b(val|var|private|protected|public|override)\b", "", param).strip()
                if ":" in clean_param:
                    p_name, p_type = clean_param.split(":", 1)
                    skeleton["constructor_params"].append({
                        "name": p_name.strip(),
                        "type": p_type.strip()
                    })

    # 3. Public Method Signatures
    # Matches: [suspend] fun processOrder(orderId: UUID): SettlementResult
    method_pattern = re.compile(
        r"^\s*(?:@([a-zA-Z0-9_]+)\s+)*"
        r"(suspend\s+)?fun\s+([a-zA-Z0-9_]+)\s*\(([\s\S]*?)\)\s*(?::\s*([a-zA-Z0-9_<>,?\s]+))?",
        re.MULTILINE
    )

    for match in method_pattern.finditer(source_text):
        is_suspend = bool(match.group(2))
        method_name = match.group(3)
        raw_args = match.group(4).strip().replace("\n", " ")
        raw_return = match.group(5) or "Unit"
        
        # Clean arguments: strip default values
        clean_args = re.sub(r"\s*=\s*[^,)]+", "", raw_args).strip()
        clean_return = raw_return.strip()

        # Skip private/internal conventions if preceded by private
        line_start = source_text[max(0, match.start() - 25):match.start()]
        if "private" in line_start or "internal" in line_start:
            continue

        skeleton["methods"].append({
            "name": method_name,
            "is_suspend": is_suspend,
            "signature": f"fun {method_name}({clean_args}): {clean_return}"
        })

    return skeleton

def format_markdown_card(skeleton: dict) -> str:
    """Formats skeleton into an ultra-dense markdown block tailored for LLM prompt ingestion."""
    lines = [
        "### 📦 TARGET CLASS SKELETON CONTRACT",
        f"- **Package**: `{skeleton['package']}`",
        f"- **Class**: `{skeleton['class_name']}`",
        "- **Constructor Injected Dependencies (MUST mock via `mockk()`):**"
    ]
    
    if skeleton["constructor_params"]:
        for p in skeleton["constructor_params"]:
            lines.append(f"  - `{p['name']}: {p['type']}`")
    else:
        lines.append("  - *(No constructor parameters / No dependencies)*")

    lines.append("- **Public Method Endpoints:**")
    if skeleton["methods"]:
        for m in skeleton["methods"]:
            tag = " `[SUSPEND]`" if m["is_suspend"] else ""
            lines.append(f"  - `{m['signature']}`{tag}")
    else:
        lines.append("  - *(No public methods detected)*")

    lines.append("")
    lines.append("💡 *Guidance: Mock all constructor dependencies. Wrap `[SUSPEND]` methods inside `runTest` using `coEvery`.*")
    return "\n".join(lines)

def main():
    if len(sys.argv) < 2:
        source_text = sys.stdin.read()
    else:
        with open(sys.argv[1], "r", encoding="utf-8", errors="ignore") as f:
            source_text = f.read()

    skeleton = extract_skeleton(source_text)
    sys.stdout.write(format_markdown_card(skeleton) + "\n")

if __name__ == "__main__":
    main()