jekyll-theme-zer0 0.10.6 → 0.15.2

data/scripts/README.md

@@ -2,164 +2,187 @@
 
 This directory contains automation scripts for managing the `jekyll-theme-zer0` gem lifecycle and feature modules.
 
-## Scripts Overview
+## Directory Structure
+
+```
+scripts/
+├── bin/                    # Entry point commands (use these!)
+│   ├── build              # Build gem without releasing
+│   ├── release            # Full release workflow
+│   └── test               # Run all test suites
+├── lib/                   # Shared libraries (sourced, not executed)
+│   ├── common.sh          # Logging, utilities, dry-run support
+│   ├── version.sh         # Version management functions
+│   ├── validation.sh      # Environment validation
+│   ├── git.sh             # Git operations
+│   ├── changelog.sh       # Changelog generation
+│   ├── gem.sh             # Gem build/publish
+│   └── preview_generator.py  # Python preview image generator
+├── features/              # Feature-specific scripts
+│   ├── generate-preview-images     # AI preview image generator
+│   ├── install-preview-generator   # Preview generator installer
+│   └── validate_preview_urls.py    # Preview URL validator
+├── utils/                 # Utility scripts
+│   ├── analyze-commits    # Commit analyzer for version bumps
+│   ├── fix-markdown       # Markdown formatting fixer
+│   └── setup              # Development environment setup
+├── test/                  # Test suites
+│   ├── lib/               # Library unit tests
+│   ├── theme/             # Theme validation tests
+│   └── integration/       # Integration tests
+└── *.sh (wrappers)        # Backward-compatible wrappers
+```
 
-### 🖼️ `generate-preview-images.sh` (Feature: ZER0-003)
-AI-powered preview image generator for Jekyll posts and content.
+## Quick Start
 
-**Usage:**
 ```bash
-./scripts/generate-preview-images.sh [options]
+# Build gem
+./scripts/bin/build
+
+# Full release workflow
+./scripts/bin/release patch   # or minor/major
+
+# Run tests
+./scripts/bin/test
 ```
 
-**Examples:**
+## Scripts Overview
+
+### Main Commands (scripts/bin/)
+
+#### `bin/build`
+Build the gem without the full release workflow.
+
 ```bash
-./scripts/generate-preview-images.sh --list-missing    # List files missing previews
-./scripts/generate-preview-images.sh --dry-run         # Preview without changes
-./scripts/generate-preview-images.sh --collection posts # Generate for posts only
-./scripts/generate-preview-images.sh -f path/to/file.md # Process specific file
-./scripts/generate-preview-images.sh --provider openai  # Use OpenAI DALL-E
+./scripts/bin/build [--dry-run] [--verbose]
 ```
 
-**Configuration:**
-Settings in `_config.yml` under `preview_images` section:
-```yaml
-preview_images:
-  enabled: true
-  provider: openai
-  model: dall-e-3
-  size: "1792x1024"
-  style: "retro pixel art, 8-bit video game aesthetic"
-  output_dir: assets/images/previews
-```
+#### `bin/release`
+Full release workflow with changelog, version bump, and publishing.
 
-**See:** [Preview Image Generator Documentation](/docs/features/preview-image-generator.md)
+```bash
+./scripts/bin/release [patch|minor|major] [options]
+
+Options:
+  --dry-run           Preview without making changes
+  --skip-tests        Skip test execution
+  --skip-publish      Skip RubyGems publishing
+  --no-github-release Skip GitHub release creation
+  --non-interactive   No confirmation prompts
+```
 
-### 📦 `install-preview-generator.sh`
-Installer for the AI Preview Image Generator feature.
+#### `bin/test`
+Unified test runner for all test suites.
 
-**Usage:**
 ```bash
-# Remote installation (for other Jekyll sites)
-curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/scripts/install-preview-generator.sh | bash
-
-# Local installation with options
-./scripts/install-preview-generator.sh [options]
+./scripts/bin/test [all|lib|theme|integration] [--verbose]
 ```
 
-**Options:**
-- `-d, --dry-run` - Preview what would be installed
-- `-f, --force` - Overwrite existing files
-- `-p, --provider PROVIDER` - Set default AI provider
-- `--no-config` - Skip _config.yml modification
-- `--no-tasks` - Skip VS Code tasks installation
+### Feature Scripts (scripts/features/)
 
-### 🚀 `setup.sh`
-Sets up the development environment for gem development.
+#### `generate-preview-images`
+AI-powered preview image generator for Jekyll posts.
 
-**Usage:**
 ```bash
-./scripts/setup.sh
+./scripts/features/generate-preview-images [options]
+
+Options:
+  --list-missing      List files missing previews
+  --dry-run           Preview without changes
+  --collection TYPE   Generate for specific collection (posts, docs, etc.)
+  -f, --file PATH     Process specific file
+  --provider PROVIDER Use specific AI provider (openai)
 ```
 
-**What it does:**
-- Checks system requirements (Ruby, Bundler, jq, Git)
-- Installs dependencies
-- Makes scripts executable
-- Validates gemspec
-- Creates CHANGELOG.md if missing
-- Sets up Git hooks for validation
-- Updates .gitignore for gem development
-
-### 📈 `version.sh`
-Manages semantic versioning of the gem.
+#### `install-preview-generator`
+Install the preview image generator feature.
 
-**Usage:**
 ```bash
-./scripts/version.sh [patch|minor|major] [--dry-run]
+./scripts/features/install-preview-generator [options]
 ```
 
-**Examples:**
+#### `validate_preview_urls.py`
+Validate preview image URLs in frontmatter.
+
 ```bash
-./scripts/version.sh patch           # 0.1.8 → 0.1.9
-./scripts/version.sh minor           # 0.1.8 → 0.2.0
-./scripts/version.sh major           # 0.1.8 → 1.0.0
-./scripts/version.sh patch --dry-run # Preview changes without applying
+python3 scripts/features/validate_preview_urls.py [--verbose] [--suggestions]
 ```
 
-**What it does:**
-- Validates working directory is clean
-- Updates version in `package.json`
-- Updates `CHANGELOG.md` if it exists
-- Creates git commit with version bump
-- Creates git tag (`v{version}`)
+### Utility Scripts (scripts/utils/)
 
-### 🔨 `build.sh`
-Builds and optionally publishes the gem.
+#### `setup`
+Set up the development environment.
 
-**Usage:**
 ```bash
-./scripts/build.sh [--publish] [--dry-run]
+./scripts/utils/setup
 ```
 
-**Examples:**
+#### `analyze-commits`
+Analyze commits to determine version bump type.
+
 ```bash
-./scripts/build.sh                    # Build gem only
-./scripts/build.sh --publish          # Build and publish to RubyGems
-./scripts/build.sh --publish --dry-run # Preview publish process
+./scripts/utils/analyze-commits [range]
 ```
 
-**What it does:**
-- Validates dependencies and gemspec
-- Builds the gem file
-- Shows gem contents for verification
-- Optionally publishes to RubyGems (with confirmation)
+#### `fix-markdown`
+Fix markdown formatting issues.
+
+```bash
+./scripts/utils/fix-markdown [files...]
+```
+
+### Libraries (scripts/lib/)
+
+These are sourced by other scripts, not executed directly:
 
-### 🧪 `test.sh`
-Runs comprehensive tests and validations.
+- `common.sh` - Logging utilities, colors, dry-run support
+- `version.sh` - Version parsing, calculation, file updates
+- `validation.sh` - Environment and dependency validation
+- `git.sh` - Git operations (tags, commits, branches)
+- `changelog.sh` - Changelog generation from commits
+- `gem.sh` - Gem build/publish operations
+- `preview_generator.py` - Python preview image generator
+
+### Test Suites (scripts/test/)
 
-**Usage:**
 ```bash
-./scripts/test.sh [--verbose]
+# Run all library unit tests
+./scripts/test/lib/run_tests.sh
+
+# Run theme validation
+./scripts/test/theme/validate
+
+# Run integration tests
+./scripts/test/integration/auto-version
+./scripts/test/integration/mermaid
 ```
 
-**What it tests:**
-- `package.json` syntax and version format
-- Gemspec syntax and validity
-- Required files existence
-- YAML front matter in layouts
-- Jekyll dependencies
-- Version consistency
-- Script permissions
-- Bundle install capability
+## Backward Compatibility
+
+Legacy script paths (e.g., `./scripts/build.sh`) are maintained as thin wrappers
+that forward to the canonical locations in `bin/`, `utils/`, `features/`, or `test/`.
 
 ## Development Workflow
 
 ### Initial Setup
 ```bash
-# Clone the repository
 git clone https://github.com/bamr87/zer0-mistakes.git
 cd zer0-mistakes
-
-# Set up development environment
-./scripts/setup.sh
+./scripts/utils/setup
 ```
 
 ### Making Changes
 ```bash
-# Make your changes to the theme files
-
-# Run tests to validate changes
-./scripts/test.sh
+# Make your changes
 
-# If tests pass, bump version
-./scripts/version.sh patch
+# Run tests
+./scripts/bin/test
 
-# Build the gem
-./scripts/build.sh
+# Build (without publish)
+./scripts/bin/build
 
-# Publish to RubyGems (when ready)
-./scripts/build.sh --publish
+# Full release
+./scripts/bin/release patch
 ```
 
 ### Automated Workflows
@@ -186,11 +209,14 @@ The project includes GitHub Actions workflows for automation:
 ## Requirements
 
 ### System Dependencies
+- **Bash**: >= 3.2 (macOS default supported - no Homebrew Bash required!)
 - **Ruby**: >= 2.7.0
 - **Bundler**: For dependency management
 - **jq**: For JSON processing
 - **Git**: For version control
 
+**Note on Bash Compatibility**: All scripts are compatible with Bash 3.2+ (the default version on macOS). You do NOT need to install Homebrew Bash. The release automation, changelog generation, and all CI/CD workflows work seamlessly with the system-provided Bash on macOS and standard Bash installations on Linux.
+
 ### RubyGems Publishing Setup
 To publish gems, you need:
 

data/scripts/analyze-commits.sh

@@ -1,313 +1,11 @@
 #!/bin/bash
 
-# Commit Analysis Script for Automated Version Bumping
-# Analyzes git commits to determine appropriate semantic version bump
-# Usage: ./scripts/analyze-commits.sh [commit-range]
-# Output: patch|minor|major|none
-
-set -euo pipefail
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-CYAN='\033[0;36m'
-NC='\033[0m' # No Color
-
-# Default values
-COMMIT_RANGE="${1:-HEAD~1..HEAD}"
-DEBUG=${DEBUG:-false}
-
-# Logging functions
-log_debug() {
-    if [[ "$DEBUG" == "true" ]]; then
-        echo -e "${CYAN}[DEBUG]${NC} $1" >&2
-    fi
-}
-
-log_info() {
-    echo -e "${BLUE}[INFO]${NC} $1" >&2
-}
-
-log_warning() {
-    echo -e "${YELLOW}[WARNING]${NC} $1" >&2
-}
-
-log_error() {
-    echo -e "${RED}[ERROR]${NC} $1" >&2
-}
-
-# Function to analyze individual commit
-analyze_commit() {
-    local commit_hash="$1"
-    local commit_message
-    local commit_files
-    local bump_level="none"
-    
-    commit_message=$(git log --format="%s%n%b" -n 1 "$commit_hash")
-    commit_files=$(git diff-tree --no-commit-id --name-only -r "$commit_hash" 2>/dev/null || echo "")
-    
-    log_debug "Analyzing commit: $commit_hash"
-    log_debug "Message: $(echo "$commit_message" | head -1)"
-    
-    # Check for breaking changes (MAJOR)
-    if echo "$commit_message" | grep -qi "BREAKING CHANGE\|breaking:"; then
-        echo "major"
-        return 0
-    fi
-    
-    # Check for major version indicators in commit message
-    if echo "$commit_message" | grep -qE "^(major|MAJOR|breaking|BREAKING)[\s:]"; then
-        echo "major"
-        return 0
-    fi
-    
-    # Check commit message patterns for conventional commits
-    local subject_line=$(echo "$commit_message" | head -1)
-    
-    # MAJOR changes
-    if echo "$subject_line" | grep -qE "^(revert|remove|delete)[\s:].*[Bb]reaking"; then
-        echo "major"
-        return 0
-    fi
-    
-    # MINOR changes (new features)
-    if echo "$subject_line" | grep -qE "^(feat|feature|add|new)[\s:]"; then
-        echo "minor"
-        return 0
-    fi
-    
-    # MINOR changes - significant additions
-    if echo "$subject_line" | grep -qE "^(enhance|improve|update)[\s:].*[Ff]eature"; then
-        echo "minor"
-        return 0
-    fi
-    
-    # PATCH changes (bug fixes, small improvements)
-    if echo "$subject_line" | grep -qE "^(fix|bug|patch|hotfix|chore|docs|style|refactor|test|perf)[\s:]"; then
-        echo "patch"
-        return 0
-    fi
-    
-    # PATCH changes - maintenance and small improvements
-    if echo "$subject_line" | grep -qE "^(update|improve|enhance|optimize|clean)[\s:]"; then
-        echo "patch"
-        return 0
-    fi
-    
-    # File-based analysis for changes without conventional commit messages
-    if [[ -n "$commit_files" ]]; then
-        local critical_files=0
-        local feature_files=0
-        local patch_files=0
-        
-        while IFS= read -r file; do
-            [[ -z "$file" ]] && continue
-            
-            log_debug "Analyzing file: $file"
-            
-            # Critical/breaking change files (MAJOR)
-            if echo "$file" | grep -qE "(Gemfile|gemspec|_config\.yml|docker-compose\.yml|Dockerfile)$"; then
-                ((critical_files++))
-                log_debug "Critical file detected: $file"
-            
-            # Feature files (MINOR)  
-            elif echo "$file" | grep -qE "(_layouts/|_includes/|assets/|pages/.*\.md$|\.rb$|\.js$)"; then
-                ((feature_files++))
-                log_debug "Feature file detected: $file"
-            
-            # Documentation and minor files (PATCH)
-            elif echo "$file" | grep -qE "(README|CHANGELOG|\.md$|\.txt$|\.yml$|\.yaml$|test/)"; then
-                ((patch_files++))
-                log_debug "Patch file detected: $file"
-            fi
-        done <<< "$commit_files"
-        
-        # Determine bump level based on file analysis
-        if [[ $critical_files -gt 0 ]]; then
-            # But only if there are significant changes to critical files
-            local lines_changed=$(git diff --shortstat "$commit_hash^" "$commit_hash" 2>/dev/null | grep -oE '[0-9]+ insertion|[0-9]+ deletion' | grep -oE '[0-9]+' | paste -sd+ | bc 2>/dev/null || echo "0")
-            if [[ $lines_changed -gt 10 ]]; then
-                echo "minor"  # Significant changes to critical files = minor
-                return 0
-            else
-                echo "patch"  # Small changes to critical files = patch
-                return 0
-            fi
-        elif [[ $feature_files -gt 0 ]]; then
-            echo "patch"  # Changes to feature files without explicit feat: = patch
-            return 0
-        elif [[ $patch_files -gt 0 ]]; then
-            echo "patch"
-            return 0
-        fi
-    fi
-    
-    # If we reach here, no clear classification - default to patch for any real changes
-    if [[ -n "$commit_files" ]]; then
-        echo "patch"
-    else
-        echo "none"
-    fi
-}
-
-# Function to determine highest bump level from multiple commits
-determine_overall_bump() {
-    local commits=("$@")
-    local highest_bump="none"
-    local patch_count=0
-    local minor_count=0
-    local major_count=0
-    
-    log_info "Analyzing ${#commits[@]} commits for version bump determination"
-    
-    for commit in "${commits[@]}"; do
-        local bump_level
-        bump_level=$(analyze_commit "$commit")
-        
-        log_debug "Commit $commit: $bump_level"
-        
-        case "$bump_level" in
-            "major")
-                ((major_count++))
-                highest_bump="major"
-                ;;
-            "minor")
-                ((minor_count++))
-                if [[ "$highest_bump" != "major" ]]; then
-                    highest_bump="minor"
-                fi
-                ;;
-            "patch")
-                ((patch_count++))
-                if [[ "$highest_bump" == "none" ]]; then
-                    highest_bump="patch"
-                fi
-                ;;
-        esac
-    done
-    
-    log_info "Bump analysis summary:"
-    log_info "  - Major changes: $major_count"
-    log_info "  - Minor changes: $minor_count"  
-    log_info "  - Patch changes: $patch_count"
-    log_info "  - Overall recommendation: $highest_bump"
-    
-    echo "$highest_bump"
-}
-
-# Main execution
-main() {
-    local commit_range="$COMMIT_RANGE"
-    
-    log_info "Analyzing commits in range: $commit_range"
-    
-    # Validate git repository
-    if ! git rev-parse --git-dir > /dev/null 2>&1; then
-        log_error "Not in a git repository"
-        exit 1
-    fi
-    
-    # Get list of commits in range
-    local commits
-    if ! commits=($(git rev-list --reverse "$commit_range" 2>/dev/null)); then
-        log_warning "No commits found in range: $commit_range"
-        echo "none"
-        exit 0
-    fi
-    
-    if [[ ${#commits[@]} -eq 0 ]]; then
-        log_warning "No commits to analyze"
-        echo "none"
-        exit 0
-    fi
-    
-    # Filter out merge commits and automated commits
-    local filtered_commits=()
-    for commit in "${commits[@]}"; do
-        local commit_subject
-        commit_subject=$(git log --format="%s" -n 1 "$commit")
-        
-        # Skip merge commits
-        if echo "$commit_subject" | grep -qE "^Merge (branch|pull request|remote-tracking branch)"; then
-            log_debug "Skipping merge commit: $commit"
-            continue
-        fi
-        
-        # Skip automated commits (version bumps, changelog updates)
-        if echo "$commit_subject" | grep -qE "^(chore: bump version|chore: update changelog|Automated|Auto-update)"; then
-            log_debug "Skipping automated commit: $commit"
-            continue
-        fi
-        
-        # Skip commits that only modify ignored files
-        local commit_files
-        commit_files=$(git diff-tree --no-commit-id --name-only -r "$commit" 2>/dev/null || echo "")
-        
-        local has_significant_files=false
-        while IFS= read -r file; do
-            [[ -z "$file" ]] && continue
-            
-            # Skip if only changelog, version files, or workflow files changed
-            if ! echo "$file" | grep -qE "^(CHANGELOG\.md|lib/.*version\.rb|package\.json|\.github/workflows/)$"; then
-                has_significant_files=true
-                break
-            fi
-        done <<< "$commit_files"
-        
-        if [[ "$has_significant_files" == "true" ]]; then
-            filtered_commits+=("$commit")
-        else
-            log_debug "Skipping commit with only version/changelog files: $commit"
-        fi
-    done
-    
-    if [[ ${#filtered_commits[@]} -eq 0 ]]; then
-        log_info "No significant commits found after filtering"
-        echo "none"
-        exit 0
-    fi
-    
-    log_info "Analyzing ${#filtered_commits[@]} significant commits (filtered from ${#commits[@]} total)"
-    
-    # Determine the appropriate version bump
-    determine_overall_bump "${filtered_commits[@]}"
-}
-
-# Show usage if requested
-if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
-    cat << EOF
-Commit Analysis Script for Automated Version Bumping
-
-USAGE:
-    $0 [commit-range]
-
-ARGUMENTS:
-    commit-range    Git commit range to analyze (default: HEAD~1..HEAD)
-
-OUTPUT:
-    patch           Bug fixes, documentation, small improvements
-    minor           New features, enhancements
-    major           Breaking changes, major refactors
-    none            No version bump needed
-
-EXAMPLES:
-    $0                          # Analyze last commit
-    $0 HEAD~5..HEAD            # Analyze last 5 commits  
-    $0 v1.0.0..HEAD            # Analyze since last tag
-
-ENVIRONMENT:
-    DEBUG=true                  # Enable debug output
-
-CONVENTIONAL COMMIT PATTERNS:
-    feat:, feature:, add:       → minor
-    fix:, bug:, patch:          → patch
-    BREAKING CHANGE, breaking:  → major
-    chore:, docs:, style:       → patch
-EOF
-    exit 0
-fi
-
-# Execute main function
-main "$@"
+# ============================================================================
+# WRAPPER: This script forwards to scripts/utils/analyze-commits
+# 
+# The canonical location is scripts/utils/analyze-commits. This wrapper exists
+# for backward compatibility with existing workflows.
+# ============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/utils/analyze-commits" "$@"

data/scripts/bin/build

@@ -17,27 +17,6 @@ source "$LIB_DIR/validation.sh"
 source "$LIB_DIR/version.sh"
 source "$LIB_DIR/gem.sh"
 
-# Parse arguments
-while [[ $# -gt 0 ]]; do
-    case $1 in
-        --dry-run)
-            export DRY_RUN=true
-            shift
-            ;;
-        --verbose)
-            export VERBOSE=true
-            shift
-            ;;
-        --help|-h)
-            show_usage
-            exit 0
-            ;;
-        *)
-            error "Unknown option: $1 (use --help for usage)"
-            ;;
-    esac
-done
-
 # Show usage
 show_usage() {
     cat << EOF
@@ -58,7 +37,7 @@ OPTIONS:
 EXAMPLES:
     ./scripts/bin/build                # Build gem with current version
     ./scripts/bin/build --dry-run      # Preview what would be built
-    ./scripts/build --verbose      # Build with debug output
+    ./scripts/bin/build --verbose      # Build with debug output
 
 ENVIRONMENT VARIABLES:
     DRY_RUN=true     Enable dry run mode
@@ -71,6 +50,27 @@ For full release workflow, use: ./scripts/release
 EOF
 }
 
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --dry-run)
+            export DRY_RUN=true
+            shift
+            ;;
+        --verbose)
+            export VERBOSE=true
+            shift
+            ;;
+        --help|-h)
+            show_usage
+            exit 0
+            ;;
+        *)
+            error "Unknown option: $1 (use --help for usage)"
+            ;;
+    esac
+done
+
 # Main build workflow
 main() {
     print_header "🔨 Gem Build"