dev-playbooks-cn 1.0.0

package/skills/devbooks-delivery-workflow/scripts/ac-trace-check.sh

@@ -0,0 +1,330 @@
+#!/bin/bash
+# skills/devbooks-delivery-workflow/scripts/ac-trace-check.sh
+# AC-ID Traceability Coverage Check Script
+#
+# Checks the traceability coverage of AC-IDs from design to tests.
+#
+# Usage:
+#   ./ac-trace-check.sh <change-id> [options]
+#   ./ac-trace-check.sh --help
+#
+# Options:
+#   --threshold N       Coverage threshold (default 80)
+#   --output FORMAT     Output format (text|json, default text)
+#   --project-root DIR  Project root directory
+#   --change-root DIR   Change package directory
+#
+# Exit codes:
+#   0 - Coverage meets threshold
+#   1 - Coverage below threshold
+#   2 - Usage error
+
+set -euo pipefail
+
+# Version
+VERSION="1.0.0"
+
+# Defaults
+threshold=80
+output_format="text"
+project_root="."
+change_root="changes"
+
+# Color output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# Show help
+show_help() {
+    cat << 'EOF'
+AC-ID Traceability Coverage Check Script (ac-trace-check.sh)
+
+Usage:
+  ./ac-trace-check.sh <change-id> [options]
+
+Options:
+  --threshold N       Coverage threshold, default 80 (percentage)
+  --output FORMAT     Output format: text | json, default text
+  --project-root DIR  Project root directory, default is current directory
+  --change-root DIR   Change package directory, default is changes
+  --help, -h          Show this help message
+  --version, -v       Show version information
+
+Algorithm:
+  1. Extract all AC-xxx from design.md
+  2. Extract AC-xxx referenced in tasks.md
+  3. Extract AC-xxx marked in tests/
+  4. Calculate: Coverage = (traced AC count) / (total AC count) x 100%
+  5. Compare against threshold, return exit code
+
+Exit codes:
+  0 - Coverage meets threshold
+  1 - Coverage below threshold
+  2 - Usage error
+
+Examples:
+  ./ac-trace-check.sh my-feature                     # Default check
+  ./ac-trace-check.sh my-feature --threshold 90     # 90% threshold
+  ./ac-trace-check.sh my-feature --output json      # JSON output
+  ./ac-trace-check.sh my-feature --change-root dev-playbooks/changes
+
+EOF
+}
+
+# Show version
+show_version() {
+    echo "ac-trace-check.sh v${VERSION}"
+}
+
+# Log functions
+log_info() {
+    [[ "$output_format" == "text" ]] && echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_pass() {
+    [[ "$output_format" == "text" ]] && echo -e "${GREEN}[PASS]${NC} $*"
+}
+
+log_fail() {
+    [[ "$output_format" == "text" ]] && echo -e "${RED}[FAIL]${NC} $*"
+}
+
+log_warn() {
+    [[ "$output_format" == "text" ]] && echo -e "${YELLOW}[WARN]${NC} $*"
+}
+
+# Extract AC-IDs
+extract_ac_ids() {
+    local file="$1"
+    grep -oE "AC-[A-Z0-9]+" "$file" 2>/dev/null | sort -u || true
+}
+
+# Extract AC-IDs from directory
+extract_ac_ids_from_dir() {
+    local dir="$1"
+    local pattern="${2:-*.test.*}"
+    find "$dir" -type f \( -name "*.test.ts" -o -name "*.test.js" -o -name "*.spec.ts" -o -name "*.spec.js" -o -name "*.bats" -o -name "*_test.py" -o -name "*_test.go" \) 2>/dev/null | while read -r file; do
+        grep -oE "AC-[A-Z0-9]+" "$file" 2>/dev/null || true
+    done | sort -u
+}
+
+# Calculate coverage
+calculate_coverage() {
+    local design_acs="$1"
+    local tasks_acs="$2"
+    local test_acs="$3"
+
+    # Get AC lists
+    local design_list=()
+    local tasks_list=()
+    local test_list=()
+    local covered_list=()
+    local uncovered_list=()
+
+    while IFS= read -r ac; do
+        [[ -n "$ac" ]] && design_list+=("$ac")
+    done <<< "$design_acs"
+
+    while IFS= read -r ac; do
+        [[ -n "$ac" ]] && tasks_list+=("$ac")
+    done <<< "$tasks_acs"
+
+    while IFS= read -r ac; do
+        [[ -n "$ac" ]] && test_list+=("$ac")
+    done <<< "$test_acs"
+
+    local total=${#design_list[@]}
+
+    if [[ $total -eq 0 ]]; then
+        # No ACs, count as 100% coverage
+        echo "100 0 0"
+        return
+    fi
+
+    # Calculate covered ACs
+    local covered=0
+    for ac in "${design_list[@]}"; do
+        local in_test=false
+        for test_ac in "${test_list[@]}"; do
+            if [[ "$ac" == "$test_ac" ]]; then
+                in_test=true
+                covered_list+=("$ac")
+                break
+            fi
+        done
+        if [[ "$in_test" == false ]]; then
+            uncovered_list+=("$ac")
+        else
+            covered=$((covered + 1))
+        fi
+    done
+
+    local rate=0
+    if [[ $total -gt 0 ]]; then
+        rate=$((covered * 100 / total))
+    fi
+
+    echo "$rate $covered $total"
+
+    # Output uncovered list to stderr
+    if [[ ${#uncovered_list[@]} -gt 0 && "$output_format" == "text" ]]; then
+        echo "uncovered: ${uncovered_list[*]}" >&2
+    fi
+}
+
+# Main function
+main() {
+    local change_id=""
+
+    # Parse arguments
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                show_help
+                exit 0
+                ;;
+            --version|-v)
+                show_version
+                exit 0
+                ;;
+            --threshold)
+                threshold="${2:-80}"
+                shift 2
+                ;;
+            --output)
+                output_format="${2:-text}"
+                shift 2
+                ;;
+            --project-root)
+                project_root="${2:-.}"
+                shift 2
+                ;;
+            --change-root)
+                change_root="${2:-changes}"
+                shift 2
+                ;;
+            -*)
+                echo "error: unknown option: $1" >&2
+                echo "Use --help for usage" >&2
+                exit 2
+                ;;
+            *)
+                change_id="$1"
+                shift
+                ;;
+        esac
+    done
+
+    # Validate arguments
+    if [[ -z "$change_id" ]]; then
+        echo "error: missing change-id" >&2
+        echo "Use --help for usage" >&2
+        exit 2
+    fi
+
+    # Build paths
+    local change_dir
+    if [[ "$change_root" = /* ]]; then
+        change_dir="${change_root}/${change_id}"
+    else
+        change_dir="${project_root}/${change_root}/${change_id}"
+    fi
+
+    local design_file="${change_dir}/design.md"
+    local tasks_file="${change_dir}/tasks.md"
+    local tests_dir="${project_root}/tests"
+
+    log_info "Checking change package: ${change_id}"
+    log_info "Design file: ${design_file}"
+    log_info "Tasks file: ${tasks_file}"
+    log_info "Tests directory: ${tests_dir}"
+
+    # Check file exists
+    if [[ ! -f "$design_file" ]]; then
+        if [[ "$output_format" == "json" ]]; then
+            echo '{"error": "design.md not found", "coverage": 0}'
+        else
+            log_fail "design.md does not exist: ${design_file}"
+        fi
+        exit 1
+    fi
+
+    # Extract AC-IDs
+    local design_acs tasks_acs test_acs
+
+    design_acs=$(extract_ac_ids "$design_file")
+    tasks_acs=""
+    if [[ -f "$tasks_file" ]]; then
+        tasks_acs=$(extract_ac_ids "$tasks_file")
+    fi
+
+    test_acs=""
+    if [[ -d "$tests_dir" ]]; then
+        test_acs=$(extract_ac_ids_from_dir "$tests_dir")
+    fi
+
+    # Calculate coverage
+    local result
+    result=$(calculate_coverage "$design_acs" "$tasks_acs" "$test_acs")
+    read -r rate covered total <<< "$result"
+
+    # Output results
+    if [[ "$output_format" == "json" ]]; then
+        local uncovered_json="[]"
+        # Recalculate uncovered list
+        local uncovered_acs=""
+        while IFS= read -r ac; do
+            [[ -z "$ac" ]] && continue
+            if ! echo "$test_acs" | grep -qx "$ac"; then
+                if [[ -z "$uncovered_acs" ]]; then
+                    uncovered_acs="\"$ac\""
+                else
+                    uncovered_acs="${uncovered_acs},\"$ac\""
+                fi
+            fi
+        done <<< "$design_acs"
+
+        cat << EOF
+{
+  "change_id": "${change_id}",
+  "coverage": ${rate},
+  "threshold": ${threshold},
+  "covered": ${covered},
+  "total": ${total},
+  "uncovered": [${uncovered_acs}],
+  "pass": $([ "$rate" -ge "$threshold" ] && echo "true" || echo "false")
+}
+EOF
+    else
+        echo ""
+        echo "AC Traceability Coverage Report"
+        echo "================================"
+        echo "Change package: ${change_id}"
+        echo "Total ACs: ${total}"
+        echo "Covered: ${covered}"
+        echo "Coverage: ${rate}%"
+        echo "Threshold: ${threshold}%"
+        echo ""
+
+        if [[ $rate -ge $threshold ]]; then
+            log_pass "Coverage ${rate}% >= ${threshold}%, check passed"
+            exit 0
+        else
+            log_fail "Coverage ${rate}% < ${threshold}%, check failed"
+            exit 1
+        fi
+    fi
+
+    # Exit code for JSON mode
+    if [[ $rate -ge $threshold ]]; then
+        exit 0
+    else
+        exit 1
+    fi
+}
+
+# Run main function
+main "$@"

package/skills/devbooks-delivery-workflow/scripts/audit-scope.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# audit-scope.sh - Provide full-scope audit scanning for precision improvement
+#
+# This script scans a directory and outputs metrics for audit purposes:
+# - File count by type
+# - Line count
+# - Complexity metrics (if available)
+# - Hotspot file list (high churn + high complexity)
+#
+# Reference: harden-devbooks-quality-gates design.md AC-011
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF' >&2
+usage: audit-scope.sh <directory> [options]
+
+Provide full-scope audit scanning for a directory:
+- File count by type
+- Total line count
+- Complexity metrics (if tools available)
+- Hotspot identification
+
+Options:
+  --format <fmt>    Output format: text (default), markdown, json
+  --exclude <pat>   Exclude pattern (can be used multiple times)
+  -h, --help        Show this help message
+
+Exit Codes:
+  0 - Scan completed successfully
+  1 - Scan error or directory not found
+  2 - Usage error
+
+Examples:
+  audit-scope.sh src/
+  audit-scope.sh src/ --format markdown
+  audit-scope.sh src/ --format json --exclude node_modules
+EOF
+}
+
+if [[ $# -eq 0 ]]; then
+  usage
+  exit 2
+fi
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+target_dir="$1"
+shift
+
+output_format="text"
+declare -a exclude_patterns=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --format)
+      output_format="${2:-text}"
+      shift 2
+      ;;
+    --exclude)
+      exclude_patterns+=("${2:-}")
+      shift 2
+      ;;
+    *)
+      echo "error: unknown option: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+# Validate format
+case "$output_format" in
+  text|markdown|json) ;;
+  *)
+    echo "error: invalid --format: '$output_format' (use: text, markdown, json)" >&2
+    exit 2
+    ;;
+esac
+
+# Check directory exists
+if [[ ! -d "$target_dir" ]]; then
+  echo "error: directory not found: ${target_dir}" >&2
+  exit 1
+fi
+
+# Build find exclude arguments as array
+declare -a find_exclude_args=()
+if [[ ${#exclude_patterns[@]} -gt 0 ]]; then
+  for pat in "${exclude_patterns[@]}"; do
+    find_exclude_args+=(-not -path "*/${pat}/*")
+  done
+fi
+
+# =============================================================================
+# Collect Metrics
+# =============================================================================
+
+# Count files by type
+count_files() {
+  local ext="$1"
+  find "$target_dir" -type f -name "*.$ext" ${find_exclude_args[@]+"${find_exclude_args[@]}"} 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Count total lines
+count_lines() {
+  local ext="$1"
+  find "$target_dir" -type f -name "*.$ext" ${find_exclude_args[@]+"${find_exclude_args[@]}"} -exec cat {} \; 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Total file count
+total_files=$(find "$target_dir" -type f ${find_exclude_args[@]+"${find_exclude_args[@]}"} 2>/dev/null | wc -l | tr -d ' ')
+
+# Count by common types
+sh_count=$(count_files "sh")
+ts_count=$(count_files "ts")
+js_count=$(count_files "js")
+md_count=$(count_files "md")
+yml_count=$(count_files "yml")
+yaml_count=$(count_files "yaml")
+json_count=$(count_files "json")
+py_count=$(count_files "py")
+
+# Line counts
+sh_lines=$(count_lines "sh")
+ts_lines=$(count_lines "ts")
+js_lines=$(count_lines "js")
+
+# Total lines (for major code types)
+total_lines=$((sh_lines + ts_lines + js_lines))
+
+# Identify potential hotspots (largest files)
+hotspots=""
+if command -v wc >/dev/null 2>&1; then
+  hotspots=$(find "$target_dir" -type f \( -name "*.sh" -o -name "*.ts" -o -name "*.js" -o -name "*.py" \) ${find_exclude_args[@]+"${find_exclude_args[@]}"} -exec wc -l {} \; 2>/dev/null | sort -rn | head -10)
+fi
+
+# =============================================================================
+# Output
+# =============================================================================
+
+case "$output_format" in
+  text)
+    echo "=================================================="
+    echo "Audit Scope: ${target_dir}"
+    echo "=================================================="
+    echo ""
+    echo "## File Count Summary"
+    echo "  Total files: ${total_files}"
+    echo "  Shell (.sh): ${sh_count}"
+    echo "  TypeScript (.ts): ${ts_count}"
+    echo "  JavaScript (.js): ${js_count}"
+    echo "  Markdown (.md): ${md_count}"
+    echo "  YAML (.yml/.yaml): $((yml_count + yaml_count))"
+    echo "  JSON (.json): ${json_count}"
+    echo "  Python (.py): ${py_count}"
+    echo ""
+    echo "## Line Count (Code)"
+    echo "  Shell: ${sh_lines}"
+    echo "  TypeScript: ${ts_lines}"
+    echo "  JavaScript: ${js_lines}"
+    echo "  Total: ${total_lines}"
+    echo ""
+    echo "## Potential Hotspots (Top 10 by line count)"
+    if [[ -n "$hotspots" ]]; then
+      echo "$hotspots" | while read -r line; do
+        echo "  $line"
+      done
+    else
+      echo "  (no code files found)"
+    fi
+    echo ""
+    ;;
+
+  markdown)
+    echo "# Audit Scope: ${target_dir}"
+    echo ""
+    echo "## File Count Summary"
+    echo ""
+    echo "| Type | Count |"
+    echo "|------|-------|"
+    echo "| Total | ${total_files} |"
+    echo "| Shell (.sh) | ${sh_count} |"
+    echo "| TypeScript (.ts) | ${ts_count} |"
+    echo "| JavaScript (.js) | ${js_count} |"
+    echo "| Markdown (.md) | ${md_count} |"
+    echo "| YAML | $((yml_count + yaml_count)) |"
+    echo "| JSON | ${json_count} |"
+    echo "| Python (.py) | ${py_count} |"
+    echo ""
+    echo "## Line Count (Code)"
+    echo ""
+    echo "| Type | Lines |"
+    echo "|------|-------|"
+    echo "| Shell | ${sh_lines} |"
+    echo "| TypeScript | ${ts_lines} |"
+    echo "| JavaScript | ${js_lines} |"
+    echo "| **Total** | **${total_lines}** |"
+    echo ""
+    echo "## Potential Hotspots"
+    echo ""
+    if [[ -n "$hotspots" ]]; then
+      echo "| Lines | File |"
+      echo "|-------|------|"
+      echo "$hotspots" | while read -r lines file; do
+        echo "| ${lines} | ${file} |"
+      done
+    else
+      echo "(no code files found)"
+    fi
+    ;;
+
+  json)
+    # Build hotspots JSON array
+    hotspots_json="[]"
+    if [[ -n "$hotspots" ]]; then
+      hotspots_json="["
+      first=true
+      while read -r lines file; do
+        if [[ "$first" == true ]]; then
+          first=false
+        else
+          hotspots_json+=","
+        fi
+        hotspots_json+="{\"lines\":${lines},\"file\":\"${file}\"}"
+      done <<< "$hotspots"
+      hotspots_json+="]"
+    fi
+
+    cat << EOF
+{
+  "directory": "${target_dir}",
+  "fileCount": {
+    "total": ${total_files},
+    "shell": ${sh_count},
+    "typescript": ${ts_count},
+    "javascript": ${js_count},
+    "markdown": ${md_count},
+    "yaml": $((yml_count + yaml_count)),
+    "json": ${json_count},
+    "python": ${py_count}
+  },
+  "lineCount": {
+    "shell": ${sh_lines},
+    "typescript": ${ts_lines},
+    "javascript": ${js_lines},
+    "total": ${total_lines}
+  },
+  "hotspots": ${hotspots_json}
+}
+EOF
+    ;;
+esac
+
+exit 0