jekyll-theme-zer0 0.7.2 → 0.10.0

data/scripts/lib/README.md

@@ -0,0 +1,291 @@
+# Release Script Libraries
+
+Modular, tested, and reusable libraries for the zer0-mistakes release automation system.
+
+## Overview
+
+This directory contains focused, single-responsibility libraries that power the release automation. Each library can be used independently or composed together for complex workflows.
+
+## Libraries
+
+### 📦 `common.sh` - Shared Utilities
+
+Core utilities used by all other libraries.
+
+**Functions:**
+
+- `log()`, `info()`, `warn()`, `error()` - Colored logging
+- `confirm()` - User confirmation prompts
+- `dry_run_exec()` - Dry run wrapper for commands
+- `require_command()`, `require_file()` - Dependency validation
+- `get_repo_root()` - Find repository root directory
+
+**Usage:**
+
+```bash
+source "$(dirname "$0")/lib/common.sh"
+log "Starting process..."
+```
+
+### 🔍 `validation.sh` - Environment Validation
+
+Validates environment, dependencies, and prerequisites.
+
+**Functions:**
+
+- `validate_git_repo()` - Verify git repository
+- `validate_clean_working_dir()` - Check for uncommitted changes
+- `validate_required_files()` - Check required files exist
+- `validate_dependencies()` - Verify all commands available
+- `validate_rubygems_auth()` - Check RubyGems credentials
+- `validate_environment()` - Comprehensive validation
+
+**Usage:**
+
+```bash
+source "$(dirname "$0")/lib/validation.sh"
+validate_environment false false  # skip_publish=false, require_gh=false
+```
+
+### 📝 `version.sh` - Version Management
+
+Read, calculate, and update semantic versions.
+
+**Functions:**
+
+- `get_current_version()` - Read version from version.rb
+- `calculate_new_version()` - Calculate new version (major/minor/patch)
+- `update_version_files()` - Update all version files
+- `validate_version_format()` - Validate semver format
+- `version_less_than()` - Compare two versions
+
+**Usage:**
+
+```bash
+source "$(dirname "$0")/lib/version.sh"
+
+current=$(get_current_version)
+new=$(calculate_new_version "$current" "minor")
+update_version_files "$new"
+```
+
+### 📋 `changelog.sh` - Changelog Generation
+
+Generate changelogs from conventional commits.
+
+**Functions:**
+
+- `generate_changelog()` - Generate changelog for version
+- `categorize_commit()` - Categorize commit by type
+- `clean_commit_message()` - Clean conventional commit prefixes
+- `extract_release_notes()` - Extract notes for specific version
+
+**Commit Categories:**
+
+- `feat:` → Added
+- `fix:` → Fixed
+- `BREAKING:` → Breaking Changes
+- `docs:`, `chore:`, `refactor:` → Changed
+- `remove:` → Removed
+- `security:` → Security
+
+**Usage:**
+
+```bash
+source "$(dirname "$0")/lib/changelog.sh"
+
+generate_changelog "1.2.0" "v1.1.0" "HEAD"
+```
+
+### 🔄 `git.sh` - Git Operations
+
+Git commits, tags, and repository operations.
+
+**Functions:**
+
+- `get_last_version_tag()` - Find last version tag
+- `commit_and_tag()` - Create release commit and tag
+- `push_changes()` - Push to remote with tags
+- `get_commits_between()` - Get commits in range
+- `get_repo_info()` - Extract owner/repo from URL
+
+**Usage:**
+
+```bash
+source "$(dirname "$0")/lib/git.sh"
+
+commit_and_tag "1.2.0"
+push_changes "origin" "main"
+```
+
+### 💎 `gem.sh` - Gem Operations
+
+Build, test, publish, and release gems.
+
+**Functions:**
+
+- `build_gem()` - Build the gem package
+- `publish_gem()` - Publish to RubyGems
+- `create_github_release()` - Create GitHub release
+- `run_tests()` - Execute test suite
+- `gem_version_exists()` - Check if version exists on RubyGems
+
+**Usage:**
+
+```bash
+source "$(dirname "$0")/lib/gem.sh"
+
+build_gem "1.2.0"
+run_tests
+publish_gem "1.2.0"
+create_github_release "1.2.0"
+```
+
+## Testing
+
+Each library has comprehensive unit tests in `test/`.
+
+### Run All Tests
+
+```bash
+./scripts/lib/test/run_tests.sh
+```
+
+### Run Individual Tests
+
+```bash
+./scripts/lib/test/test_version.sh
+./scripts/lib/test/test_changelog.sh
+./scripts/lib/test/test_git.sh
+```
+
+### Test Coverage
+
+- ✅ Version calculations and validation
+- ✅ Changelog generation and categorization
+- ✅ Git operations and tag management
+- ✅ Environment validation
+- ✅ Gem build and publish workflows
+
+## Environment Variables
+
+Control library behavior with environment variables:
+
+```bash
+# Dry run mode (no actual changes)
+DRY_RUN=true
+
+# Non-interactive mode (auto-confirm prompts)
+INTERACTIVE=false
+
+# Verbose debug output
+VERBOSE=true
+```
+
+## Example: Custom Release Script
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Source libraries
+LIB_DIR="$(dirname "$0")/lib"
+source "$LIB_DIR/common.sh"
+source "$LIB_DIR/validation.sh"
+source "$LIB_DIR/version.sh"
+source "$LIB_DIR/changelog.sh"
+source "$LIB_DIR/git.sh"
+source "$LIB_DIR/gem.sh"
+
+# Main workflow
+main() {
+    print_header "Custom Release"
+
+    # Validate
+    validate_environment
+
+    # Version
+    local current=$(get_current_version)
+    local new=$(calculate_new_version "$current" "patch")
+    update_version_files "$new"
+
+    # Changelog
+    generate_changelog "$new"
+
+    # Build & Test
+    build_gem "$new"
+    run_tests
+
+    # Commit & Tag
+    commit_and_tag "$new"
+
+    # Publish
+    publish_gem "$new"
+    create_github_release "$new"
+    push_changes
+
+    success "Release $new complete!"
+}
+
+main "$@"
+```
+
+## Architecture Benefits
+
+### ✅ Modularity
+
+Each library has ONE responsibility - easy to understand and modify.
+
+### ✅ Testability
+
+Small, focused functions can be unit tested independently.
+
+### ✅ Reusability
+
+Libraries can be used in different scripts or GitHub Actions.
+
+### ✅ Maintainability
+
+Changes isolated to specific files - less ripple effect.
+
+### ✅ Clarity
+
+Functions have clear names and single purposes.
+
+## Migrating Old Scripts
+
+Old monolithic scripts (`gem-publish.sh`, `release.sh`, `build.sh`) can now be:
+
+1. **Deprecated** with warnings pointing to new libraries
+2. **Replaced** with thin wrappers using libraries
+3. **Removed** once adoption is confirmed
+
+Example deprecation wrapper:
+
+```bash
+#!/bin/bash
+echo "⚠️  WARNING: This script is deprecated"
+echo "    Use: ./scripts/release"
+exec "$(dirname "$0")/release" "$@"
+```
+
+## Contributing
+
+When adding new functionality:
+
+1. **Choose the right library** - or create a new one if needed
+2. **Write tests first** - add tests to `test/test_*.sh`
+3. **Keep functions small** - one function, one purpose
+4. **Document thoroughly** - update this README
+5. **Test in isolation** - each library should work standalone
+
+## Questions?
+
+- See `docs/RELEASE_WORKFLOW_IMPROVEMENTS.md` for the full refactoring plan
+- Check existing library code for patterns and examples
+- Run tests to ensure everything still works
+
+---
+
+**Phase 1 Complete** ✅  
+All libraries extracted with comprehensive test coverage.

data/scripts/lib/changelog.sh

@@ -0,0 +1,313 @@
+#!/bin/bash
+
+# Changelog generation library for zer0-mistakes release scripts
+# Provides automatic changelog generation from git commit history
+
+# Check Bash version (need 4+ for associative arrays)
+if [[ "${BASH_VERSINFO[0]}" -lt 4 ]]; then
+    echo "[ERROR] This script requires Bash 4.0 or higher (current: ${BASH_VERSION})" >&2
+    echo "[INFO] On macOS, install via: brew install bash" >&2
+    echo "[INFO] Then update scripts to use: #!/usr/local/bin/bash" >&2
+    exit 1
+fi
+
+# Source common utilities
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+source "$SCRIPT_DIR/git.sh"
+
+# Constants (check if already defined)
+if [[ -z "${CHANGELOG_FILE:-}" ]]; then
+    readonly CHANGELOG_FILE="CHANGELOG.md"
+fi
+
+# Categorize a single commit based on conventional commit format
+categorize_commit() {
+    local commit_hash="$1"
+    local subject
+    
+    subject=$(get_commit_subject "$commit_hash")
+    local subject_lower=$(echo "$subject" | tr '[:upper:]' '[:lower:]')
+    
+    debug "Categorizing: $subject"
+    
+    # Check commit message and body for breaking changes
+    local commit_full
+    commit_full=$(get_commit_message "$commit_hash")
+    
+    if echo "$commit_full" | grep -qi "BREAKING CHANGE\|breaking:"; then
+        echo "breaking"
+        return 0
+    fi
+    
+    # Conventional commit patterns
+    case "$subject_lower" in
+        feat:*|feature:*|add:*|new:*)
+            echo "added"
+            ;;
+        fix:*|bugfix:*|bug:*|patch:*)
+            echo "fixed"
+            ;;
+        perf:*|performance:*)
+            echo "changed"
+            ;;
+        refactor:*)
+            echo "changed"
+            ;;
+        style:*)
+            echo "changed"
+            ;;
+        docs:*|doc:*)
+            echo "changed"
+            ;;
+        test:*)
+            echo "changed"
+            ;;
+        chore:*)
+            echo "changed"
+            ;;
+        ci:*)
+            echo "changed"
+            ;;
+        build:*)
+            echo "changed"
+            ;;
+        revert:*|remove:*|delete:*)
+            echo "removed"
+            ;;
+        deprecate:*|deprecated:*)
+            echo "deprecated"
+            ;;
+        security:*|sec:*)
+            echo "security"
+            ;;
+        *)
+            echo "other"
+            ;;
+    esac
+}
+
+# Clean commit message for changelog
+clean_commit_message() {
+    local subject="$1"
+    
+    # Remove conventional commit prefix
+    subject=$(echo "$subject" | sed -E 's/^(feat|feature|fix|bugfix|bug|patch|perf|performance|refactor|style|docs|doc|test|chore|ci|build|revert|remove|delete|deprecate|deprecated|security|sec)(\([^)]*\))?:\s*//')
+    
+    # Capitalize first letter
+    subject="$(echo "${subject:0:1}" | tr '[:lower:]' '[:upper:]')${subject:1}"
+    
+    echo "$subject"
+}
+
+# Generate changelog entry for a version
+generate_changelog() {
+    local new_version="$1"
+    local from_ref="${2:-$(get_last_version_tag)}"
+    local to_ref="${3:-HEAD}"
+    
+    step "Generating changelog for version $new_version..."
+    
+    debug "Commit range: $from_ref..$to_ref"
+    
+    # Get commits
+    local commits_raw
+    commits_raw=$(get_commits_between "$from_ref" "$to_ref")
+    
+    if [[ -z "$commits_raw" ]]; then
+        warn "No commits found since $from_ref"
+        return 0
+    fi
+    
+    # Parse and categorize commits
+    declare -A categories
+    categories=(
+        ["breaking"]=""
+        ["added"]=""
+        ["changed"]=""
+        ["deprecated"]=""
+        ["removed"]=""
+        ["fixed"]=""
+        ["security"]=""
+        ["other"]=""
+    )
+    
+    local commit_count=0
+    while IFS='|' read -r hash subject author date; do
+        [[ -z "$hash" ]] && continue
+        
+        ((commit_count++))
+        
+        # Skip merge commits
+        if echo "$subject" | grep -qE "^Merge (branch|pull request|remote-tracking branch)"; then
+            debug "Skipping merge commit: $hash"
+            continue
+        fi
+        
+        # Skip automated version/changelog commits
+        if echo "$subject" | grep -qE "^(chore: (bump version|release version|update changelog)|Automated|Auto-update)"; then
+            debug "Skipping automated commit: $hash"
+            continue
+        fi
+        
+        # Check if commit only modified version/changelog files
+        local files
+        files=$(get_commit_files "$hash")
+        local has_significant_files=false
+        
+        while IFS= read -r file; do
+            [[ -z "$file" ]] && continue
+            
+            if ! echo "$file" | grep -qE "^(CHANGELOG\.md|lib/.*version\.rb|package\.json|\.github/workflows/)$"; then
+                has_significant_files=true
+                break
+            fi
+        done <<< "$files"
+        
+        if [[ "$has_significant_files" == "false" ]]; then
+            debug "Skipping commit with only version/changelog files: $hash"
+            continue
+        fi
+        
+        # Categorize and store
+        local category
+        category=$(categorize_commit "$hash")
+        
+        local clean_msg
+        clean_msg=$(clean_commit_message "$subject")
+        
+        if [[ -n "${categories[$category]}" ]]; then
+            categories[$category]+=$'\n'
+        fi
+        categories[$category]+="- $clean_msg"
+        
+    done <<< "$commits_raw"
+    
+    info "Analyzed $commit_count commits"
+    
+    # Build changelog entry
+    local changelog_entry=""
+    local date
+    date=$(date +"%Y-%m-%d")
+    
+    changelog_entry+="## [$new_version] - $date"$'\n\n'
+    
+    # Add sections in order
+    for category in "breaking" "added" "changed" "deprecated" "removed" "fixed" "security" "other"; do
+        if [[ -n "${categories[$category]}" ]]; then
+            case "$category" in
+                "breaking")
+                    changelog_entry+="### ⚠️  BREAKING CHANGES"$'\n'
+                    ;;
+                "added")
+                    changelog_entry+="### Added"$'\n'
+                    ;;
+                "changed")
+                    changelog_entry+="### Changed"$'\n'
+                    ;;
+                "deprecated")
+                    changelog_entry+="### Deprecated"$'\n'
+                    ;;
+                "removed")
+                    changelog_entry+="### Removed"$'\n'
+                    ;;
+                "fixed")
+                    changelog_entry+="### Fixed"$'\n'
+                    ;;
+                "security")
+                    changelog_entry+="### Security"$'\n'
+                    ;;
+                "other")
+                    changelog_entry+="### Other"$'\n'
+                    ;;
+            esac
+            
+            changelog_entry+="${categories[$category]}"$'\n\n'
+        fi
+    done
+    
+    # Preview changelog
+    info "Changelog preview:"
+    echo -e "${PURPLE}${changelog_entry}${NC}" | head -30
+    
+    # Update CHANGELOG.md
+    if [[ "$DRY_RUN" == "true" ]]; then
+        info "[DRY RUN] Would update $CHANGELOG_FILE"
+        return 0
+    fi
+    
+    if [[ "$INTERACTIVE" == "true" ]]; then
+        if ! confirm "Add this changelog entry to $CHANGELOG_FILE?"; then
+            error "Changelog generation cancelled by user"
+        fi
+    fi
+    
+    update_changelog_file "$changelog_entry"
+    
+    success "Changelog generated for version $new_version"
+}
+
+# Update the CHANGELOG.md file with new entry
+update_changelog_file() {
+    local entry="$1"
+    
+    debug "Updating $CHANGELOG_FILE..."
+    
+    if [[ ! -f "$CHANGELOG_FILE" ]]; then
+        warn "$CHANGELOG_FILE not found, creating new one"
+        echo "# Changelog" > "$CHANGELOG_FILE"
+        echo "" >> "$CHANGELOG_FILE"
+        echo "All notable changes to this project will be documented in this file." >> "$CHANGELOG_FILE"
+        echo "" >> "$CHANGELOG_FILE"
+        echo "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)," >> "$CHANGELOG_FILE"
+        echo "and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)." >> "$CHANGELOG_FILE"
+        echo "" >> "$CHANGELOG_FILE"
+    fi
+    
+    # Create backup
+    cp "$CHANGELOG_FILE" "${CHANGELOG_FILE}.bak"
+    
+    # Insert new entry after header (preserve first line)
+    {
+        head -n 1 "$CHANGELOG_FILE"
+        echo ""
+        echo "$entry"
+        tail -n +2 "$CHANGELOG_FILE"
+    } > "${CHANGELOG_FILE}.tmp"
+    
+    mv "${CHANGELOG_FILE}.tmp" "$CHANGELOG_FILE"
+    rm -f "${CHANGELOG_FILE}.bak"
+    
+    debug "✓ Updated $CHANGELOG_FILE"
+}
+
+# Extract release notes for a specific version from CHANGELOG.md
+extract_release_notes() {
+    local version="$1"
+    
+    debug "Extracting release notes for version $version..."
+    
+    if [[ ! -f "$CHANGELOG_FILE" ]]; then
+        warn "No CHANGELOG.md found"
+        return 1
+    fi
+    
+    # Extract section between version header and next version header
+    awk -v version="$version" '
+        /^## \[/ {
+            if (found) exit
+            if ($0 ~ "\\[" version "\\]") {
+                found=1
+                next
+            }
+        }
+        found && !/^## \[/ { print }
+    ' "$CHANGELOG_FILE"
+}
+
+# Export functions
+export -f categorize_commit
+export -f clean_commit_message
+export -f generate_changelog
+export -f update_changelog_file
+export -f extract_release_notes