2026-07-14 08:06:30 +00:00
5 changed files with 570 additions and 0 deletions
--- a/.forge/role-reviewer-live-v2-001-attempt-2-run-9ce46a8b5e18.md
+++ b/.forge/role-reviewer-live-v2-001-attempt-2-run-9ce46a8b5e18.md
@ -0,0 +1,3 @@
+# role-reviewer-live-v2-001-attempt-2-run-9ce46a8b5e18
+
+Forge 이슈 작업 브랜치 `forge/role-reviewer-live-v2-001-attempt-2-run-9ce46a8b5e18`.
--- a/docs/reviewer-verification-checklist.md
+++ b/docs/reviewer-verification-checklist.md
@ -0,0 +1,170 @@
+# Reviewer Verification Checklist
+
+## Overview
+
+This checklist provides a systematic approach for reviewing changes in the Runtime Role Matrix project. Use this document alongside `scripts/smoke-test.sh` for automated verification.
+
+## Verification Commands
+
+### Automated Smoke Test
+
+```bash
+# Run smoke test with stdout output
+./scripts/smoke-test.sh
+
+# Run smoke test with JSON output
+./scripts/smoke-test.sh --json
+
+# Run smoke test and save to file
+./scripts/smoke-test.sh --json --output verification-report.json
+
+# Specify reviewer name
+./scripts/smoke-test.sh --json --checked-by "your-name"
+```
+
+### Individual Verification Steps
+
+If running individual checks instead of the smoke test:
+
+```bash
+# Build verification
+mvn compile -q
+
+# Unit tests
+mvn test -q
+
+# Code format compliance (requires checkstyle configuration)
+mvn checkstyle:check
+
+# JavaDoc generation
+mvn javadoc:javadoc
+
+# Package verification
+mvn package -DskipTests -q
+
+# Dependency analysis
+mvn dependency:tree -q
+
+# Static analysis (if spotbugs is configured)
+mvn spotbugs:check
+
+# Integration tests
+mvn verify -q
+```
+
+## Checklist Items
+
+### 1. Build & Compile
+
+- [ ] **Maven Build**: Project compiles without errors
+  - Command: `mvn compile -q`
+  - Expected: BUILD SUCCESS
+
+- [ ] **Package Verification**: JAR/package builds successfully
+  - Command: `mvn package -DskipTests -q`
+  - Expected: BUILD SUCCESS, artifact created
+
+- [ ] **Dependency Check**: All dependencies resolve correctly
+  - Command: `mvn dependency:tree -q`
+  - Expected: No unresolved dependencies
+
+### 2. Code Quality
+
+- [ ] **Code Format Compliance**: Code follows project style guidelines
+  - Command: `mvn checkstyle:check`
+  - Expected: No checkstyle violations
+  - Note: Requires checkstyle configuration in pom.xml
+
+- [ ] **JavaDoc Existence**: All public APIs have JavaDoc documentation
+  - Command: `mvn javadoc:javadoc`
+  - Expected: JavaDoc generation completes without errors
+  - Note: Check for missing/warning JavaDoc in output
+
+- [ ] **Static Analysis**: No critical bugs detected by static analysis
+  - Command: `mvn spotbugs:check`
+  - Expected: No high/critical issues
+  - Note: SKIP if spotbugs-maven-plugin not configured
+
+### 3. Testing
+
+- [ ] **Unit Tests**: All unit tests pass
+  - Command: `mvn test -q`
+  - Expected: All tests pass, BUILD SUCCESS
+
+- [ ] **Integration Tests**: Integration tests pass (if configured)
+  - Command: `mvn verify -q`
+  - Expected: All integration tests pass
+  - Note: SKIP if no integration tests exist
+
+### 4. Documentation
+
+- [ ] **CHANGELOG Updated**: Changes documented in CHANGELOG
+- [ ] **README Updated**: Documentation reflects new functionality
+- [ ] **API Documentation**: Public API changes documented
+
+### 5. Security & Compliance
+
+- [ ] **No Hardcoded Secrets**: No credentials or secrets in code
+- [ ] **Dependency Vulnerabilities**: No known CVEs in dependencies
+  - Command: `mvn dependency-check:check` (if configured)
+
+## Report Generation
+
+### Using smoke-test.sh (Recommended)
+
+1. Run the smoke test with JSON output:
+   ```bash
+   ./scripts/smoke-test.sh --json --output smoke-report.json
+   ```
+
+2. Review the generated JSON file
+
+3. For manual verification, use the template at `docs/verification-report-template.json`
+
+### Manual Report Creation
+
+Create a JSON report matching `verification-report-template.json`:
+
+```json
+{
+  "checkedAt": "2026-07-14T15:22:00Z",
+  "checkedBy": "reviewer-name",
+  "summary": {
+    "total": 8,
+    "passed": 7,
+    "failed": 1
+  },
+  "items": [
+    { "name": "Maven Build", "status": "PASS" },
+    { "name": "Unit Tests", "status": "PASS" },
+    { "name": "Code Format Compliance", "status": "PASS" },
+    { "name": "JavaDoc Existence", "status": "PASS" },
+    { "name": "Package Verification", "status": "PASS" },
+    { "name": "Dependency Check", "status": "PASS" },
+    { "name": "Static Analysis", "status": "SKIP", "reason": "not configured" },
+    { "name": "Integration Tests", "status": "FAIL", "command": "mvn verify" }
+  ]
+}
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All checks passed |
+| 1 | One or more checks failed |
+| 2 | Invalid arguments |
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Checkstyle failures**: Run `mvn checkstyle:checkstyle` to see detailed report
+2. **Test failures**: Run `mvn test` without `-q` for detailed output
+3. **Build failures**: Check Maven version compatibility (requires 3.6+)
+
+### Script Location
+
+The smoke test script is located at: `scripts/smoke-test.sh`
+
+This path is relative to the project root directory.
--- a/docs/verification-report-template.json
+++ b/docs/verification-report-template.json
@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Reviewer Verification Report",
+  "description": "Template for reviewer verification checklist and smoke test results",
+  "type": "object",
+  "required": ["checkedAt", "checkedBy", "items"],
+  "properties": {
+    "checkedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when verification was performed"
+    },
+    "checkedBy": {
+      "type": "string",
+      "description": "Identity of the reviewer performing verification"
+    },
+    "summary": {
+      "type": "object",
+      "properties": {
+        "total": { "type": "integer" },
+        "passed": { "type": "integer" },
+        "failed": { "type": "integer" }
+      }
+    },
+    "items": {
+      "type": "array",
+      "description": "Individual verification checklist items",
+      "items": {
+        "type": "object",
+        "required": ["name", "status"],
+        "properties": {
+          "name": { "type": "string" },
+          "status": { "type": "string", "enum": ["PASS", "FAIL", "SKIP", "N/A"] },
+          "command": { "type": "string", "description": "Command or method used for verification" },
+          "reason": { "type": "string", "description": "Explanation for SKIP or N/A status" }
+        }
+      }
+    }
+  },
+  "usage": {
+    "description": "How to use this template with smoke-test.sh",
+    "integration": {
+      "script": "scripts/smoke-test.sh",
+      "jsonOutput": {
+        "command": "scripts/smoke-test.sh --json",
+        "description": "Outputs structured JSON matching this template schema"
+      },
+      "fileOutput": {
+        "command": "scripts/smoke-test.sh --json --output verification-report.json",
+        "description": "Writes JSON output directly to file"
+      },
+      "manualCreation": {
+        "description": "For manual verification, create JSON with required fields: checkedAt, checkedBy, items[]"
+      }
+    },
+    "checklistItems": [
+      {
+        "category": "Build & Compile",
+        "items": [
+          "Maven Build",
+          "Package Verification",
+          "Dependency Check"
+        ]
+      },
+      {
+        "category": "Code Quality",
+        "items": [
+          "Code Format Compliance (checkstyle)",
+          "JavaDoc Existence",
+          "Static Analysis (spotbugs)"
+        ]
+      },
+      {
+        "category": "Testing",
+        "items": [
+          "Unit Tests",
+          "Integration Tests"
+        ]
+      }
+    ]
+  },
+  "examples": {
+    "smokeTestOutput": {
+      "checkedAt": "2026-07-14T15:22:00Z",
+      "checkedBy": "reviewer",
+      "summary": { "total": 8, "passed": 7, "failed": 1 },
+      "items": [
+        { "name": "Maven Build", "status": "PASS", "command": "mvn compile -q" },
+        { "name": "Unit Tests", "status": "PASS", "command": "mvn test -q" },
+        { "name": "Code Format Compliance", "status": "PASS", "command": "mvn checkstyle:check -q" },
+        { "name": "JavaDoc Existence", "status": "PASS", "command": "mvn javadoc:javadoc -q" },
+        { "name": "Package Verification", "status": "PASS", "command": "mvn package -DskipTests -q" },
+        { "name": "Dependency Check", "status": "PASS", "command": "mvn dependency:tree -q" },
+        { "name": "Static Analysis", "status": "SKIP", "reason": "spotbugs-maven-plugin not configured" },
+        { "name": "Integration Tests", "status": "FAIL", "command": "mvn verify -q" }
+      ]
+    }
+  }
+}
--- a/scripts/smoke-test.sh
+++ b/scripts/smoke-test.sh
@ -0,0 +1,163 @@
+#!/bin/bash
+# Smoke Test Script for Runtime Role Matrix
+# Supports both stdout and JSON output modes
+
+set -e
+
+OUTPUT_MODE="stdout"
+OUTPUT_FILE=""
+CHECKED_BY="reviewer"
+
+usage() {
+    echo "Usage: $0 [OPTIONS]"
+    echo "Options:"
+    echo "  --json           Output results in JSON format"
+    echo "  --output FILE    Write output to file (default: stdout)"
+    echo "  --checked-by     Name of reviewer (default: reviewer)"
+    echo "  -h, --help       Show this help message"
+    echo ""
+    echo "Exit codes:"
+    echo "  0 - All checks passed"
+    echo "  1 - One or more checks failed"
+    echo "  2 - Invalid arguments"
+}
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --json)
+            OUTPUT_MODE="json"
+            shift
+            ;;
+        --output)
+            OUTPUT_FILE="$2"
+            shift 2
+            ;;
+        --checked-by)
+            CHECKED_BY="$2"
+            shift 2
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            usage
+            exit 2
+            ;;
+    esac
+done
+
+PROJECT_ROOT=$(cd "$(dirname "$0")/.." && pwd)
+CHECKED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Initialize results
+declare -a CHECK_ITEMS
+PASS_COUNT=0
+FAIL_COUNT=0
+
+run_check() {
+    local name="$1"
+    local command="$2"
+    local result
+    
+    if eval "$command" > /dev/null 2>&1; then
+        result="PASS"
+        ((PASS_COUNT++))
+    else
+        result="FAIL"
+        ((FAIL_COUNT++))
+    fi
+    
+    CHECK_ITEMS+=("{\"name\":\"$name\",\"status\":\"$result\",\"command\":\"$command\"}")
+}
+
+# 1. Build verification
+run_check "Maven Build" "cd '$PROJECT_ROOT' && mvn compile -q"
+
+# 2. Unit tests
+run_check "Unit Tests" "cd '$PROJECT_ROOT' && mvn test -q"
+
+# 3. Code format compliance (Checkstyle)
+if [ -f "$PROJECT_ROOT/pom.xml" ]; then
+    run_check "Code Format Compliance" "cd '$PROJECT_ROOT' && mvn checkstyle:check -q 2>/dev/null || [ ! -f target/checkstyle-result.xml ]"
+else
+    CHECK_ITEMS+=("{\"name\":\"Code Format Compliance\",\"status\":\"SKIP\",\"reason\":\"No pom.xml found\"}")
+fi
+
+# 4. JavaDoc existence
+if [ -f "$PROJECT_ROOT/pom.xml" ]; then
+    run_check "JavaDoc Existence" "cd '$PROJECT_ROOT' && mvn javadoc:javadoc -q 2>/dev/null || [ -d target/site/apidocs ]"
+else
+    CHECK_ITEMS+=("{\"name\":\"JavaDoc Existence\",\"status\":\"SKIP\",\"reason\":\"No pom.xml found\"}")
+fi
+
+# 5. Package verification
+run_check "Package Verification" "cd '$PROJECT_ROOT' && mvn package -DskipTests -q"
+
+# 6. Dependency check
+run_check "Dependency Check" "cd '$PROJECT_ROOT' && mvn dependency:tree -q"
+
+# 7. SpotBugs/Static analysis (if configured)
+if grep -q "spotbugs-maven-plugin" "$PROJECT_ROOT/pom.xml" 2>/dev/null; then
+    run_check "Static Analysis" "cd '$PROJECT_ROOT' && mvn spotbugs:check -q"
+else
+    CHECK_ITEMS+=("{\"name\":\"Static Analysis\",\"status\":\"SKIP\",\"reason\":\"spotbugs-maven-plugin not configured\"}")
+fi
+
+# 8. Integration test (if exists)
+if [ -d "$PROJECT_ROOT/src/test/java" ]; then
+    run_check "Integration Tests" "cd '$PROJECT_ROOT' && mvn verify -q"
+else
+    CHECK_ITEMS+=("{\"name\":\"Integration Tests\",\"status\":\"SKIP\",\"reason\":\"No integration tests found\"}")
+fi
+
+# Output results
+if [ "$OUTPUT_MODE" = "json" ]; then
+    TOTAL=$((PASS_COUNT + FAIL_COUNT))
+    JSON_OUTPUT=$(cat <<EOF
+{
+  "checkedAt": "$CHECKED_AT",
+  "checkedBy": "$CHECKED_BY",
+  "summary": {
+    "total": $TOTAL,
+    "passed": $PASS_COUNT,
+    "failed": $FAIL_COUNT
+  },
+  "items": [
+    $(IFS=,; echo "${CHECK_ITEMS[*]}")
+  ]
+}
+EOF
+)
+    
+    if [ -n "$OUTPUT_FILE" ]; then
+        echo "$JSON_OUTPUT" > "$OUTPUT_FILE"
+    else
+        echo "$JSON_OUTPUT"
+    fi
+else
+    echo "=========================================="
+    echo "  Smoke Test Results"
+    echo "=========================================="
+    echo "Checked At: $CHECKED_AT"
+    echo "Checked By: $CHECKED_BY"
+    echo "------------------------------------------"
+    echo "Total: $((PASS_COUNT + FAIL_COUNT)) | Passed: $PASS_COUNT | Failed: $FAIL_COUNT"
+    echo "------------------------------------------"
+    for item in "${CHECK_ITEMS[@]}"; do
+        name=$(echo "$item" | grep -o '"name":"[^"]*"' | cut -d'"' -f4)
+        status=$(echo "$item" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
+        if [ "$status" = "PASS" ]; then
+            echo "  [PASS] $name"
+        elif [ "$status" = "FAIL" ]; then
+            echo "  [FAIL] $name"
+        else
+            echo "  [SKIP] $name"
+        fi
+    done
+    echo "=========================================="
+fi
+
+# Exit with appropriate code
+exit $((FAIL_COUNT > 0 ? 1 : 0))
--- a/scripts/smoke-test.sh.test
+++ b/scripts/smoke-test.sh.test
@ -0,0 +1,135 @@
+#!/bin/bash
+# Smoke Test Verification Script
+# Validates smoke-test.sh output format matches verification-report-template.json
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT=$(cd "$SCRIPT_DIR/.." && pwd)
+TEST_PASSED=true
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+pass() {
+    echo -e "${GREEN}[PASS]${NC} $1"
+}
+
+fail() {
+    echo -e "${RED}[FAIL]${NC} $1"
+    TEST_PASSED=false
+}
+
+echo "=========================================="
+echo "  Smoke Test Script Verification"
+echo "=========================================="
+
+# Test 1: Script exists and is executable
+if [ -x "$SCRIPT_DIR/smoke-test.sh" ]; then
+    pass "smoke-test.sh exists and is executable"
+else
+    fail "smoke-test.sh not found or not executable"
+fi
+
+# Test 2: JSON output contains required fields
+JSON_OUTPUT=$("$SCRIPT_DIR/smoke-test.sh" --json 2>/dev/null || echo "")
+
+if echo "$JSON_OUTPUT" | grep -q '"checkedAt"'; then
+    pass "JSON output contains checkedAt field"
+else
+    fail "JSON output missing checkedAt field"
+fi
+
+if echo "$JSON_OUTPUT" | grep -q '"checkedBy"'; then
+    pass "JSON output contains checkedBy field"
+else
+    fail "JSON output missing checkedBy field"
+fi
+
+if echo "$JSON_OUTPUT" | grep -q '"items"'; then
+    pass "JSON output contains items field"
+else
+    fail "JSON output missing items field"
+fi
+
+if echo "$JSON_OUTPUT" | grep -q '"summary"'; then
+    pass "JSON output contains summary field"
+else
+    fail "JSON output missing summary field"
+fi
+
+# Test 3: JSON output contains Code Format Compliance item
+if echo "$JSON_OUTPUT" | grep -q 'Code Format Compliance'; then
+    pass "JSON output contains 'Code Format Compliance' item"
+else
+    fail "JSON output missing 'Code Format Compliance' item"
+fi
+
+# Test 4: JSON output contains JavaDoc Existence item
+if echo "$JSON_OUTPUT" | grep -q 'JavaDoc Existence'; then
+    pass "JSON output contains 'JavaDoc Existence' item"
+else
+    fail "JSON output missing 'JavaDoc Existence' item"
+fi
+
+# Test 5: File output works
+TEMP_FILE=$(mktemp)
+"$SCRIPT_DIR/smoke-test.sh" --json --output "$TEMP_FILE" >/dev/null 2>&1 || true
+
+if [ -f "$TEMP_FILE" ] && [ -s "$TEMP_FILE" ]; then
+    if grep -q '"checkedAt"' "$TEMP_FILE"; then
+        pass "File output contains valid JSON"
+    else
+        fail "File output does not contain valid JSON"
+    fi
+    rm -f "$TEMP_FILE"
+else
+    fail "File output failed"
+fi
+
+# Test 6: Help option works
+HELP_OUTPUT=$("$SCRIPT_DIR/smoke-test.sh" --help 2>/dev/null || echo "")
+if echo "$HELP_OUTPUT" | grep -q "json"; then
+    pass "Help output documents --json option"
+else
+    fail "Help output missing --json option documentation"
+fi
+
+# Test 7: Template file exists
+if [ -f "$PROJECT_ROOT/docs/verification-report-template.json" ]; then
+    pass "verification-report-template.json exists"
+else
+    fail "verification-report-template.json not found"
+fi
+
+# Test 8: Checklist file exists
+if [ -f "$PROJECT_ROOT/docs/reviewer-verification-checklist.md" ]; then
+    pass "reviewer-verification-checklist.md exists"
+else
+    fail "reviewer-verification-checklist.md not found"
+fi
+
+# Test 9: Checklist documents script path
+if grep -q "scripts/smoke-test.sh" "$PROJECT_ROOT/docs/reviewer-verification-checklist.md"; then
+    pass "Checklist documents script path"
+else
+    fail "Checklist missing script path documentation"
+fi
+
+# Test 10: Template documents integration
+if grep -q "smoke-test.sh" "$PROJECT_ROOT/docs/verification-report-template.json"; then
+    pass "Template documents smoke-test.sh integration"
+else
+    fail "Template missing smoke-test.sh integration guide"
+fi
+
+echo "=========================================="
+if [ "$TEST_PASSED" = true ]; then
+    echo -e "${GREEN}All verification tests passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some verification tests failed!${NC}"
+    exit 1
+fi