feat: Add location information to pseudo-class and pseudo-element error messages

This commit enhances error messages for unknown pseudo-classes and pseudo-elements by including the CSS Level or CSS Module where they are defined. Key changes:

- Created `PseudoLocationIndex` interface to map pseudo-classes and pseudo-elements to their sources
- Implemented `buildPseudoLocationIndex()` to pre-build an index of locations
- Updated error handling in parser to include location information
- Added test cases to verify the new error message functionality

The changes provide more informative error messages, helping developers quickly identify where a specific pseudo-class or pseudo-element is defined.

Author: mdevils

src/parser.ts

@@ -29,7 +29,8 @@ import {
     getXmlOptions,
     SyntaxDefinition,
     CssModule,
-    cssModules
+    cssModules,
+    pseudoLocationIndex
 } from './syntax-definitions.js';
 import {digitsChars, isHex, isIdent, isIdentStart, maxHexLength, quoteChars, whitespaceChars} from './utils.js';
 
@@ -764,12 +765,23 @@ export function createParser(
                 assert(isDoubleColon || pseudoName, 'Expected pseudo-class name.');
                 assert(!isDoubleColon || pseudoName, 'Expected pseudo-element name.');
                 assert(pseudoName, 'Expected pseudo-class name.');
-                assert(
+                if (
                     !isDoubleColon ||
-                        pseudoElementsAcceptUnknown ||
-                        Object.prototype.hasOwnProperty.call(pseudoElementsDefinitions, pseudoName),
-                    `Unknown pseudo-element "${pseudoName}".`
-                );
+                    pseudoElementsAcceptUnknown ||
+                    Object.prototype.hasOwnProperty.call(pseudoElementsDefinitions, pseudoName)
+                ) {
+                    // All good
+                } else {
+                    // Generate a helpful error message with location information
+                    const locations = pseudoLocationIndex.pseudoElements[pseudoName];
+                    let errorMessage = `Unknown pseudo-element "${pseudoName}"`;
+                    
+                    if (locations && locations.length > 0) {
+                        errorMessage += `. It is defined in: ${locations.join(', ')}`;
+                    }
+                    
+                    fail(errorMessage + '.');
+                }
 
                 isPseudoElement =
                     pseudoElementsEnabled &&
@@ -800,7 +812,19 @@ export function createParser(
                     assert(pseudoClassesEnabled, 'Pseudo-classes are not enabled.');
                     const signature =
                         pseudoClassesDefinitions[pseudoName] ?? (pseudoClassesAcceptUnknown && defaultPseudoSignature);
-                    assert(signature, `Unknown pseudo-class: "${pseudoName}".`);
+                    if (signature) {
+                        // All good
+                    } else {
+                        // Generate a helpful error message with location information
+                        const locations = pseudoLocationIndex.pseudoClasses[pseudoName];
+                        let errorMessage = `Unknown pseudo-class: "${pseudoName}"`;
+                        
+                        if (locations && locations.length > 0) {
+                            errorMessage += `. It is defined in: ${locations.join(', ')}`;
+                        }
+                        
+                        fail(errorMessage + '.');
+                    }
 
                     const argument = parsePseudoArgument(pseudoName, 'pseudo-class', signature);
                     const pseudoClass: AstPseudoClass = {

src/syntax-definitions.ts

@@ -502,6 +502,130 @@ export const cssModules = {
  */
 export type CssModule = keyof typeof cssModules;
 
+/**
+ * Maps pseudo-classes and pseudo-elements to their CSS Level or CSS Module
+ */
+export interface PseudoLocationIndex {
+    pseudoClasses: Record<string, string[]>;
+    pseudoElements: Record<string, string[]>;
+}
+
+/**
+ * Builds an index of where each pseudo-class and pseudo-element is defined
+ * (in which CSS Level or CSS Module)
+ */
+export function buildPseudoLocationIndex(): PseudoLocationIndex {
+    const index: PseudoLocationIndex = {
+        pseudoClasses: {},
+        pseudoElements: {}
+    };
+    
+    // Add CSS Levels (excluding 'latest' and 'progressive')
+    const cssLevels: CssLevel[] = ['css1', 'css2', 'css3', 'selectors-3', 'selectors-4'];
+    
+    for (const level of cssLevels) {
+        const syntax = cssSyntaxDefinitions[level];
+        
+        // Process pseudo-classes
+        if (syntax.pseudoClasses && typeof syntax.pseudoClasses === 'object') {
+            const { definitions } = syntax.pseudoClasses;
+            if (definitions) {
+                for (const [type, names] of Object.entries(definitions)) {
+                    for (const name of names) {
+                        if (!index.pseudoClasses[name]) {
+                            index.pseudoClasses[name] = [];
+                        }
+                        if (!index.pseudoClasses[name].includes(level)) {
+                            index.pseudoClasses[name].push(level);
+                        }
+                    }
+                }
+            }
+        }
+        
+        // Process pseudo-elements
+        if (syntax.pseudoElements && typeof syntax.pseudoElements === 'object') {
+            const { definitions } = syntax.pseudoElements;
+            if (definitions) {
+                if (Array.isArray(definitions)) {
+                    for (const name of definitions) {
+                        if (!index.pseudoElements[name]) {
+                            index.pseudoElements[name] = [];
+                        }
+                        if (!index.pseudoElements[name].includes(level)) {
+                            index.pseudoElements[name].push(level);
+                        }
+                    }
+                } else {
+                    for (const [type, names] of Object.entries(definitions)) {
+                        for (const name of names) {
+                            if (!index.pseudoElements[name]) {
+                                index.pseudoElements[name] = [];
+                            }
+                            if (!index.pseudoElements[name].includes(level)) {
+                                index.pseudoElements[name].push(level);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    // Add CSS Modules
+    for (const [moduleName, moduleSyntax] of Object.entries(cssModules)) {
+        // Process pseudo-classes
+        if (moduleSyntax.pseudoClasses && typeof moduleSyntax.pseudoClasses === 'object') {
+            const { definitions } = moduleSyntax.pseudoClasses;
+            if (definitions) {
+                for (const [type, names] of Object.entries(definitions)) {
+                    for (const name of names) {
+                        if (!index.pseudoClasses[name]) {
+                            index.pseudoClasses[name] = [];
+                        }
+                        if (!index.pseudoClasses[name].includes(moduleName)) {
+                            index.pseudoClasses[name].push(moduleName);
+                        }
+                    }
+                }
+            }
+        }
+        
+        // Process pseudo-elements
+        if (moduleSyntax.pseudoElements && typeof moduleSyntax.pseudoElements === 'object') {
+            const { definitions } = moduleSyntax.pseudoElements;
+            if (definitions) {
+                if (Array.isArray(definitions)) {
+                    for (const name of definitions) {
+                        if (!index.pseudoElements[name]) {
+                            index.pseudoElements[name] = [];
+                        }
+                        if (!index.pseudoElements[name].includes(moduleName)) {
+                            index.pseudoElements[name].push(moduleName);
+                        }
+                    }
+                } else {
+                    for (const [type, names] of Object.entries(definitions)) {
+                        for (const name of names) {
+                            if (!index.pseudoElements[name]) {
+                                index.pseudoElements[name] = [];
+                            }
+                            if (!index.pseudoElements[name].includes(moduleName)) {
+                                index.pseudoElements[name].push(moduleName);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    return index;
+}
+
+// Pre-build the index for faster lookup
+export const pseudoLocationIndex = buildPseudoLocationIndex();
+
 const latestSyntaxDefinition = {
     ...selectors4SyntaxDefinition,
     modules: (Object.entries(cssModules) as [CssModule, SyntaxDefinition & {latest?: boolean}][])

test/modules.test.ts

@@ -713,5 +713,45 @@ describe('CSS Modules', () => {
                 })
             );
         });
+        
+        it('should provide helpful error messages with location information', () => {
+            const parse = createParser({
+                syntax: {
+                    pseudoClasses: {
+                        unknown: 'reject'
+                    },
+                    pseudoElements: {
+                        unknown: 'reject'
+                    }
+                }
+            });
+            
+            // Test for pseudo-class defined in a CSS module
+            try {
+                parse(':sticky');
+                fail('Should have thrown an error');
+            } catch (e) {
+                expect(e.message).toContain('Unknown pseudo-class: "sticky"');
+                expect(e.message).toContain('css-position-3');
+            }
+            
+            // Test for pseudo-element defined in a CSS module
+            try {
+                parse('::part(button)');
+                fail('Should have thrown an error');
+            } catch (e) {
+                expect(e.message).toContain('Unknown pseudo-element "part"');
+                expect(e.message).toContain('css-shadow-parts-1');
+            }
+            
+            // Test for pseudo-class defined in a CSS level
+            try {
+                parse(':focus-visible');
+                fail('Should have thrown an error');
+            } catch (e) {
+                expect(e.message).toContain('Unknown pseudo-class: "focus-visible"');
+                expect(e.message).toContain('selectors-4');
+            }
+        });
     });
 });