docopslab-dev 0.1.0

data/assets/scripts/build.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Generic release build script for DocOps Lab projects
+# Usage: Set PROJECT_NAME and DOCKER_ORG, then run this script
+
+set -e
+
+# Load common build functions from centrally managed location
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Try to find build-common.sh in various locations
+if [ -f "$SCRIPT_DIR/build-common.sh" ]; then
+    # shellcheck source=build-common.sh
+    source "$SCRIPT_DIR/build-common.sh"
+elif [ -f "$SCRIPT_DIR/lib/build-common.sh" ]; then
+    # shellcheck source=build-common.sh
+    source "$SCRIPT_DIR/lib/build-common.sh"
+elif [ -f "scripts/.vendor/docopslab/build-common.sh" ]; then
+    # shellcheck source=build-common.sh
+    source "scripts/.vendor/docopslab/build-common.sh"
+else
+    echo "❌ Error: build-common.sh not found. Run 'rake labdev:config:sync' to get centrally managed scripts."
+    exit 1
+fi
+
+# Project configuration - override these in your calling script or environment  
+PROJECT_NAME="${PROJECT_NAME:-$(basename "$(pwd)")}"
+DOCKER_ORG="${DOCKER_ORG:-docopslab}"
+
+echo -e "${GREEN}🚀 ${PROJECT_NAME} Release Build Script${NC}"
+echo "=================================="
+
+# Validation
+check_project_root
+check_git_clean  
+check_main_branch
+check_bundle_installed
+check_docker_available
+
+# Run tests
+run_rspec_tests
+test_cli_functionality
+
+# Get current version
+current_version=$(get_current_version)
+echo -e "${GREEN}📋 Current version: $current_version${NC}"
+
+# Build and test gem
+build_gem
+gem_file=$(test_built_gem)
+
+# Build Docker image using the docker-specific script
+echo -e "${YELLOW}🐳 Building Docker image...${NC}"
+"$SCRIPT_DIR/build-docker.sh" 2>&1 | grep -E "(Building|Testing|successfully|Docker image:)" || true
+
+# Show final success message
+show_build_success "$current_version" "$gem_file"

data/assets/scripts/parse_jekyll_asciidoc_logs.rb

@@ -0,0 +1,467 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'yaml'
+require 'time'
+require 'fileutils'
+require 'erb'
+
+# Jekyll-AsciiDoc Log Parser
+#
+# Parses Jekyll verbose build logs to extract Asciidoctor warnings and errors.
+# Associates each issue with the source file being processed.
+#
+# Usage:
+#   bundle exec jekyll build --verbose > .agent/jekyll-build.log 2>&1
+#   bundle exec rake 'labdev:lint:logs[jekyll-asciidoc,.agent/jekyll-build.log]'
+
+module JekyllAsciiDocLogParser
+  COLORS = {
+    red: 31,
+    yellow: 33,
+    green: 32,
+    blue: 34,
+    cyan: 36
+  }.freeze
+
+  # Represents a single log issue
+  class LogIssue
+    attr_accessor :type, :kind, :file, :path, :with, :from, :line, :note, :code, :fix, :attr
+
+    def initialize type:, kind:, file:, line:, note:, **options
+      @type = type
+      @kind = kind
+      @file = file
+      @line = line
+      @note = note
+      @attr = options[:attr]
+
+      # Handle optional parameters
+      reported_file_path = options[:reported_file_path]
+      is_excerpt = options[:is_excerpt] || false
+      @fix = nil
+
+      process_context(reported_file_path, is_excerpt)
+      process_error_specifics(reported_file_path, file, line)
+    end
+
+    def to_h
+      hash = {
+        'type' => @type,
+        'kind' => @kind,
+        'file' => @file,
+        'line' => @line,
+        'note' => @note,
+        'fix?' => @fix
+      }
+
+      # Add optional fields only if they have values
+      hash['path'] = @path if @path
+      hash['with'] = @with if @with
+      hash['from'] = @from if @from
+      hash['code'] = @code if @code && !@code.empty?
+      hash['attr'] = @attr if @attr
+
+      hash
+    end
+
+    private
+
+    def process_context reported_file_path, is_excerpt
+      @from = '#excerpt' if reported_file_path == '#excerpt' || is_excerpt
+    end
+
+    def process_error_specifics reported_file_path, source_file, line_number
+      if @kind == 'include_file_not_found'
+        extract_missing_path
+      else
+        set_problem_file(reported_file_path, source_file)
+        extract_code_line(line_number)
+      end
+    end
+
+    def extract_missing_path
+      return unless @note =~ /include file not found: (.+)$/
+
+      missing_path = Regexp.last_match(1)
+
+      # Try to convert absolute path back to relative path
+      if missing_path =~ %r{/home/[^/]+/[^/]+/work/[^/]+/(.+)$} ||
+         missing_path =~ %r{/([^/]+/[^/]+\.adoc)$}
+        @path = Regexp.last_match(1)
+      end
+    end
+
+    def set_problem_file reported_file_path, source_file
+      problem_file = JekyllAsciiDocLogParser.normalize_problem_path(reported_file_path, source_file)
+      @with = problem_file unless problem_file == source_file
+    end
+
+    def extract_code_line line_number
+      return unless @with
+
+      code_line = JekyllAsciiDocLogParser.get_code_line_from_problem_file(@with, line_number)
+      @code = code_line if code_line && !code_line.empty?
+    end
+  end
+
+  class << self
+    def parse_log_file log_file, output_dir='.agent/reports'
+      unless File.exist?(log_file)
+        puts "❌ Log file not found: #{log_file}"
+        return false
+      end
+
+      content = File.read(log_file)
+      parse_log_content(content, output_dir, log_file)
+    end
+
+    def parse_log_content content, output_dir='.agent/reports', source_name='stdin'
+      puts '📝 Parsing Jekyll AsciiDoctor log for warnings and errors...'
+
+      FileUtils.mkdir_p(output_dir)
+
+      timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+      output_file = "jekyll-asciidoc-issues-#{timestamp}.yml"
+      output_path = File.join(output_dir, output_file)
+
+      issues = parse_issues(content)
+
+      if issues.empty?
+        puts '✅ No AsciiDoctor issues found!'
+        return true
+      end
+
+      generate_yaml_report(issues, output_path, source_name)
+
+      severity = summarize_severity(issues)
+      icon = severity[:has_error] ? '❌' : '⚠️'
+      total_files = issues.length
+      total_issues = count_total_issues(issues)
+      files_text = colorize(total_files, :cyan)
+      issues_color = severity[:has_error] ? :red : :yellow
+      issues_text = colorize(total_issues, issues_color)
+
+      puts "📄 Jekyll AsciiDoc issues report generated: #{output_path}"
+      puts "#{icon} Found #{issues_text} #{pluralize(total_issues, 'total issue')} across #{files_text} " \
+           "#{pluralize(total_files, 'source file')} to review"
+      true
+    end
+
+    # Public helper methods accessible to LogIssue class
+
+    def normalize_source_path source_file
+      normalized = source_file.gsub(/#excerpt$/, '').gsub(%r{/$}, '')
+      normalized.gsub(%r{^\./}, '')
+    end
+
+    def normalize_problem_path reported_path, source_file
+      case reported_path
+      when '#excerpt'
+        # Special case: excerpt errors are in the source file itself
+        source_file
+      when %r{^/}
+        # Absolute path; try to make relative to project root
+        if reported_path.include?('/home/')
+          # Extract the project-relative portion
+          if reported_path =~ %r{/home/[^/]+/[^/]+/work/([^/]+)/(.+)$}
+            project = Regexp.last_match(1)
+            path = Regexp.last_match(2)
+            "#{project}/#{path}"
+          else # Fallback
+            File.basename(reported_path)
+          end
+        else
+          reported_path
+        end
+      when %r{^\.\./}
+        # Resolve relative path from source file directory
+        source_dir = File.dirname(source_file)
+        resolved = File.expand_path(reported_path, source_dir)
+        # Make it relative to project root
+        resolved.gsub(%r{^/.*?/work/[^/]+/}, '')
+      else
+        # Already relative or simple filename
+        reported_path
+      end
+    end
+
+    def categorize_error_type message
+      case message
+      when /include file not found/
+        'include_file_not_found'
+      when /section title out of sequence/
+        'section_title_out_of_sequence'
+      when /unterminated listing block/
+        'unterminated_listing_block'
+      when /invalid reference/
+        'invalid_reference'
+      when /attribute '([^']+)' (?:is|not) defined/
+        'missing_attribute'
+      else
+        'other'
+      end
+    end
+
+    def get_code_line_from_problem_file problem_file, line_number
+      return '' unless problem_file && line_number.positive?
+
+      # Try various paths where the file might exist
+      possible_paths = [
+        problem_file,
+        "./#{problem_file}",
+        File.expand_path(problem_file)
+      ]
+
+      # Also try in common Jekyll source directories
+      %w[_docs _blog _pages content].each do |dir|
+        unless problem_file.start_with?(dir)
+          possible_paths << "#{dir}/#{problem_file}"
+          possible_paths << "#{dir}/#{File.basename(problem_file)}"
+        end
+      end
+
+      possible_paths.each do |path|
+        next unless File.exist?(path)
+
+        begin
+          lines = File.readlines(path)
+          line_content = lines[line_number - 1]&.chomp
+          return line_content if line_content && !line_content.empty?
+        rescue StandardError => e
+          puts "⚠️  Could not read line #{line_number} from #{path}: #{e.message}"
+        end
+      end
+
+      '' # Return empty string if we can't find/read the file
+    end
+
+    private
+
+    def parse_issues content
+      lines = content.split("\n")
+      issues = []
+      current_source_file = nil
+
+      lines.each do |line|
+        line = line.strip
+
+        # Track what file Jekyll is currently rendering (this is our source file)
+        current_source_file = Regexp.last_match(1) if line =~ /Rendering Markup: (.+\.adoc.*)/
+
+        # Extract asciidoctor warnings and errors with explicit file/line
+        missing_attr = nil
+        if line =~ /^asciidoctor: (WARNING|ERROR): (.+): line (\d+): (.+)$/
+          issue_type = Regexp.last_match(1) == 'ERROR' ? 'ERROR' : 'warning'
+          reported_file_path = Regexp.last_match(2) # Keep exactly as AsciiDoctor reports it
+          line_number = Regexp.last_match(3).to_i
+          message = Regexp.last_match(4)
+        elsif line =~ /^asciidoctor: (WARNING|ERROR): skipping reference to missing attribute: (.+)$/
+          issue_type = Regexp.last_match(1) == 'ERROR' ? 'ERROR' : 'warning'
+          reported_file_path = current_source_file
+          line_number = 0
+          missing_attr = Regexp.last_match(2).strip
+          message = "attribute '#{missing_attr}' not defined"
+        else
+          next
+        end
+
+        next unless current_source_file
+
+        # Normalize the source file path (relative to project root)
+        source_file = normalize_source_path(current_source_file)
+        is_excerpt = current_source_file.include?('#excerpt')
+
+        error_category = categorize_error_type(message)
+        attr_name = nil
+        if error_category == 'missing_attribute'
+          if message =~ /attribute '([^']+)' (?:is|not) defined/
+            attr_name = Regexp.last_match(1)
+          elsif missing_attr
+            attr_name = missing_attr
+          end
+        end
+
+        # Create LogIssue object
+        log_issue = LogIssue.new(
+          type: issue_type,
+          kind: error_category,
+          file: source_file,
+          line: line_number,
+          note: message,
+          attr: attr_name,
+          reported_file_path: reported_file_path,
+          is_excerpt: is_excerpt)
+
+        issues << log_issue.to_h
+      end
+
+      # Group issues by source file for organized output
+      issues.group_by { |issue| issue['file'] }.map do |file, file_issues|
+        {
+          'source_file' => file,
+          'issues' => file_issues
+        }
+      end
+    end
+
+    def count_total_issues file_issues
+      file_issues.sum { |file_data| file_data['issues'].length }
+    end
+
+    def generate_yaml_report file_issues, output_file, source_name
+      template = ERB.new(yaml_template)
+      yaml_content = template.result_with_hash(
+        file_issues: file_issues,
+        source_name: source_name,
+        timestamp: Time.now.strftime('%Y-%m-%d %H:%M:%S'),
+        total_files: file_issues.length,
+        total_issues: count_total_issues(file_issues))
+
+      # Post-process to remove unwanted blank lines
+      cleaned_content = clean_yaml_whitespace(yaml_content)
+      File.write(output_file, cleaned_content)
+    end
+
+    def clean_yaml_whitespace yaml_content
+      lines = yaml_content.lines
+      cleaned_lines = []
+
+      lines.each_with_index do |line, index|
+        if line.strip.empty?
+          # Keep empty line only if the next line starts with # or -
+          next_line = lines[index + 1]
+          cleaned_lines << line if next_line && (next_line.strip.start_with?('#') || next_line.strip.start_with?('-'))
+        else
+          cleaned_lines << line
+        end
+      end
+
+      cleaned_lines.join
+    end
+
+    def ai_prompt agent_prompt=nil
+      return agent_prompt if agent_prompt
+
+      template_path = File.join(TEMPLATES_DIR, 'jekyll-asciidoc-fix.prompt.yml')
+      File.read(template_path) if File.exist?(template_path)
+    end
+
+    def yaml_template
+      <<~TEMPLATE
+        # Jekyll AsciiDoc Issues Report
+        #
+        # Generated: <%= timestamp %>
+        # Source: <%= source_name %>
+        # Files with issues: <%= total_files %>
+        # Total issues: <%= total_issues %>
+        #
+        # User Instructions:
+        # For each issue, enter a fix?: value of:
+        # 'no' or 'skip' to ignore for now
+        # 'fix' to mark for correction
+        # 'fix("corrected text")' to specify exact correction
+        # 'fix(include)' to fix missing include files
+        # 'fix(leveloffset)' fix section level issues at the include
+        # 'fix(sectionlevel)' fix section level issues in the included file
+        # 'ignore' to add to permanent ignore list (not yet implemented)
+        #
+        # Data Structure:
+        # - file: The Jekyll file being rendered (needs fixing)
+        # - path: Missing include file path (for include_file_not_found only)
+        # - with: The file containing the actual issue (when different from file)
+        # - from: Context like "#excerpt" when relevant
+        # - kind: Error type classification
+        ##{' '}
+        # After editing this file, use an AI agent to process the fixes.
+        #
+        ---
+        <% file_issues.each do |file_data| %>
+        # <%= file_data['source_file'] %>
+        <% file_data['issues'].each do |issue| %>
+        - type: <%= issue['type'] %>
+          kind: <%= issue['kind'] %>
+          file: <%= issue['file'] %>
+        <% if issue['path'] %>
+          path: <%= issue['path'] %>
+        <% end %>
+        <% if issue['with'] %>
+          with: <%= issue['with'] %>
+        <% end %>
+        <% if issue['from'] %>
+          from: "<%= issue['from'] %>"
+        <% end %>
+        <% if issue['line'] && issue['line'] > 0 %>
+          line: <%= issue['line'] %>
+        <% end %>
+          note: "<%= issue['note'] %>"
+        <% if issue['attr'] %>
+          attr: <%= issue['attr'] %>
+        <% end %>
+        <% if issue['code'] && !issue['code'].empty? %>
+          code: |
+            <%= issue['code'] %>
+        <% end %>
+          fix?:#{' '}
+        <% end %>
+
+        <% end %>
+        #
+        # AI Agent Instructions:
+        <%= ai_prompt %>
+      TEMPLATE
+    end
+
+    def colorize value, color
+      text = value.to_s
+      return text unless $stdout.tty?
+
+      code = COLORS[color]
+      return text unless code
+
+      "\e[#{code}m#{text}\e[0m"
+    end
+
+    def pluralize count, singular, plural=nil
+      plural ||= "#{singular}s"
+      count == 1 ? singular : plural
+    end
+
+    def summarize_severity file_issues
+      has_error = false
+      has_warning = false
+
+      file_issues.each do |file_data|
+        file_data['issues'].each do |issue|
+          if issue['type'] == 'ERROR'
+            has_error = true
+          else
+            has_warning = true
+          end
+        end
+      end
+
+      { has_error: has_error, has_warning: has_warning }
+    end
+  end
+end
+
+# CLI usage when run directly
+if $PROGRAM_NAME == __FILE__
+  if ARGV.empty?
+    puts 'Usage: parse_jekyll_asciidoc_logs.rb <log_file> [output_dir]'
+    puts '   or: cat log.txt | parse_jekyll_asciidoc_logs.rb'
+    exit 1
+  end
+
+  if ARGV[0] == '-'
+    # Read from stdin
+    content = $stdin.read
+    output_dir = ARGV[1] || '.agent/reports'
+    JekyllAsciiDocLogParser.parse_log_content(content, output_dir, 'stdin')
+  else
+    log_file = ARGV[0]
+    output_dir = ARGV[1] || '.agent/reports'
+    JekyllAsciiDocLogParser.parse_log_file(log_file, output_dir)
+  end
+end

data/assets/templates/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# DocOps Lab development tooling
+# TODO: Once published to RubyGems, replace with: gem 'docopslab-dev'
+gem 'docopslab-dev', path: '../lab/gems/docopslab-dev'

data/assets/templates/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'docopslab/dev'

data/assets/templates/gitignore

@@ -0,0 +1,69 @@
+# Jekyll build output
+_site/
+.jekyll-cache/
+
+# Build paths
+built/
+build/
+
+# Bundler
+.bundle/
+vendor/
+.vendor/
+
+# macOS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# DocOps Lab Dev tooling - vendor configs are synced, not tracked
+.config/.vendor/
+scripts/.vendor/
+
+# Temporary paths
+tmp/
+*.tmp
+*.bak
+*~
+*.tmp
+*.bak
+.warp/
+.agent/
+.agents/
+
+# Logs
+*.log
+
+# Generated config files (merged from base + local)
+.config/vale.ini
+.config/htmlproofer.yml
+
+# Gem content paths
+gems/**/pkg/
+*.gem
+
+# Build artifacts - generated by CI/scripts
+artifacts/
+tmp/
+# DocOps Lab vendor files
+
+# RSpec
+.rspec_status
+specs/tests/results/
+
+# Test coverage
+/coverage/
+
+# Environment variable files
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+
+# Ruby version managers
+.ruby-version
+.ruby-gemset

data/assets/templates/jekyll-asciidoc-fix.prompt.yml

@@ -0,0 +1,17 @@
+# When processing this file, focus on the relationship between
+#  the 'file' and 'with' properties:
+#
+# 1. 'file' = The Jekyll file that includes/references the problem
+# 2. 'with' = The file that contains the actual structural issue
+# 3. 'kind' types and typical fixes:
+#    - include_file_not_found: Create missing files or fix paths
+#    - section_title_out_of_sequence: Adjust heading levels or leveloffset
+#    - unterminated_listing_block: Close code blocks with proper delimiters
+#    - invalid_reference: Fix broken cross-references
+#    - missing_attribute: Define the attribute locally or via included settings
+#
+# Common patterns:
+# - Multiple files referencing the same with file suggest the issue is in the shared file
+# - #excerpt errors usually indicate an include is embedded in the excerpted text
+# - Section title sequence errors often need leveloffset adjustments in include directives
+# - Missing files may need creation or path corrections

data/assets/templates/spellcheck.prompt.yml

@@ -0,0 +1,16 @@
+# When processing user responses in this file:
+# 1. For fix?: 'add' or 'd': Add the term to the filters section in:
+#    gems/docopslab-dev/assets/config-packs/vale/authoring/Spelling.yml
+# 1.a. For fix?: 'do' or 'dolab' or 'docopslab': Add the term to a special '# DocOpsLab Terms' section
+# 1.b. For fix?: nontech("word"): Add the term to a special '# Non-Technical Terms' section
+# 2. For fix?: 'fix': Replace the term in the file with inferred corrected spelling
+# 3. For fix?: 'fix("word")': Replace the term with the word value verbatim
+# 4. For fix?: 'no' or 'n': Ignore this issue for now
+# 5. For fix?: 'pass': Wrap the affected text in {vale_off} and {vale_on} comment attributes
+#               and make sure the attributes are defined in .adoc file header (offer to user):
+#               :vale_off: <!-- vale off -->
+#               :vale_on:  <!-- vale on -->
+# The spelling dictionary is the 'filters:' sequence in the Spelling.yml file
+# When adding to dictionary, maintain alphabetical order within sections
+# DO NOT TAKE INITIATIVE. STick to the instructed changes except where prompted with `fix?: 'fix'`.
+# DO NOT correct neigboring words in text nor add nor alter words in the dictionary other than those named.

data/docopslab-dev.gemspec

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'lib/docopslab/dev/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'docopslab-dev'
+  spec.version = DocOpsLab::Dev::VERSION
+  spec.authors = ['DocOps Lab']
+  spec.email = ['codewriting@protonmail.com']
+
+  spec.summary = 'Internal development tooling for DocOps Lab projects'
+  spec.description = 'Centralized configuration management, linting, and development ' \
+                     'workflows for DocOps Lab repositories'
+  spec.homepage = 'https://github.com/DocOps/lab'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/DocOps/lab/tree/main/gems/docopslab-dev'
+  spec.metadata['changelog_uri'] = 'https://github.com/DocOps/lab/blob/main/gems/docopslab-dev/README.adoc'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.glob('{lib,config-packs,hooks,docs,assets}/**/*') +
+               %w[README.adoc LICENSE docopslab-dev.gemspec] +
+               Dir.glob('specs/data/*')
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Core runtime dependencies
+  spec.add_dependency 'asciidoctor', '~> 2.0'
+  spec.add_dependency 'rake', '~> 13.0'
+  spec.add_dependency 'yaml', '~> 0.2'
+
+  # Code quality and linting
+  spec.add_dependency 'debride',        '~> 1.13'
+  spec.add_dependency 'fasterer',       '~> 0.11'
+  spec.add_dependency 'flog',           '~> 4.8'
+  spec.add_dependency 'reek',           '~> 6.5'
+  spec.add_dependency 'rubocop',        '~> 1.80'
+  spec.add_dependency 'rubocop-rake',   '~> 0.7'
+  spec.add_dependency 'rubocop-rspec',  '~> 3.7'
+  spec.add_dependency 'subtxt',         '~> 0.3'
+
+  # Security analysis
+  spec.add_dependency 'brakeman',       '~> 7.1'
+  spec.add_dependency 'bundler-audit',  '~> 0.9'
+
+  # Testing and coverage
+  spec.add_dependency 'html-proofer',   '~> 5.0'
+  spec.add_dependency 'inch',           '~> 0.8'
+  spec.add_dependency 'simplecov',      '~> 0.22'
+
+  # Development dependencies should be in Gemfile, not gemspec
+end