feat: add static explanation

[Caknoooo]

Feature PR

Summary

Adding a feature to remove AxeCore/Deque references from the JSON output and replace them with cleaner, static explanations to make accessibility results more user-friendly, consistent, and easier for the business to understand.

Changes

• Components/Modules added or modified
• API/contract changes
• Backward compatibility impact

Evidence / Demo

Checklist

• Linked issue included (closes #xxx)
• Tests added/updated
• Documentation updated if needed
• Lint & build pass
• Accessibility considerations

[greptile-apps]

Greptile Overview

Greptile Summary

This PR replaces AxeCore/Deque references with static, user-friendly explanations sourced from rulesData.json.

Key Changes:

• Added new ViolationTransformer class that enriches accessibility violations with static data (title, summary, explanation, WCAG standards, ACT rules, supporting links)
• Integrated transformation into AI processing pipeline, so both AI and non-AI modes benefit from cleaner output
• Updated HTML report templates to display structured accessibility information with proper escaping
• Made helpUrl optional throughout the codebase since it's replaced by static explanations
• Enhanced UserStoryService with more robust file path resolution using fallback strategy
• Included comprehensive unit tests with 100% coverage of transformation scenarios

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Clean architecture with well-tested transformation logic, proper type safety, comprehensive HTML escaping, backward compatibility maintained, and no breaking changes to existing APIs
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
src/utils/violation-transformer.ts	5/5	New transformer class to enrich violations with static data from rulesData.json, removing AxeCore references
src/utils/ai-processor.ts	5/5	Integrated ViolationTransformer to apply static explanations before AI processing, improved type safety
src/services/user-stories.ts	5/5	Enhanced file path resolution with fallback strategy, made getRuleData async for consistency
src/cli/services/utils/html-generator.ts	5/5	Updated HTML templates to display static explanations, WCAG standards, ACT rules, and supporting links

Sequence Diagram

sequenceDiagram
    participant Client
    participant AIProcessor
    participant ViolationTransformer
    participant UserStoryService
    participant rulesData.json
    participant OpenAI
    participant HtmlGenerator

    Client->>AIProcessor: processAccessibilityIssues(issues)
    AIProcessor->>ViolationTransformer: transformMany(issues)
    
    loop For each issue
        ViolationTransformer->>UserStoryService: getRuleData(issue.id)
        UserStoryService->>rulesData.json: Read static data
        rulesData.json-->>UserStoryService: Rule data (title, summary, wcag, etc)
        UserStoryService-->>ViolationTransformer: Rule data
        ViolationTransformer->>ViolationTransformer: Enrich issue with static fields
    end
    
    ViolationTransformer-->>AIProcessor: Transformed issues (without helpUrl)
    
    alt AI Enabled
        loop For each transformed issue
            AIProcessor->>UserStoryService: getUserStory(issue.id)
            UserStoryService-->>AIProcessor: User story
            AIProcessor->>OpenAI: Generate explanation & remediation
            OpenAI-->>AIProcessor: AI response
            AIProcessor->>AIProcessor: Merge AI data with transformed issue
        end
    end
    
    AIProcessor-->>Client: Processed issues with static + AI data
    Client->>HtmlGenerator: Generate HTML report
    HtmlGenerator->>HtmlGenerator: Render title, summary, explanation, WCAG, ACT rules
    HtmlGenerator-->>Client: HTML report with user-friendly content

Loading

[greptile-apps]

_{7 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[4rokis]

LGTM