Merge pull request #171 from bookedsolidtech/feat/validate-css-file

feat: add validate_css_file multi-component CSS validator

Author: himerus

.changeset/validate-css-file.md

@@ -0,0 +1,6 @@
+---
+'helixir': minor
+'@helixir/core': minor
+---
+
+Add validate_css_file MCP tool — validates entire CSS files targeting multiple web components in one call with auto-detection

custom-elements.json

@@ -0,0 +1,283 @@
+/**
+ * CSS File Validator — validates an entire CSS file containing styles for
+ * multiple web components. Auto-detects which components are referenced,
+ * runs per-component validation (shadow DOM, API resolution), and runs
+ * global validators (specificity, color contrast, shorthand, theme).
+ *
+ * This is the "just validate my whole file" tool — agents don't need to
+ * know which components are used or call validators individually.
+ */
+
+import type { Cem } from './cem.js';
+import { parseCem } from './cem.js';
+import { checkShadowDomUsage } from './shadow-dom-checker.js';
+import { resolveCssApi } from './css-api-resolver.js';
+import { checkThemeCompatibility } from './theme-checker.js';
+import { checkCssSpecificity } from './specificity-checker.js';
+import { checkColorContrast } from './color-contrast-checker.js';
+import { checkCssShorthand } from './shorthand-checker.js';
+import { checkCssScopeFromMeta } from './scope-checker.js';
+import { checkTokenFallbacksFromMeta } from './token-fallback-checker.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface CssFileIssue {
+  severity: 'error' | 'warning' | 'info';
+  category: string;
+  message: string;
+  line?: number;
+  suggestion?: string;
+  component?: string;
+}
+
+export interface ComponentValidation {
+  tagName: string;
+  issues: CssFileIssue[];
+  invalidParts: string[];
+  invalidTokens: string[];
+}
+
+export interface CssFileValidationResult {
+  clean: boolean;
+  totalIssues: number;
+  componentsFound: string[];
+  components: Record<string, ComponentValidation>;
+  globalIssues: CssFileIssue[];
+  verdict: string;
+}
+
+// ─── Component Detection ────────────────────────────────────────────────────
+
+/**
+ * Extracts web component tag names from CSS selectors.
+ * Matches: tag-name {, tag-name::part(x) {, tag-name.class {, tag-name[attr] {
+ */
+function detectComponentsInCss(css: string, cem: Cem): string[] {
+  // Build a set of known tag names from the CEM
+  const knownTags = new Set<string>();
+  for (const mod of cem.modules) {
+    for (const decl of mod.declarations ?? []) {
+      if ('tagName' in decl && decl.tagName) {
+        knownTags.add(decl.tagName);
+      }
+    }
+  }
+
+  // Find all custom element tags referenced in selectors
+  // Custom elements must contain a hyphen
+  const tagPattern = /(?:^|[},;\s])([a-z][a-z0-9]*-[a-z0-9-]*)(?=[.:{\s,[[])/gm;
+  const found = new Set<string>();
+  let match: RegExpExecArray | null;
+
+  while ((match = tagPattern.exec(css)) !== null) {
+    const tag = (match[1] ?? '').trim();
+    if (knownTags.has(tag)) {
+      found.add(tag);
+    }
+  }
+
+  return [...found].sort();
+}
+
+// ─── Main Entry Point ───────────────────────────────────────────────────────
+
+export function validateCssFile(css: string, cem: Cem): CssFileValidationResult {
+  const componentsFound = detectComponentsInCss(css, cem);
+  const components: Record<string, ComponentValidation> = {};
+  const globalIssues: CssFileIssue[] = [];
+
+  // Per-component validation
+  for (const tagName of componentsFound) {
+    const issues: CssFileIssue[] = [];
+    const invalidParts: string[] = [];
+    const invalidTokens: string[] = [];
+
+    try {
+      const meta = parseCem(tagName, cem);
+
+      // Shadow DOM anti-patterns
+      safeRun(() => {
+        const shadowResult = checkShadowDomUsage(css, tagName, meta);
+        for (const issue of shadowResult.issues) {
+          issues.push({
+            severity: issue.severity === 'error' ? 'error' : 'warning',
+            category: 'shadowDom',
+            message: issue.message,
+            line: issue.line,
+            suggestion: issue.suggestion,
+            component: tagName,
+          });
+        }
+      });
+
+      // CSS API resolution (parts, tokens, slots)
+      safeRun(() => {
+        const resolution = resolveCssApi(css, meta);
+        for (const part of resolution.parts.resolved) {
+          if (!part.valid) {
+            invalidParts.push(part.name);
+            issues.push({
+              severity: 'error',
+              category: 'invalidPart',
+              message: `::part(${part.name}) does not exist on <${tagName}>. ${part.suggestion ? `Did you mean: ${part.suggestion}` : `Valid parts: ${meta.cssParts.map((p) => p.name).join(', ') || 'none'}`}`,
+              component: tagName,
+            });
+          }
+        }
+        for (const token of resolution.tokens.resolved) {
+          if (!token.valid) {
+            invalidTokens.push(token.name);
+            issues.push({
+              severity: 'error',
+              category: 'invalidToken',
+              message: `CSS custom property "${token.name}" does not exist on <${tagName}>. ${token.suggestion ? `Did you mean: ${token.suggestion}` : ''}`,
+              component: tagName,
+            });
+          }
+        }
+      });
+
+      // Token fallbacks
+      safeRun(() => {
+        const knownTokens = new Set(meta.cssProperties.map((p) => p.name));
+        const fallbackResult = checkTokenFallbacksFromMeta(css, knownTokens);
+        for (const issue of fallbackResult.issues) {
+          issues.push({
+            severity: 'warning',
+            category: 'tokenFallbacks',
+            message: issue.message,
+            line: issue.line,
+            component: tagName,
+          });
+        }
+      });
+
+      // Scope validation
+      safeRun(() => {
+        const scopeResult = checkCssScopeFromMeta(css, tagName, meta.cssProperties);
+        for (const issue of scopeResult.issues) {
+          issues.push({
+            severity: 'warning',
+            category: 'scope',
+            message: issue.message,
+            line: issue.line,
+            component: tagName,
+          });
+        }
+      });
+    } catch {
+      // Tag not in CEM — skip per-component validation
+    }
+
+    components[tagName] = { tagName, issues, invalidParts, invalidTokens };
+  }
+
+  // Global CSS validation (not component-specific)
+  safeRun(() => {
+    const themeResult = checkThemeCompatibility(css);
+    for (const issue of themeResult.issues) {
+      globalIssues.push({
+        severity: 'warning',
+        category: 'themeCompat',
+        message: issue.message,
+        line: issue.line,
+      });
+    }
+  });
+
+  safeRun(() => {
+    const specResult = checkCssSpecificity(css);
+    for (const issue of specResult.issues) {
+      globalIssues.push({
+        severity: 'info',
+        category: 'specificity',
+        message: issue.message,
+        line: issue.line,
+      });
+    }
+  });
+
+  safeRun(() => {
+    const contrastResult = checkColorContrast(css);
+    for (const issue of contrastResult.issues) {
+      globalIssues.push({
+        severity: 'warning',
+        category: 'colorContrast',
+        message: issue.message,
+        line: issue.line,
+      });
+    }
+  });
+
+  safeRun(() => {
+    const shorthandResult = checkCssShorthand(css);
+    for (const issue of shorthandResult.issues) {
+      globalIssues.push({
+        severity: 'warning',
+        category: 'shorthand',
+        message: issue.message,
+        line: issue.line,
+        suggestion: issue.suggestion,
+      });
+    }
+  });
+
+  // Aggregate
+  const allIssues = [...globalIssues, ...Object.values(components).flatMap((c) => c.issues)];
+  const totalIssues = allIssues.length;
+  const clean = totalIssues === 0;
+  const verdict = buildVerdict(componentsFound, components, globalIssues, totalIssues);
+
+  return {
+    clean,
+    totalIssues,
+    componentsFound,
+    components,
+    globalIssues,
+    verdict,
+  };
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function safeRun(fn: () => void): void {
+  try {
+    fn();
+  } catch {
+    // Individual checker failed — skip
+  }
+}
+
+function buildVerdict(
+  componentsFound: string[],
+  components: Record<string, ComponentValidation>,
+  globalIssues: CssFileIssue[],
+  totalIssues: number,
+): string {
+  if (totalIssues === 0) {
+    return componentsFound.length > 0
+      ? `Clean — ${componentsFound.length} component${componentsFound.length > 1 ? 's' : ''} validated, no issues.`
+      : 'Clean — no web components detected in CSS.';
+  }
+
+  const errors = [
+    ...globalIssues.filter((i) => i.severity === 'error'),
+    ...Object.values(components).flatMap((c) => c.issues.filter((i) => i.severity === 'error')),
+  ].length;
+
+  const warnings = [
+    ...globalIssues.filter((i) => i.severity === 'warning'),
+    ...Object.values(components).flatMap((c) => c.issues.filter((i) => i.severity === 'warning')),
+  ].length;
+
+  const parts: string[] = [];
+  if (errors > 0) parts.push(`${errors} error${errors > 1 ? 's' : ''}`);
+  if (warnings > 0) parts.push(`${warnings} warning${warnings > 1 ? 's' : ''}`);
+
+  const componentSummary = Object.entries(components)
+    .filter(([, v]) => v.issues.length > 0)
+    .map(([tag, v]) => `<${tag}>: ${v.issues.length}`)
+    .join(', ');
+
+  return `${parts.join(', ')} across ${componentsFound.length} component${componentsFound.length > 1 ? 's' : ''}${componentSummary ? ` (${componentSummary})` : ''}.`;
+}

packages/core/src/handlers/css-file-validator.ts

@@ -8,6 +8,7 @@ export * from './bundle.js';
 export * from './cdn.js';
 export * from './cem.js';
 export * from './code-validator.js';
+export * from './css-file-validator.js';
 export * from './color-contrast-checker.js';
 export * from './compare.js';
 export * from './transition-checker.js';

packages/core/src/handlers/index.ts

@@ -29,6 +29,7 @@ import { checkTransitionAnimation } from '../handlers/transition-checker.js';
 import { checkShadowDomJs } from '../handlers/shadow-dom-js-checker.js';
 import { resolveCssApi } from '../handlers/css-api-resolver.js';
 import { runStylingPreflight } from '../handlers/styling-preflight.js';
+import { validateCssFile } from '../handlers/css-file-validator.js';
 import { createErrorResponse, createSuccessResponse } from '../shared/mcp-helpers.js';
 import type { MCPToolResult } from '../shared/mcp-helpers.js';
 import { handleToolError } from '../shared/error-handling.js';
@@ -173,6 +174,10 @@ const StylingPreflightArgsSchema = z.object({
   htmlText: z.string().optional(),
 });
 
+const ValidateCssFileArgsSchema = z.object({
+  cssText: z.string(),
+});
+
 export const STYLING_TOOL_DEFINITIONS = [
   {
     name: 'diagnose_styling',
@@ -824,6 +829,26 @@ export const STYLING_TOOL_DEFINITIONS = [
       required: ['cssText', 'tagName'],
     },
   },
+  {
+    name: 'validate_css_file',
+    description:
+      'Validates an entire CSS file targeting multiple web components in one call. Auto-detects all web component tag names in selectors, runs per-component validation (Shadow DOM, ::part() resolution, token validation, scope checks), and global validation (theme compatibility, color contrast, specificity, shorthand). Returns issues grouped by component plus global issues. Use this when reviewing a CSS file that styles multiple components — no need to know which components are used.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        libraryId: {
+          type: 'string',
+          description:
+            'Optional library ID to target a specific loaded library instead of the default.',
+        },
+        cssText: {
+          type: 'string',
+          description: 'The full CSS file content to validate.',
+        },
+      },
+      required: ['cssText'],
+    },
+  },
 ];
 
 /**
@@ -1017,6 +1042,12 @@ export function handleStylingCall(
       return createSuccessResponse(JSON.stringify(result, null, 2));
     }
 
+    if (name === 'validate_css_file') {
+      const { cssText } = ValidateCssFileArgsSchema.parse(args);
+      const result = validateCssFile(cssText, cem);
+      return createSuccessResponse(JSON.stringify(result, null, 2));
+    }
+
     return createErrorResponse(`Unknown styling tool: ${name}`);
   } catch (err) {
     const mcpErr = handleToolError(err);