develoz-rails 0.1.0

data/lib/generators/develoz/doc_specs/templates/bin/generate-docs.tt

@@ -0,0 +1,392 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'fileutils'
+
+# Script to generate markdown documentation from system specs with doc comments
+#
+# Usage:
+#   bin/generate-docs                    # Generate docs for all system specs with doc comments
+#   bin/generate-docs spec/path/to/file  # Generate docs for a specific spec file
+#   bin/generate-docs --check            # Verify committed docs match their specs (no spec run); exit 1 if stale
+
+class DocGenerator
+  DOCS_DIR = 'docs/platform-guide'
+  SCREENSHOTS_DIR = 'docs/screenshots'
+
+  # Fallbacks for specs that omit the directives below. Specs with no
+  # `@category` collect under DEFAULT_CATEGORY; specs with no `@order` sort
+  # after numbered ones. Both defaults push such docs to the end of the TOC.
+  DEFAULT_CATEGORY = 'Other'
+  DEFAULT_ORDER = 999_999
+
+  # Metadata directives a spec places in its doc comments to control where it
+  # appears in the table of contents. They are parsed out of the comment stream
+  # and never rendered into the generated doc body, e.g.
+  #
+  #   # @category Audits & Reports
+  #   # @order 510
+  #
+  #   # = Feature Name
+  #
+  # `@order` is a single global ordering value across all guides. The README
+  # groups guides by `@category` and lists categories in ascending order of the
+  # smallest `@order` they contain, so the entire structure is driven by the
+  # specs themselves — there is no category list to keep in sync here.
+  CATEGORY_DIRECTIVE = /^\s*#\s*@category\s+(.+?)\s*$/
+  ORDER_DIRECTIVE = /^\s*#\s*@order\s+(\d+)\s*$/
+  DIRECTIVE = /^\s*#\s*@(?:category|order)\b/
+
+  def initialize(spec_files = nil)
+    @spec_files = spec_files || find_documented_specs
+  end
+
+  def generate(run_specs: true)
+    if @spec_files.empty?
+      puts 'No system specs with documentation comments found.'
+      return
+    end
+
+    @spec_files.each do |spec_file|
+      puts "\nGenerating documentation for #{spec_file}..."
+      process_spec(spec_file, run_specs:)
+    end
+
+    generate_readme
+
+    puts "\n✓ Documentation generation complete!"
+    puts "  Generated #{@spec_files.size} documentation file(s) in #{DOCS_DIR}/"
+    puts "  Generated README.md with table of contents"
+  end
+
+  # Verify the committed platform-guide docs are in sync with their documented
+  # specs, without running the specs. Re-renders the doc body (headings, prose,
+  # screenshot references) from each spec and compares it against the committed
+  # markdown, ignoring the generation timestamp and the screenshot binaries
+  # themselves. Returns true when everything is up to date.
+  def check
+    stale = find_documented_specs.select { |spec_file| doc_stale?(spec_file) }
+
+    if stale.empty?
+      puts '✓ Platform-guide docs are up to date.'
+      return true
+    end
+
+    warn "✗ Platform-guide docs are out of date for #{stale.size} spec(s):"
+    stale.each { |spec_file| warn "  - #{spec_file} -> #{generate_output_filename(spec_file)}" }
+    warn ''
+    warn 'Regenerate the affected guide(s) and commit the result:'
+    stale.each { |spec_file| warn "  bin/run bin/generate-docs #{spec_file}" }
+    false
+  end
+
+  # Rebuild only the README table of contents from the committed docs and their
+  # spec `@category`/`@order` directives, without running any specs. Used after
+  # changing directives or category ordering.
+  def regenerate_readme
+    generate_readme
+    puts '✓ Regenerated README.md table of contents.'
+  end
+
+  private
+
+  def doc_stale?(spec_file)
+    output_file = generate_output_filename(spec_file)
+    return true unless File.exist?(output_file)
+
+    expected = "#{render_doc_body(extract_doc_comments(spec_file), extract_screenshot_calls(spec_file)).rstrip}\n"
+    committed = strip_timestamp_header(File.read(output_file, encoding: 'UTF-8'))
+    expected != committed
+  end
+
+  def strip_timestamp_header(content)
+    content.sub(/\A<!--\nGenerated: [^\n]*\n-->\n\n/, '')
+  end
+
+  def find_documented_specs
+    Dir.glob('spec/system/**/*_spec.rb').select do |file|
+      File.read(file, encoding: 'UTF-8').match?(/^#\s*=/)
+    end
+  end
+
+  def process_spec(spec_file, run_specs: true)
+    # Extract documentation comments and screenshot calls
+    doc_comments = extract_doc_comments(spec_file)
+    screenshot_calls = extract_screenshot_calls(spec_file)
+
+    if run_specs
+      # Run the spec with screenshots enabled
+      puts "  Running spec with SCREENSHOTS=true..."
+      run_spec_with_screenshots(spec_file)
+    else
+      puts "  Re-rendering from doc comments (using existing screenshots)..."
+    end
+
+    # Generate markdown file
+    output_file = generate_output_filename(spec_file)
+    generate_markdown(output_file, doc_comments, screenshot_calls)
+
+    puts "  ✓ Generated #{output_file}"
+  end
+
+  def extract_doc_comments(spec_file)
+    content = File.read(spec_file, encoding: 'UTF-8')
+    lines = content.split("\n")
+    comments = []
+    current_block = { level: 0, title: '', content: [], line_number: 0 }
+
+    lines.each_with_index do |line, index|
+      if line =~ DIRECTIVE
+        # @category / @order are TOC metadata, not body content — skip them.
+        next
+      elsif line =~ /^(\s*)#\s*(=+)\s*(.+)/
+        # Save previous block if it exists
+        comments << current_block.dup unless current_block[:title].empty?
+
+        # Start new section
+        level = Regexp.last_match(2).length
+        title = Regexp.last_match(3).strip
+        current_block = { level:, title:, content: [], line_number: index + 1 }
+      elsif line =~ /^(\s*)#\s*(.*)/ && !current_block[:title].empty?
+        # Add to current block
+        content_line = Regexp.last_match(2).strip
+        current_block[:content] << content_line
+      elsif !current_block[:title].empty? && line !~ /^(\s*)#/
+        # End of comment block
+        comments << current_block.dup
+        current_block = { level: 0, title: '', content: [], line_number: 0 }
+      end
+    end
+
+    # Save last block if needed
+    comments << current_block unless current_block[:title].empty?
+
+    comments
+  end
+
+  def extract_screenshot_calls(spec_file)
+    content = File.read(spec_file, encoding: 'UTF-8')
+    lines = content.split("\n")
+    screenshots = []
+
+    lines.each_with_index do |line, index|
+      if line =~ /doc_screenshot\(['"]([\w\-\/]+)['"]\)/
+        screenshots << { path: Regexp.last_match(1), line_number: index + 1 }
+      end
+    end
+
+    screenshots
+  end
+
+  def run_spec_with_screenshots(spec_file)
+    # Ensure screenshots directory exists
+    FileUtils.mkdir_p(SCREENSHOTS_DIR)
+
+    # Run the spec
+    command = "SCREENSHOTS=true bundle exec rspec --format documentation #{spec_file}"
+    system(command, err: File::NULL)
+  end
+
+  def generate_output_filename(spec_file)
+    basename = File.basename(spec_file, '_spec.rb')
+    output_name = basename.upcase.gsub('_', '-') + '.md'
+    File.join(DOCS_DIR, output_name)
+  end
+
+  def generate_markdown(output_file, doc_comments, screenshot_calls)
+    FileUtils.mkdir_p(DOCS_DIR)
+    File.write(output_file, "#{timestamp_header}#{render_doc_body(doc_comments, screenshot_calls).rstrip}\n")
+  end
+
+  def timestamp_header
+    "<!--\nGenerated: #{Time.now.utc.strftime('%Y-%m-%d %H:%M:%S UTC')}\n-->\n\n"
+  end
+
+  # Render the markdown body (everything after the timestamp header) from a
+  # spec's doc comments and screenshot calls. Shared by generation and --check
+  # so both produce byte-identical output for the same spec.
+  def render_doc_body(doc_comments, screenshot_calls)
+    body = +''
+
+    doc_comments.each_with_index do |comment, index|
+      heading_tag = "h#{comment[:level]}"
+      heading_id = slugify(comment[:title])
+      body << "<#{heading_tag} id=\"#{heading_id}\">#{comment[:title]}</#{heading_tag}>\n\n"
+
+      comment[:content].each { |line| body << "#{line}\n" }
+      body << "\n"
+
+      next_comment_line = doc_comments[index + 1]&.dig(:line_number) || Float::INFINITY
+      screenshots = find_related_screenshots(comment[:line_number], next_comment_line, screenshot_calls)
+      screenshots.each do |screenshot|
+        rendered = render_screenshot(screenshot[:path])
+        body << rendered if rendered
+      end
+    end
+
+    body
+  end
+
+  def find_related_screenshots(current_line, next_line, screenshot_calls)
+    # Find screenshots that appear after this comment but before the next one
+    screenshot_calls.select do |screenshot|
+      screenshot[:line_number] > current_line && screenshot[:line_number] < next_line
+    end
+  end
+
+  def render_screenshot(screenshot_path)
+    # Only embed screenshots whose generated file exists on disk
+    return unless find_screenshot_file(screenshot_path)
+
+    # Use full path from docs/platform-guide to docs/screenshots
+    "![#{screenshot_path}](/docs/screenshots/#{screenshot_path}.png)\n\n"
+  end
+
+  def find_screenshot_file(screenshot_path)
+    # Screenshots are saved in docs/screenshots during test run
+    screenshot_file = File.join(SCREENSHOTS_DIR, "#{screenshot_path}.png")
+
+    if File.exist?(screenshot_file)
+      screenshot_file
+    end
+  end
+
+  def slugify(text)
+    text.downcase
+        .gsub(/[^a-z0-9\s-]/, '')
+        .gsub(/\s+/, '-')
+        .gsub(/-+/, '-')
+        .gsub(/^-|-$/, '')
+  end
+
+  # Writes the README table of contents grouped by `@category` and ordered by
+  # `@order`. Called at the end of a full/partial generation run and standalone
+  # via `regenerate_readme` (the `--readme-only` mode).
+  def generate_readme
+    readme_path = File.join(DOCS_DIR, 'README.md')
+
+    File.open(readme_path, 'w') do |f|
+      # Add generation timestamp
+      f.puts "<!--"
+      f.puts "Generated: #{Time.now.utc.strftime('%Y-%m-%d %H:%M:%S UTC')}"
+      f.puts "-->"
+      f.puts
+
+      f.puts '<h1 id="platform-guide">Platform Guide</h1>'
+      f.puts
+      f.puts 'This guide is the primary, automatically generated reference for operating the'
+      f.puts 'platform. It is extracted from the admin system specs, so every page reflects the'
+      f.puts 'behaviour that is actually tested in the codebase.'
+      f.puts
+      f.puts 'Guides are grouped by area below and ordered to follow a typical admin workflow —'
+      f.puts 'from onboarding a client through to running audits and imports.'
+
+      # Build the TOC from every documented spec (not just the ones regenerated
+      # in this run) so running for a subset of specs doesn't drop other
+      # entries. Group by `@category` and order by `@order`.
+      groups = toc_groups
+
+      f.puts category_workflow_diagram(groups.map(&:first))
+      f.puts
+      f.puts '<h2 id="table-of-contents">Table of Contents</h2>'
+
+      groups.each do |category, entries|
+        f.puts
+        f.puts %(<h3 id="#{slugify(category)}">#{category}</h3>)
+        f.puts
+        entries.each do |entry|
+          f.puts "- [#{entry[:title]}](#{entry[:file]})"
+        end
+      end
+    end
+  end
+
+  # A Mermaid flowchart of the guide categories in workflow order, rendered by
+  # the in-app docs viewer. Derived from the same ordered categories as the TOC,
+  # so it never drifts from the actual guides.
+  def category_workflow_diagram(categories)
+    return '' if categories.empty?
+
+    nodes = categories.each_with_index.map { |category, index| %(c#{index}["#{category}"]) }
+    <<~DIAGRAM.chomp
+
+      ```mermaid
+      flowchart LR
+          #{nodes.join(' --> ')}
+      ```
+    DIAGRAM
+  end
+
+  # Returns the table of contents as an ordered list of [category, entries]
+  # pairs. Category order is derived entirely from the specs: categories are
+  # listed in ascending order of the smallest `@order` they contain (ties broken
+  # alphabetically), and entries within a category are ordered by `@order` then
+  # title. Only specs whose generated doc actually exists on disk are linked.
+  def toc_groups
+    entries = find_documented_specs.filter_map do |spec_file|
+      file = File.basename(generate_output_filename(spec_file))
+      next unless File.exist?(File.join(DOCS_DIR, file))
+
+      directives = extract_directives(spec_file)
+      {
+        file:,
+        title: spec_doc_title(spec_file),
+        category: directives[:category] || DEFAULT_CATEGORY,
+        order: directives[:order] || DEFAULT_ORDER
+      }
+    end
+
+    entries
+      .group_by { |entry| entry[:category] }
+      .sort_by { |category, group| [group.map { |entry| entry[:order] }.min, category] }
+      .map { |category, group| [category, group.sort_by { |entry| [entry[:order], entry[:title]] }] }
+  end
+
+  # Read the `@category` / `@order` directives from a spec's doc comments. These
+  # control TOC placement only and are stripped from the rendered doc body.
+  def extract_directives(spec_file)
+    category = nil
+    order = nil
+
+    File.foreach(spec_file, encoding: 'UTF-8') do |line|
+      category ||= Regexp.last_match(1) if line =~ CATEGORY_DIRECTIVE
+      order ||= Regexp.last_match(1).to_i if line =~ ORDER_DIRECTIVE
+    end
+
+    { category:, order: }
+  end
+
+  # The doc title is the first top-level (`# =`, not `# ==`) heading comment.
+  def spec_doc_title(spec_file)
+    File.foreach(spec_file, encoding: 'UTF-8') do |line|
+      return Regexp.last_match(1).strip if line =~ /^\s*#\s*=(?!=)\s*(.+?)\s*$/
+    end
+
+    File.basename(spec_file, '_spec.rb').split('_').map(&:capitalize).join(' ')
+  end
+end
+
+# Parse command line arguments
+args = ARGV.dup
+check_mode = args.delete('--check')
+readme_only = args.delete('--readme-only')
+render_only = args.delete('--render-only')
+spec_files = args.empty? ? nil : args
+
+generator = DocGenerator.new(spec_files)
+
+if check_mode
+  # Used by the `docs:check` rake task — verify docs without running specs.
+  exit(generator.check ? 0 : 1)
+elsif readme_only
+  # Rebuild the table of contents from committed docs + spec directives only,
+  # without running any specs (fast; use after changing @category/@order).
+  generator.regenerate_readme
+elsif render_only
+  # Re-render doc bodies from doc comments using the screenshots already on
+  # disk, without running any specs. Use after prose-only doc-comment edits
+  # (Mermaid diagrams, tables, blockquotes) that don't change screenshots.
+  generator.generate(run_specs: false)
+else
+  generator.generate
+end

data/lib/generators/develoz/doc_specs/templates/lib/tasks/docs_check.rake.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+namespace :docs do
+  desc "Check platform-guide docs are in sync with their documented system specs"
+  task :check do # rubocop:disable Rails/RakeEnvironment
+    ruby "bin/generate-docs --check"
+  end
+end

data/lib/generators/develoz/doc_specs/templates/spec/support/doc_screenshot_helper.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Helper method for conditional screenshot capture
+# Usage: doc_screenshot('01_page_name')
+# Enable with: SCREENSHOTS=true rspec spec/...
+module DocScreenshotHelper
+  def doc_screenshot(filename)
+    return unless ENV["SCREENSHOTS"] == "true"
+
+    sleep 0.5 # Allow time for animations to complete
+    save_screenshot(Rails.root.join("docs/screenshots/#{filename}.png")) # rubocop:disable Lint/Debugger
+  end
+end
+
+RSpec.configure do |config|
+  config.include DocScreenshotHelper, type: :system
+end

data/lib/generators/develoz/doc_specs/templates/spec/system/example_doc_spec.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+#
+# @category Getting Started
+# @order 100
+
+# = Example Documentation Spec
+#
+# This spec demonstrates the self-documenting system spec pattern.
+# Doc comments starting with `# =` become headings in the generated markdown.
+# Use `# ==` for sub-headings, `# ===` for sub-sub-headings, etc.
+#
+# The `@category` and `@order` directives control where this guide appears
+# in the table of contents generated by `bin/generate-docs`.
+#
+# == Overview
+#
+# 1. Write doc comments above your system spec using `# = Heading` syntax
+# 2. Call `doc_screenshot('category/screenshot_name')` to capture screenshots
+# 3. Run `bin/generate-docs` to generate markdown documentation
+# 4. Run `rake docs:check` to verify docs are in sync with specs
+#
+describe "Example Documentation" do
+  before do
+    visit "/docs"
+  end
+
+  it "displays the homepage" do
+    expect(page).to have_css("body")
+
+    # === Homepage Screenshot
+    #
+    # This screenshot captures the homepage as seen by users.
+    doc_screenshot("getting-started/homepage")
+  end
+end

data/lib/generators/develoz/docker/docker_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "develoz"
+
+module Develoz
+  module Generators
+    class DockerGenerator < Develoz::Generators::Base
+      def self.source_root
+        File.expand_path("templates", __dir__)
+      end
+
+      def create_docker_compose
+        template "docker-compose.yml.tt", "docker-compose.yml"
+      end
+
+      def create_dockerfile_dev
+        template "dockerfile_dev.tt", "Dockerfile.dev"
+      end
+
+      def create_bin_dev
+        template "bin_dev.tt", "bin/dev"
+        chmod "bin/dev", 0o755
+      end
+
+      def create_bin_setup
+        template "bin_setup.tt", "bin/setup"
+        chmod "bin/setup", 0o755
+      end
+
+      def create_bin_docker_entrypoint
+        template "bin_docker_entrypoint.tt", "bin/docker-entrypoint"
+        chmod "bin/docker-entrypoint", 0o755
+      end
+
+      def create_bin_run
+        template "bin_run.tt", "bin/run"
+        chmod "bin/run", 0o755
+      end
+
+      def wire_env
+        append_env "POSTGRES_USER", "postgres"
+        append_env "POSTGRES_PASSWORD", "postgres"
+        append_env "POSTGRES_DB", "#{app_name}_development"
+        append_env "DATABASE_URL", "postgres://postgres:postgres@postgres:5432/#{app_name}_development"
+        append_env "SELENIUM_URL", "http://selenium:4444/wd/hub"
+        append_env "MAILCATCHER_URL", "http://mailcatcher:1080"
+      end
+
+      def ensure_env_gitignored
+        ensure_gitignore(".env")
+      end
+    end
+  end
+end

data/lib/generators/develoz/docker/templates/bin_dev.tt

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Start the development environment via Docker Compose
+docker compose up --build

data/lib/generators/develoz/docker/templates/bin_docker_entrypoint.tt

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Remove a potentially pre-existing server PID
+rm -f /rails/tmp/pids/server.pid
+
+# Run the Rails server in development
+bin/rails server -b 0.0.0.0 -p 3000

data/lib/generators/develoz/docker/templates/bin_run.tt

@@ -0,0 +1,152 @@
+#!/bin/bash
+
+# Docker-aware command runner
+# Runs commands locally or in Docker containers based on availability
+
+set -e
+
+docker_available() {
+    command -v docker >/dev/null 2>&1
+}
+
+docker_accessible() {
+    local output
+
+    if ! output=$(docker compose ps --services 2>/dev/null 2>&1); then
+        docker_error="$output"
+        return 1
+    fi
+
+    true
+}
+
+container_running() {
+    local service="$1"
+    local output
+
+    if ! output=$(docker compose ps "$service" --services 2>/dev/null 2>&1); then
+        docker_error="$output"
+        return 1
+    fi
+
+    echo "$output" | grep -q "$service"
+}
+
+container_built() {
+    local service="$1"
+    local output
+
+    if ! output=$(docker compose ps -a "$service" 2>/dev/null 2>&1); then
+        docker_error="$output"
+        return 1
+    fi
+
+    echo "$output" | grep -q "$service"
+}
+
+determine_service() {
+    local container_override="$1"
+
+    if [[ -n "$container_override" ]]; then
+        echo "$container_override"
+    else
+        echo "app"
+    fi
+}
+
+run_locally() {
+    local service="$1"
+    shift
+    echo "Running locally: $*"
+
+    # Source asdf environment
+    if [[ -d "$HOME/.asdf" ]]; then
+        export ASDF_DATA_DIR="$HOME/.asdf"
+        export PATH="$HOME/.asdf/bin:$HOME/.asdf/shims:$PATH"
+    fi
+
+    # Source rbenv if available
+    if [[ -d "$HOME/.rbenv" ]]; then
+        export PATH="$HOME/.rbenv/bin:$PATH"
+        eval "$(rbenv init -)"
+    fi
+
+    # Source RVM if available
+    if [[ -d "$HOME/.rvm" ]]; then
+        source "$HOME/.rvm/scripts/rvm"
+    fi
+
+    exec "$@"
+}
+
+run_with_docker() {
+    local service="$1"
+    shift
+    local -a mode=()
+    while [[ "$1" != "--" ]]; do
+        mode+=("$1")
+        shift
+    done
+    shift # consume --
+
+    echo "Running: docker compose ${mode[*]} $service $*"
+    exec docker compose "${mode[@]}" "$service" "$@"
+}
+
+if [[ $# -eq 0 ]]; then
+    echo "Usage: bin/run [--container <name>] <command>"
+    echo "Options:"
+    echo "  --container <name>    Run in a specific container (default: app)"
+    echo ""
+    echo "Examples:"
+    echo "  bin/run rspec"
+    echo "  bin/run rubocop -a"
+    echo "  bin/run rake db:migrate"
+    echo "  bin/run --container implementation bin/process"
+    exit 1
+fi
+
+# Parse --container flag
+container_override=""
+args=()
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --container)
+            if [[ -z "$2" || "$2" == --* ]]; then
+                echo "Error: --container requires a container name"
+                exit 1
+            fi
+            container_override="$2"
+            shift 2
+            ;;
+        *)
+            args+=("$1")
+            shift
+            ;;
+    esac
+done
+
+if [[ ${#args[@]} -eq 0 ]]; then
+    echo "Error: No command specified"
+    exit 1
+fi
+
+service=$(determine_service "$container_override")
+
+if ! docker_available; then
+    echo "Docker not available, running locally"
+    run_locally "$service" "${args[@]}"
+elif ! docker_accessible; then
+    echo "Docker is installed but not accessible: ${docker_error:-unknown error}"
+    echo "Ensure Docker is running and you have permission to access /var/run/docker.sock."
+    run_locally "$service" "${args[@]}"
+elif container_running "$service"; then
+    echo "Container $service is running"
+    run_with_docker "$service" exec -- "${args[@]}"
+elif container_built "$service"; then
+    echo "Container $service is built but stopped"
+    run_with_docker "$service" run -e SKIP_MIGRATIONS=true --rm -- "${args[@]}"
+else
+    echo "Container $service not available, running locally"
+    run_locally "$service" "${args[@]}"
+fi

data/lib/generators/develoz/docker/templates/bin_setup.tt

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "==> Setting up development environment..."
+
+# Install gems
+bundle install
+
+# Create and migrate the database
+if [ -f config/database.yml ]; then
+  bin/rails db:create db:migrate
+fi
+
+echo "==> Setup complete!"
+echo "Run bin/dev to start the development server."