w1-system-font-validator/README.md

VS Code extension for validating W1 System font variables (both fontConfig.json and localFontConfig.json)

# W1 System Font Validator - VSCode Extension

Advanced VS Code extension for validating W1 System font variables with unified font system support.

## Features

- Unified Font System Validation - Supports both package and local fonts with identical validation logic
- Smart Weight/Style Validation - Checks actual font availability against CSS usage
- CSS Context Analysis - Links font-family variables with font-weight declarations in the same CSS rule
- Migration Assistant - Detects deprecated weight-specific patterns and suggests modern alternatives
- Intelligent Hover Info - Shows available weights and styles for any font-family variable
- Real-time Validation - Validates as you type with smart debouncing

## Quick Start

### Installation

#### From VSIX (Development)

1. Download or build the `.vsix` file
2. In VS Code/Cursor: Extensions → "..." → "Install from VSIX..."
3. Select the `.vsix` file
4. Reload window

#### Building from Source

```bash
git clone <repository>
cd w1-system-font-manager-vsc-extension
npm install
npm run build
npm run package
```

### Basic Setup

The extension automatically detects font configurations in your project root:

- `fontConfig.json` - Package-based fonts
- `localFontConfig.json` - Local file-based fonts

### First Usage

Create a CSS file with W1 font variables and observe real-time validation:

```css
.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 700; /* Valid weight - no error */
}

.text {
  font-family: var(--fontfamily_primary);
  font-weight: 600; /* Invalid weight - shows error */
}
```

## Architecture

### Core Concepts

The extension performs intelligent CSS analysis by parsing CSS rules and correlating font-family variables with font-weight and font-style declarations. It validates against actual font configurations to ensure type-safe font usage.

### System Integration

The extension integrates with both W1 Font Manager and W1 Local Font Manager, supporting unified validation across package-based and local file-based font systems within the W1 ecosystem.

### Data Structure

```typescript
interface FontRole {
  displayName: string;
  availableWeights: Record<string, WeightInfo>;
  variables: {
    family: string;
  };
}

interface WeightInfo {
  weight: number;
  style: 'normal' | 'italic';
}

interface ValidationResult {
  diagnostics: Diagnostic[];
  hasErrors: boolean;
  processedRules: number;
}
```

## API Reference

### Main Commands

#### `W1 Font Validator: Debug Current File`

Trigger manual validation with comprehensive debug output.

**Usage**: Open Command Palette (`Ctrl+Shift+P`) and run the command

**Output**: Detailed validation information in VS Code Output Panel

#### `W1 Font Validator: Reload Configuration`

Force reload font configurations from project files.

**Usage**: Run when configuration files change

### Configuration Options

```json
{
  "w1FontValidator.validateOnType": true,
  "w1FontValidator.showHoverInfo": true,
  "w1FontValidator.supportLocalFonts": true,
  "w1FontValidator.supportPackageFonts": true,
  "w1FontValidator.debugMode": false
}
```

**Settings**:

- `validateOnType` (boolean) - Enable real-time validation
- `showHoverInfo` (boolean) - Show hover information for font variables
- `supportLocalFonts` (boolean) - Validate local font configurations
- `supportPackageFonts` (boolean) - Validate package font configurations
- `debugMode` (boolean) - Enable verbose debug logging

## CLI Commands

This extension does not provide CLI commands. It operates within VS Code/Cursor editor environment.

## Advanced Usage

### Context-Aware Validation

The extension analyzes complete CSS rules to understand font context:

```css
.component {
  font-family: var(--fontfamily_primary);
  font-weight: 500; /* Validates against primary font's available weights */
  font-style: italic; /* Checks if italic is available for weight 500 */
}
```

### Supported Font Systems

#### Package-Based Fonts (fontConfig.json)

```json
{
  "roles": {
    "primary": {
      "displayName": "Inter",
      "availableWeights": {
        "400": {"weight": 400, "style": "normal"},
        "400_italic": {"weight": 400, "style": "italic"},
        "700": {"weight": 700, "style": "normal"}
      },
      "variables": {
        "family": "--fontfamily_primary"
      }
    }
  }
}
```

#### Local File-Based Fonts (localFontConfig.json)

```json
{
  "detailedRoles": {
    "primary_local": {
      "displayName": "Inter",
      "availableWeights": {
        "400": {"weight": 400, "style": "normal"},
        "400_italic": {"weight": 400, "style": "italic"},
        "700": {"weight": 700, "style": "normal"}
      },
      "variables": {
        "family": "--fontfamily_primary_local"
      }
    }
  }
}
```

### Migration Assistant

The extension detects deprecated patterns and suggests modern alternatives:

```css
/* Deprecated - Will show warning */
.heading {
  font-family: var(--font_primary_bold);
}

/* Modern - Recommended */
.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 700;
}
```

## Development

### Local Development Setup

```bash
# Clone and setup
git clone <repository>
cd w1-system-font-manager-vsc-extension
npm install
npm run build
```

### Build System

- **TypeScript**: Full extension development with VS Code APIs
- **Webpack**: Bundling for extension distribution
- **VSIX Packaging**: Extension packaging for distribution
- **Watch Mode**: Live development with auto-rebuild

### Contributing

- Follow VS Code extension development guidelines
- Include tests for validation logic
- Update debug capabilities for new features
- Follow semantic versioning

## Migration & Compatibility

### Version History

- **v2.0**: Unified font system support with enhanced validation
- **v1.5**: Added migration assistant and hover information
- **v1.0**: Initial CSS validation for W1 font variables

### Breaking Changes

#### v2.0 Migration

Enhanced validation may detect previously undetected issues:

```typescript
// v1.x - May not catch invalid combinations
// v2.0+ - Validates weight + style combinations
.text {
  font-family: var(--fontfamily_primary);
  font-weight: 500;
  font-style: italic; // Now validates if 500 italic exists
}
```

### Compatibility

- VS Code version: >=1.74.0
- Node.js version: >=16.0.0
- Supports both W1 Font Manager v1.4+ and W1 Local Font Manager v2.0+
- Works with CSS, SCSS, Less, and CSS Modules

## Troubleshooting

### Common Issues

#### Extension not providing validation

**Solution**: Verify font configuration files exist in project root:

```bash
# Check for configuration files
ls -la fontConfig.json localFontConfig.json

# Run debug command in VS Code
# Command Palette → "W1 Font Validator: Debug Current File"
```

#### No hover information displayed

**Solution**: Ensure hover info is enabled and you're hovering over valid font variables:

```json
{
  "w1FontValidator.showHoverInfo": true
}
```

#### Validation not working in specific files

**Solution**: Check supported file types and patterns:

- Files must be `*.css`, `*.scss`, `*.less`, or `*.module.css`
- Files in `/styles/` directories are automatically included
- `globals.css` and `global.css` are supported

### Debug Mode

Enable comprehensive debug output:

1. Open Output Panel: View → Output
2. Select "W1 Font Validator" from dropdown
3. Enable debug mode in settings
4. View real-time validation logs

**Debug Output Example**:

```text
[W1 Font Validator] Validating: global.css
Configuration loaded: fontConfig.json
Found 3 font-family variables
Found 2 invalid weight combinations
Validation completed with 2 diagnostics
```

## Validation Examples

### Valid Usage

```css
.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 700; /* Available weight */
}

.text {
  font-family: var(--fontfamily_primary_local);
  font-weight: 400;
  font-style: italic; /* Available combination */
}
```

### Invalid Usage (Shows Errors)

```css
.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 600; /* NOT available for this font */
}

.text {
  font-family: var(--fontfamily_nonexistent); /* Invalid variable */
}
```

### Deprecated Patterns (Shows Warnings)

```css
.heading {
  font-family: var(--font_primary_bold); /* Deprecated */
  /* Should be: font-family: var(--fontfamily_primary); font-weight: 700; */
}
```

## Supported File Types

- `*.css` - Standard CSS files
- `*.scss` - Sass files
- `*.less` - Less files
- `*.module.css` - CSS Modules
- Files in `/styles/` directories
- `globals.css` and `global.css`

## Related Packages

- [`@werk1/w1-system-font-manager`](https://npmjs.com/package/@werk1/w1-system-font-manager) - Package-based font management
- [`@werk1/w1-system-local-font-manager`](https://npmjs.com/package/@werk1/w1-system-local-font-manager) - Local font file management
- [`@werk1/w1-system-core`](https://npmjs.com/package/@werk1/w1-system-core) - Core W1 System components

## License

MIT © Werk1