uniword 1.0.0

data/lib/uniword/accessibility/rules/contrast_ratio_rule.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Contrast Ratio Rule - WCAG 1.4.3 Contrast (Minimum)
+      #
+      # Responsibility: Check text/background contrast ratios
+      # Single Responsibility: Contrast ratio validation only
+      #
+      # WCAG 1.4.3 Level AA: Minimum contrast ratio of 4.5:1
+      class ContrastRatioRule < AccessibilityRule
+        # Check document contrast ratios
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(_document)
+          []
+
+          # Contrast ratio checking requires color analysis
+          # This is a placeholder implementation
+          # Actual implementation would check:
+          # - Text color vs background color
+          # - Minimum ratio of 4.5:1 for normal text (AA)
+          # - Minimum ratio of 3:1 for large text (AA)
+          # - Higher ratios for AAA compliance
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/descriptive_headings_rule.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Descriptive Headings Rule - WCAG 2.4.6 Headings and Labels
+      #
+      # Responsibility: Check that headings are descriptive
+      # Single Responsibility: Heading descriptiveness validation only
+      #
+      # WCAG 2.4.6 Level AA: Headings and labels describe topic or purpose
+      class DescriptiveHeadingsRule < AccessibilityRule
+        # Check document headings for descriptiveness
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(document)
+          violations = []
+
+          return violations unless @config[:check_descriptiveness]
+
+          headings = extract_headings(document)
+
+          headings.each_with_index do |heading, index|
+            text = extract_heading_text(heading[:paragraph])
+
+            # Check minimum length
+            if text && @config[:min_heading_length] && (text.length < @config[:min_heading_length])
+              violations << create_violation(
+                message: "Heading #{index + 1} is too short to be descriptive: '#{text}'",
+                element: heading[:paragraph],
+                severity: @config[:severity] || :warning,
+                suggestion: @config[:suggestion] ||
+                  'Use descriptive headings that clearly describe content'
+              )
+            end
+
+            # Check for generic headings
+            generic_headings = %w[heading section part introduction conclusion]
+            next unless text && generic_headings.any? { |g| text.downcase == g }
+
+            violations << create_violation(
+              message: "Heading #{index + 1} is too generic: '#{text}'",
+              element: heading[:paragraph],
+              severity: :warning,
+              suggestion: 'Make headings specific to the content they describe'
+            )
+          end
+
+          violations
+        end
+
+        private
+
+        # Extract headings from document
+        #
+        # @param document [Document] Document to extract from
+        # @return [Array<Hash>] Headings with level and paragraph
+        def extract_headings(document)
+          document.paragraphs
+                  .select { |p| heading_paragraph?(p) }
+                  .map { |p| { level: extract_heading_level(p), paragraph: p } }
+        end
+
+        # Check if paragraph is a heading
+        #
+        # @param paragraph [Paragraph] Paragraph to check
+        # @return [Boolean] True if heading
+        def heading_paragraph?(paragraph)
+          return false unless paragraph.style
+
+          paragraph.style.match?(/^Heading\s*\d+$/i) ||
+            paragraph.style.match?(/^h\d+$/i)
+        end
+
+        # Extract heading level from paragraph
+        #
+        # @param paragraph [Paragraph] Paragraph to extract from
+        # @return [Integer] Heading level
+        def extract_heading_level(paragraph)
+          match = paragraph.style.match(/(\d+)/)
+          match ? match[1].to_i : 1
+        end
+
+        # Extract text from heading paragraph
+        #
+        # @param paragraph [Paragraph] Paragraph to extract from
+        # @return [String, nil] Heading text
+        def extract_heading_text(paragraph)
+          if paragraph.respond_to?(:text)
+            paragraph.text
+          elsif paragraph.respond_to?(:runs)
+            paragraph.runs.map(&:text).join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/document_title_rule.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Document Title Rule - WCAG 2.4.2 Page Titled
+      #
+      # Responsibility: Check that document has a descriptive title
+      # Single Responsibility: Document title validation only
+      #
+      # WCAG 2.4.2 Level A: Pages must have titles that describe topic or purpose
+      class DocumentTitleRule < AccessibilityRule
+        # Check document title
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(document)
+          violations = []
+
+          title = extract_title(document)
+
+          # Check if title exists
+          if @config[:require_title] && (title.nil? || title.strip.empty?)
+            violations << create_violation(
+              message: 'Document missing title',
+              element: document,
+              severity: @config[:severity] || :error,
+              suggestion: @config[:suggestion] ||
+                'Document must have a descriptive title'
+            )
+            return violations
+          end
+
+          # Check minimum title length
+          if title && @config[:min_title_length] && (title.length < @config[:min_title_length])
+            violations << create_violation(
+              message: "Document title too short (#{title.length} chars)",
+              element: document,
+              severity: :warning,
+              suggestion: "Title should be descriptive (min #{@config[:min_title_length]} chars)"
+            )
+          end
+
+          violations
+        end
+
+        private
+
+        # Extract title from document
+        #
+        # @param document [Document] Document to extract from
+        # @return [String, nil] Document title
+        def extract_title(document)
+          # Try to get title from document metadata/properties
+          if document.respond_to?(:title)
+            document.title
+          elsif document.respond_to?(:metadata)
+            document.metadata&.title
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/heading_structure_rule.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Heading Structure Rule - WCAG 1.3.1 Info and Relationships
+      #
+      # Responsibility: Check proper heading hierarchy
+      # Single Responsibility: Heading structure validation only
+      #
+      # WCAG 1.3.1 Level A: Headings must follow proper hierarchy
+      class HeadingStructureRule < AccessibilityRule
+        # Check document heading structure
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(document)
+          violations = []
+          headings = extract_headings(document)
+
+          # Check if document needs headings but has none
+          if headings.empty? && requires_headings?(document)
+            violations << create_violation(
+              message: "Document lacks heading structure (#{document.paragraphs.count} paragraphs without headings)",
+              element: document,
+              severity: :warning,
+              suggestion: @config[:suggestion] ||
+                'Add headings to structure the content for screen readers'
+            )
+            return violations
+          end
+
+          # Check heading hierarchy
+          violations.concat(check_hierarchy(headings)) if @config[:check_hierarchy]
+
+          # Check for H1 requirement
+          if @config[:require_h1] && !has_h1?(headings)
+            violations << create_violation(
+              message: 'Document missing top-level heading (H1)',
+              element: document,
+              severity: :error,
+              suggestion: 'Start document with a level 1 heading (H1)'
+            )
+          end
+
+          violations
+        end
+
+        private
+
+        # Extract headings from document
+        #
+        # @param document [Document] Document to extract from
+        # @return [Array<Hash>] Headings with level and paragraph
+        def extract_headings(document)
+          document.paragraphs
+                  .select { |p| heading_paragraph?(p) }
+                  .map { |p| { level: extract_heading_level(p), paragraph: p } }
+        end
+
+        # Check if paragraph is a heading
+        #
+        # @param paragraph [Paragraph] Paragraph to check
+        # @return [Boolean] True if heading
+        def heading_paragraph?(paragraph)
+          return false unless paragraph.style
+
+          paragraph.style.match?(/^Heading\s*\d+$/i) ||
+            paragraph.style.match?(/^h\d+$/i)
+        end
+
+        # Extract heading level from paragraph
+        #
+        # @param paragraph [Paragraph] Paragraph to extract from
+        # @return [Integer] Heading level
+        def extract_heading_level(paragraph)
+          match = paragraph.style.match(/(\d+)/)
+          match ? match[1].to_i : 1
+        end
+
+        # Check if document requires headings
+        #
+        # @param document [Document] Document to check
+        # @return [Boolean] True if headings required
+        def requires_headings?(document)
+          min = @config[:min_paragraphs_for_heading] || 5
+          document.paragraphs.count >= min
+        end
+
+        # Check heading hierarchy
+        #
+        # @param headings [Array<Hash>] Extracted headings
+        # @return [Array<AccessibilityViolation>] Hierarchy violations
+        def check_hierarchy(headings)
+          violations = []
+          previous_level = 0
+
+          headings.each_with_index do |heading, index|
+            level = heading[:level]
+
+            # Headings should not skip levels
+            if @config[:no_level_skipping] && level > previous_level + 1
+              violations << create_violation(
+                message: "Heading hierarchy skip: Level #{previous_level} to #{level} (heading #{index + 1})",
+                element: heading[:paragraph],
+                severity: @config[:severity] || :error,
+                suggestion: 'Headings should increase by one level at a time (e.g., H1 → H2, not H1 → H3)'
+              )
+            end
+
+            previous_level = level
+          end
+
+          violations
+        end
+
+        # Check if document has H1
+        #
+        # @param headings [Array<Hash>] Extracted headings
+        # @return [Boolean] True if H1 exists
+        def has_h1?(headings)
+          headings.any? { |h| h[:level] == 1 }
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/image_alt_text_rule.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Image Alt Text Rule - WCAG 1.1.1 Non-text Content
+      #
+      # Responsibility: Check that images have alternative text
+      # Single Responsibility: Image alt text validation only
+      #
+      # WCAG 1.1.1 Level A: All non-text content must have text alternative
+      class ImageAltTextRule < AccessibilityRule
+        # Check document images for alt text
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(document)
+          violations = []
+
+          document.images.each_with_index do |image, index|
+            # Check for alt text existence
+            if image.alt_text.nil? || image.alt_text.strip.empty?
+              violations << create_violation(
+                message: "Image #{index + 1} missing alternative text",
+                element: image,
+                severity: @config[:severity] || :error,
+                suggestion: @config[:suggestion] ||
+                  "Add descriptive alternative text using image.alt_text = '...'"
+              )
+              next # Skip quality checks if no alt text
+            end
+
+            # Check alt text quality if enabled
+            next unless @config[:check_quality]
+
+            violations.concat(check_alt_text_quality(image, index))
+          end
+
+          violations
+        end
+
+        private
+
+        # Check quality of alt text
+        #
+        # @param image [Image] Image to check
+        # @param index [Integer] Image index
+        # @return [Array<AccessibilityViolation>] Quality violations
+        def check_alt_text_quality(image, index)
+          violations = []
+
+          # Check minimum length
+          if @config[:min_length] && image.alt_text.length < @config[:min_length]
+            violations << create_violation(
+              message: "Image #{index + 1} has insufficient alt text (too short: #{image.alt_text.length} chars)",
+              element: image,
+              severity: :warning,
+              suggestion: "Alternative text should describe the image content meaningfully (min #{@config[:min_length]} chars)"
+            )
+          end
+
+          # Check maximum length
+          if @config[:max_length] && image.alt_text.length > @config[:max_length]
+            violations << create_violation(
+              message: "Image #{index + 1} has excessive alt text (too long: #{image.alt_text.length} chars)",
+              element: image,
+              severity: :warning,
+              suggestion: "Keep alternative text concise (max #{@config[:max_length]} chars)"
+            )
+          end
+
+          # Check for unhelpful generic text
+          unhelpful = %w[image picture photo img graphic icon]
+          alt_lower = image.alt_text.downcase
+          if unhelpful.any? { |word| alt_lower == word || alt_lower.start_with?("#{word} of") }
+            violations << create_violation(
+              message: "Image #{index + 1} has generic alt text: '#{image.alt_text}'",
+              element: image,
+              severity: :warning,
+              suggestion: "Describe what the image shows, not that it's an image"
+            )
+          end
+
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/language_specification_rule.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Language Specification Rule - WCAG 3.1.1 Language of Page
+      #
+      # Responsibility: Check that document language is specified
+      # Single Responsibility: Language specification validation only
+      #
+      # WCAG 3.1.1 Level A: Default human language of page can be programmatically determined
+      class LanguageSpecificationRule < AccessibilityRule
+        # Check document language specification
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(document)
+          violations = []
+
+          return violations unless @config[:require_language]
+
+          language = extract_language(document)
+
+          # Check if language is specified
+          if language.nil? || language.strip.empty?
+            violations << create_violation(
+              message: 'Document language not specified',
+              element: document,
+              severity: @config[:severity] || :error,
+              suggestion: @config[:suggestion] ||
+                'Set document language property for screen readers'
+            )
+          end
+
+          violations
+        end
+
+        private
+
+        # Extract language from document
+        #
+        # @param document [Document] Document to extract from
+        # @return [String, nil] Document language code
+        def extract_language(document)
+          # Try to get language from document metadata/properties
+          if document.respond_to?(:language)
+            document.language
+          elsif document.respond_to?(:metadata)
+            document.metadata&.language
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/list_structure_rule.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # List Structure Rule - WCAG 1.3.1 Info and Relationships
+      #
+      # Responsibility: Check proper list structure and nesting
+      # Single Responsibility: List structure validation only
+      #
+      # WCAG 1.3.1 Level A: Lists must use proper structure
+      class ListStructureRule < AccessibilityRule
+        # Check document lists for proper structure
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(_document)
+          []
+
+          # Check for lists that may be improperly structured
+          # This is a simplified check - actual implementation would need
+          # to examine list elements in the document structure
+
+          # For now, return empty as this requires deeper document introspection
+          # In a real implementation, we would check:
+          # - Proper nesting levels
+          # - Maximum nesting depth
+          # - Consistent list types
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/reading_order_rule.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Reading Order Rule - WCAG 1.3.2 Meaningful Sequence
+      #
+      # Responsibility: Check logical reading order
+      # Single Responsibility: Reading order validation only
+      #
+      # WCAG 1.3.2 Level A: Content must be in meaningful sequence
+      class ReadingOrderRule < AccessibilityRule
+        # Check document reading order
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(_document)
+          []
+
+          # Reading order checking requires analyzing document structure
+          # This is a placeholder implementation
+          # Actual implementation would check for:
+          # - Tables before their captions
+          # - Images before their descriptions
+          # - Footnotes in proper sequence
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules/table_headers_rule.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      # Table Headers Rule - WCAG 1.3.1 Info and Relationships
+      #
+      # Responsibility: Check that tables have proper headers
+      # Single Responsibility: Table header validation only
+      #
+      # WCAG 1.3.1 Level A: Data tables must have headers
+      class TableHeadersRule < AccessibilityRule
+        # Check document tables for headers
+        #
+        # @param document [Document] Document to check
+        # @return [Array<AccessibilityViolation>] Found violations
+        def check(document)
+          violations = []
+
+          document.tables.each_with_index do |table, index|
+            # Check if table has header row
+            has_header = table.rows.first&.header?
+
+            unless has_header
+              violations << create_violation(
+                message: "Table #{index + 1} missing header row",
+                element: table,
+                severity: @config[:severity] || :error,
+                suggestion: @config[:suggestion] ||
+                  'Mark first row as header: table.rows.first.header = true'
+              )
+            end
+
+            # Check for caption if required
+            next unless @config[:require_caption] && !table_has_caption?(table)
+
+            violations << create_violation(
+              message: "Table #{index + 1} missing caption",
+              element: table,
+              severity: :warning,
+              suggestion: 'Add table caption to describe the data presented'
+            )
+          end
+
+          violations
+        end
+
+        private
+
+        # Check if table has caption
+        #
+        # @param table [Table] Table to check
+        # @return [Boolean] True if caption exists
+        def table_has_caption?(table)
+          # Tables may have a caption property or title
+          table.respond_to?(:caption) && !table.caption.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/uniword/accessibility/rules.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    module Rules
+      autoload :ColorUsageRule, "#{__dir__}/rules/color_usage_rule"
+      autoload :ContrastRatioRule, "#{__dir__}/rules/contrast_ratio_rule"
+      autoload :DescriptiveHeadingsRule, "#{__dir__}/rules/descriptive_headings_rule"
+      autoload :DocumentTitleRule, "#{__dir__}/rules/document_title_rule"
+      autoload :HeadingStructureRule, "#{__dir__}/rules/heading_structure_rule"
+      autoload :ImageAltTextRule, "#{__dir__}/rules/image_alt_text_rule"
+      autoload :LanguageSpecificationRule, "#{__dir__}/rules/language_specification_rule"
+      autoload :ListStructureRule, "#{__dir__}/rules/list_structure_rule"
+      autoload :ReadingOrderRule, "#{__dir__}/rules/reading_order_rule"
+      autoload :TableHeadersRule, "#{__dir__}/rules/table_headers_rule"
+    end
+  end
+end

data/lib/uniword/accessibility.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Accessibility
+    autoload :AccessibilityChecker, "#{__dir__}/accessibility/accessibility_checker"
+    autoload :AccessibilityProfile, "#{__dir__}/accessibility/accessibility_profile"
+    autoload :AccessibilityReport, "#{__dir__}/accessibility/accessibility_report"
+    autoload :AccessibilityRule, "#{__dir__}/accessibility/accessibility_rule"
+    autoload :AccessibilityViolation, "#{__dir__}/accessibility/accessibility_violation"
+    autoload :Rules, "#{__dir__}/accessibility/rules"
+  end
+end