CSS Auditor for Angular

An intelligent VS Code extension that audits CSS/SCSS files in Angular projects, identifies best practice violations, and provides AI-powered remediation suggestions.

Features

• Automatic Detection: Automatically activates when opening Angular projects (detects angular.json)
• Manual Auditing: Run audits manually via Command Palette
• Intelligent Analysis: Parses CSS/SCSS files and identifies violations of best practices
• AI-Powered Solutions: Generates contextual, step-by-step remediation advice using OpenAI or Anthropic APIs
• Interactive UI: Beautiful two-panel webview interface with file navigation
• Smart Caching: Caches LLM responses to optimize API usage and performance
• Progress Tracking: Real-time progress updates during analysis
• Advanced Conflict Detection: 10+ conflict types including Angular-specific, CSS variables, third-party libraries
• Performance Profiling: Measures analysis execution time and provides optimization recommendations
• Cross-File Analysis: Identifies conflicts across multiple CSS/SCSS files

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "CSS Auditor"
4. Click Install

From Source

1. Clone this repository
2. Run npm install
3. Run npm run compile
4. Press F5 to launch Extension Development Host

Automated Build (Recommended)

# Automated build and packaging
npm run build:extension

# Or use the build script directly
./build-extension.sh

Configuration

API Configuration

The extension requires an LLM API key for generating solutions:

1. Open VS Code Settings (Ctrl+,)
2. Search for "CSS Auditor"
3. Configure the following settings:

OpenAI (Default)

• CSS Auditor: LLM API Key: Your OpenAI API key
• CSS Auditor: LLM Provider: openai

Anthropic

• CSS Auditor: LLM API Key: Your Anthropic API key
• CSS Auditor: LLM Provider: anthropic

Usage

Automatic Activation

The extension automatically activates when you open a workspace containing an angular.json file.

Manual Audit

1. Open Command Palette (Ctrl+Shift+P)
2. Type "CSS Auditor: Run CSS Audit"
3. Press Enter

Testing Commands

Quick Test (Recommended for validation)

• Command: CSS Auditor: Quick Test
• Purpose: Creates a small test file and analyzes it
• Expected time: < 5 seconds
• Use case: Validate extension is working correctly

Performance Diagnostic

• Command: CSS Auditor: Run Performance Diagnostic
• Purpose: Compares analysis performance and provides optimization insights
• Expected time: < 15 seconds
• Use case: Monitor extension performance

Full Audit

• Command: CSS Auditor: Run Audit
• Purpose: Analyzes all CSS/SCSS files in your workspace
• Expected time: < 30 seconds (limited to 50 files for performance)
• Use case: Complete project analysis

Viewing Results

• The extension will scan all .css and .scss files in your workspace
• Results are displayed in a two-panel webview:
  • Left Panel: List of files with violations
  • Right Panel: Detailed violations with AI-generated solutions
• Click "Go to File" to navigate to specific violations in your code
• Results also appear in the VS Code sidebar under "CSS Audit Results"

Detected Violations

The extension detects 10+ categories of CSS best practice violations:

🎯 Advanced Conflict Detection

• Component Conflicts: Angular-specific issues with ::ng-deep, view encapsulation
• Specificity Wars: Cascading conflicts and !important usage
• Third-Party Library Conflicts: Angular Material, PrimeNG, Bootstrap overrides
• CSS Variables Conflicts: Root-level variable and theme conflicts
• Browser Compatibility: Modern CSS features not supported in older browsers

🎨 Visual & Layout Conflicts

• Color Conflicts: Inconsistent color usage across components
• Layout Breaking: CSS that breaks page layout structure
• Animation Conflicts: Transition and transform issues
• Responsive Design: Conflicts between different breakpoints

⚡ Performance Issues

• Universal Selectors: Performance-killing * selectors
• Deep Nesting: Selectors with excessive nesting (>4 levels)
• Expensive Patterns: Rendering performance bottlenecks

♿ Accessibility & Best Practices

• Color Contrast: Insufficient color contrast ratios
• Font Units: Recommends relative units (em/rem) over px
• Z-Index Magic Numbers: Inconsistent z-index values

🔧 Basic Best Practices

• Avoid !important: Breaks natural cascade and maintainability
• Shorthand Properties: Reduces CSS file size and improves maintainability
• Magic Numbers: Use consistent scales for better maintainability

📊 Severity Levels

• Critical 🔴: Immediate action required (security/performance risks)
• High 🟠: Significant issues affecting functionality
• Medium 🟡: Important but not critical issues
• Low 🟢: Minor improvements or warnings

Architecture

The extension follows an agentic systems architecture with four specialized agents:

1. Orchestrator Agent: Manages the end-to-end audit workflow
2. Analyst Agent: Parses CSS/SCSS and identifies violations
3. Solutions Agent: Generates AI-powered remediation advice
4. Presenter Agent: Manages the user interface and webview

Development

Project Structure

src/
├── agents/
│   ├── orchestrator.ts        # Workflow coordinator
│   ├── analyst.ts             # Code analysis engine
│   ├── solutions.ts           # AI solution generator
│   ├── presenter.ts           # UI controller
│   ├── conflictDetector.ts    # Advanced conflict detection
│   └── advancedConflictAnalyzer.ts # Sophisticated analysis engine
├── providers/
│   └── auditTreeProvider.ts   # Tree view provider
├── rules/
│   └── best-practices.ts      # CSS rule definitions
├── types/
│   └── index.ts               # TypeScript interfaces
└── extension.ts               # Main activation file

Building

Automated Build (Recommended)

npm run build:extension

This script:

• Cleans previous build artifacts
• Compiles using webpack (production mode)
• Packages into a .vsix file using vsce
• Provides installation instructions

Manual Build Steps

npm run compile    # Build the extension
npm run watch      # Watch mode for development
npm run package    # Create .vsix package
npm run clean      # Clean build artifacts

Build Output

• build/extension.js - Optimized production bundle (~45 KB)
• css-auditor-{version}.vsix - Installable package (~36 KB)

Testing

npm run test       # Run unit tests
npm run pretest    # Compile and lint before testing

Performance Testing

• Quick Test: Validates extension functionality (< 5 seconds)
• Performance Diagnostic: Compares analyzer performance (< 15 seconds)
• Full Audit: Complete project analysis (< 30 seconds, max 50 files)

Changelog

v1.0.5 (Latest)

• Enhanced Detection: Added 18 comprehensive conflict patterns
• Performance Fixes: Resolved infinite loop issues with timeout protection
• File Limiting: Max 50 files analyzed for optimal performance
• Advanced Analyzer: Integrated OptimizedAdvancedConflictAnalyzerAgent
• Promise Protection: Added Promise.race() timeout wrapping

v1.0.0

• Initial release
• Basic CSS/SCSS analysis
• AI-powered solution generation
• Interactive webview interface
• Automatic Angular project detection
• Tree view with conflict categorization
• Cross-file analysis capabilities

Documentation

• Advanced Analyzer - Detailed technical documentation
• Feature Overview - Complete feature descriptions
• Performance Optimization - Performance tuning guide
• Detection Fixes - Bug fixes and improvements

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

If you encounter issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include your VS Code version and extension version
4. Check the console logs for detailed error information