@thejaredwilcurt/csslop 0.0.24 → 0.0.26

package/src/rules/optimize.js

@@ -103,6 +103,35 @@ function expandPureNestedRules (rules) {
   return result;
 }
 
+/**
+ * Builds a reusable matcher that expresses child selectors as nested selectors
+ * relative to one parent. The combinator pattern is compiled once per parent so
+ * that testing many children against the same parent does not rebuild it.
+ *
+ * @param  {string}                          parentSelector  The parent selector string.
+ * @return {function(string): (string|null)}                 A matcher returning the nested selector, or null when the child cannot be nested.
+ */
+function createNestedSelectorMatcher (parentSelector) {
+  const parent = parentSelector.trim();
+  // Match a child selector that starts with the parent followed by a combinator (>, +, ~)
+  const combinatorPattern = new RegExp('^' + escapeRegexString(parent) + '\\s*([>+~])\\s*(.+)$');
+
+  return (childSelector) => {
+    const child = childSelector.trim();
+    if (child.startsWith(parent + ':') || child.startsWith(parent + '::')) {
+      return '&' + child.slice(parent.length);
+    }
+    if (child.startsWith(parent + ' ')) {
+      return child.slice(parent.length + 1);
+    }
+    const combinatorMatch = child.match(combinatorPattern);
+    if (combinatorMatch) {
+      return combinatorMatch[1] + combinatorMatch[2];
+    }
+    return null;
+  };
+}
+
 /**
  * Attempts to express a child selector as a nested selector relative to a parent, returning the nested form or null if nesting is not possible.
  *
@@ -111,22 +140,7 @@ function expandPureNestedRules (rules) {
  * @return {string|null}            The nested selector using & syntax, or null if the child cannot be nested under the parent.
  */
 function tryNestSelector (parentSel, childSel) {
-  const parent = parentSel.trim();
-  const child = childSel.trim();
-  if (child.startsWith(parent + ':') || child.startsWith(parent + '::')) {
-    return '&' + child.slice(parent.length);
-  }
-  if (child.startsWith(parent + ' ')) {
-    return child.slice(parent.length + 1);
-  }
-  // Match child selector that starts with the parent followed by a combinator (>, +, ~)
-  const combinatorMatch = child.match(
-    new RegExp('^' + escapeRegexString(parent) + '\\s*([>+~])\\s*(.+)$')
-  );
-  if (combinatorMatch) {
-    return combinatorMatch[1] + combinatorMatch[2];
-  }
-  return null;
+  return createNestedSelectorMatcher(parentSel)(childSel);
 }
 
 /**
@@ -173,6 +187,87 @@ function removeEmptyRules (rules) {
   });
 }
 
+/**
+ * Determines whether a character is CSS whitespace.
+ *
+ * @param  {string}  character  A single character from a selector.
+ * @return {boolean}            Whether the character is whitespace.
+ */
+function isSelectorWhitespace (character) {
+  // Match a single whitespace character
+  return (/\s/).test(character);
+}
+
+/**
+ * Collects every prefix of a child selector that could act as its nesting
+ * parent. A parent always ends immediately before a pseudo-class colon, a
+ * descendant whitespace run, or the whitespace run leading into a combinator,
+ * so only those few positions can start a nestable remainder. Enumerating them
+ * turns "which earlier rule can host this one" into a set of key lookups
+ * instead of a comparison against every preceding rule.
+ *
+ * @param  {string} childSelector  The trimmed child selector.
+ * @return {Set}                   The candidate parent selector strings.
+ */
+function collectCandidateParentSelectors (childSelector) {
+  const candidates = new Set();
+  for (let index = 1; index < childSelector.length; index++) {
+    const character = childSelector[index];
+    if (character === ':' || isSelectorWhitespace(character)) {
+      candidates.add(childSelector.slice(0, index));
+      continue;
+    }
+    if (character !== '>' && character !== '+' && character !== '~') {
+      continue;
+    }
+    // A combinator may be separated from its parent by whitespace, which
+    // belongs to neither side, so the parent ends where that run begins.
+    let boundary = index;
+    while (boundary > 0 && isSelectorWhitespace(childSelector[boundary - 1])) {
+      boundary--;
+    }
+    if (boundary > 0) {
+      candidates.add(childSelector.slice(0, boundary));
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Finds the most recently emitted rule that can host a child selector as a
+ * nested rule, matching the behaviour of scanning backwards through the emitted
+ * rules but only visiting the handful of rules whose selector is a viable
+ * parent prefix.
+ *
+ * @param  {Array}       emittedRules     The rules emitted so far.
+ * @param  {Map}         indexBySelector  Map of each emitted single-selector rule's selector to its index.
+ * @param  {string}      childSelector    The trimmed child selector to nest.
+ * @return {object|null}                  The `parentIndex` and `nestedSelector`, or null when nothing can host the child.
+ */
+function findNestingParent (emittedRules, indexBySelector, childSelector) {
+  const parentIndexes = [];
+  for (const candidateParent of collectCandidateParentSelectors(childSelector)) {
+    const parentIndex = indexBySelector.get(candidateParent);
+    if (parentIndex !== undefined) {
+      parentIndexes.push(parentIndex);
+    }
+  }
+  // The nearest preceding parent wins, exactly as a backwards scan would.
+  parentIndexes.sort((first, second) => {
+    return second - first;
+  });
+  for (const parentIndex of parentIndexes) {
+    const nestedSelector = tryNestSelector(emittedRules[parentIndex].selectors[0], childSelector);
+    if (nestedSelector !== null) {
+      return {
+        nestedSelector,
+        parentIndex
+      };
+    }
+  }
+  return null;
+}
+
 /**
  * Groups flat CSS rules into nested structures where a child selector can be expressed relative to a preceding parent, reducing output size through CSS nesting.
  *
@@ -181,29 +276,22 @@ function removeEmptyRules (rules) {
  */
 function nestFlatRules (rules) {
   const result = [];
+  const indexBySelector = new Map();
   for (const rule of rules) {
     if (rule.type !== 'rule' || rule.selectors?.length !== 1) {
       result.push(rule);
       continue;
     }
     const childSelector = rule.selectors[0].trim();
-    let wasNested = false;
-    for (let j = result.length - 1; j >= 0; j--) {
-      const parentRule = result[j];
-      if (parentRule.type !== 'rule' || parentRule.selectors?.length !== 1) {
-        continue;
-      }
-      const nestedSelector = tryNestSelector(parentRule.selectors[0], childSelector);
-      if (nestedSelector !== null) {
-        parentRule.declarations = parentRule.declarations || [];
-        parentRule.declarations.push({ ...rule, selectors: [nestedSelector] });
-        wasNested = true;
-        break;
-      }
-    }
-    if (!wasNested) {
-      result.push(rule);
+    const nesting = findNestingParent(result, indexBySelector, childSelector);
+    if (nesting) {
+      const parentRule = result[nesting.parentIndex];
+      parentRule.declarations = parentRule.declarations || [];
+      parentRule.declarations.push({ ...rule, selectors: [nesting.nestedSelector] });
+      continue;
     }
+    indexBySelector.set(childSelector, result.length);
+    result.push(rule);
   }
   for (const rule of result) {
     if (rule.type === 'rule' && rule.declarations) {
@@ -277,6 +365,7 @@ function factorCommonParents (rules) {
       continue;
     }
     // Collect the run of consecutive rules that can all nest under the candidate.
+    const matchNestedSelector = createNestedSelectorMatcher(candidateParent);
     const run = [];
     const nestedForms = [];
     let lookahead = index;
@@ -285,7 +374,7 @@ function factorCommonParents (rules) {
       if (sibling.type !== 'rule' || sibling.selectors?.length !== 1) {
         break;
       }
-      const nestedSelector = tryNestSelector(candidateParent, sibling.selectors[0]);
+      const nestedSelector = matchNestedSelector(sibling.selectors[0]);
       if (nestedSelector === null) {
         break;
       }
@@ -745,8 +834,12 @@ function mergeIdenticalNestedRules (rules) {
  * @return {Array}        A new array of rules with same-selector rules combined.
  */
 function mergeSelectorRules (rules) {
-  let result = [];
-  let selectorMap = new Map();
+  // A merged rule moves to the end of the output. Its old slot is emptied
+  // instead of spliced out so that every recorded position stays valid, and the
+  // position map locates that slot without searching the output.
+  const slots = [];
+  const positionByRule = new Map();
+  const selectorMap = new Map();
   for (const rule of rules) {
     if (rule.type === 'rule') {
       const selectorKey = rule.selectors ?
@@ -757,23 +850,26 @@ function mergeSelectorRules (rules) {
       if (selectorKey && selectorMap.has(selectorKey)) {
         const existingRule = selectorMap.get(selectorKey);
         existingRule.declarations.push(...(rule.declarations || []));
-        result = result.filter((candidate) => {
-          return candidate !== existingRule;
-        });
-        result.push(existingRule);
+        slots[positionByRule.get(existingRule)] = null;
+        positionByRule.set(existingRule, slots.length);
+        slots.push(existingRule);
       } else {
         selectorMap.set(selectorKey, rule);
-        result.push(rule);
+        positionByRule.set(rule, slots.length);
+        slots.push(rule);
       }
     } else {
       if (rule.type === 'whitespace') {
         continue;
       }
-      result.push(rule);
+      slots.push(rule);
       selectorMap.clear();
+      positionByRule.clear();
     }
   }
-  return result;
+  return slots.filter((slot) => {
+    return slot !== null;
+  });
 }
 
 /**
@@ -835,6 +931,61 @@ function normalizeSelector (selector) {
     .replace(/::after\b/g, ':after');
 }
 
+/**
+ * Indexes, for every normalized selector in the stylesheet, the last rule that
+ * declares each property under it. Comparing that index against a rule's own
+ * position answers "is this selector's property overridden later" in constant
+ * time, instead of rescanning and renormalizing every following rule.
+ *
+ * @param  {Array} rules  The flat list of AST rule nodes.
+ * @return {Map}          Map of normalized selector to a map of property name to its last declaring rule index.
+ */
+function indexLastDeclaringRuleBySelector (rules) {
+  const lastRuleIndexBySelector = new Map();
+  rules.forEach((rule, ruleIndex) => {
+    if (rule.type !== 'rule' || !rule.selectors) {
+      return;
+    }
+    const declaredProperties = (rule.declarations || []).filter((declaration) => {
+      return declaration.type === 'declaration';
+    }).map((declaration) => {
+      return declaration.property;
+    });
+    if (declaredProperties.length === 0) {
+      return;
+    }
+    for (const selector of rule.selectors) {
+      const normalizedSelector = normalizeSelector(selector);
+      let lastRuleIndexByProperty = lastRuleIndexBySelector.get(normalizedSelector);
+      if (!lastRuleIndexByProperty) {
+        lastRuleIndexByProperty = new Map();
+        lastRuleIndexBySelector.set(normalizedSelector, lastRuleIndexByProperty);
+      }
+      for (const property of declaredProperties) {
+        lastRuleIndexByProperty.set(property, ruleIndex);
+      }
+    }
+  });
+  return lastRuleIndexBySelector;
+}
+
+/**
+ * Checks whether a given selector has a specific property overridden
+ * by any later rule in the stylesheet. A property is considered
+ * overridden if a subsequent rule contains that selector (as its only
+ * selector or among its selectors) and declares the same property.
+ *
+ * @param  {Map}     lastRuleIndexBySelector  The index built by `indexLastDeclaringRuleBySelector`.
+ * @param  {number}  startIndex               The index of the current rule (search starts after this).
+ * @param  {string}  selector                 The normalized selector to check.
+ * @param  {string}  property                 The CSS property name to check.
+ * @return {boolean}                          True if a later rule overrides this selector+property.
+ */
+function isSelectorPropertyOverriddenLater (lastRuleIndexBySelector, startIndex, selector, property) {
+  const lastRuleIndex = lastRuleIndexBySelector.get(selector)?.get(property);
+  return lastRuleIndex !== undefined && lastRuleIndex > startIndex;
+}
+
 /**
  * Removes properties from multi-selector rules when every selector in
  * the rule has that property overridden by a later rule. For example,
@@ -847,6 +998,10 @@ function normalizeSelector (selector) {
  * @return {Array}        The rules with overridden multi-selector properties removed.
  */
 function removeOverriddenMultiSelectorProperties (rules) {
+  // Only rules that follow the one being pruned are ever consulted, and pruning
+  // never adds a declaration, so a single index built up front stays accurate.
+  const lastRuleIndexBySelector = indexLastDeclaringRuleBySelector(rules);
+
   for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex++) {
     const rule = rules[ruleIndex];
     if (rule.type !== 'rule' || !rule.selectors || rule.selectors.length < 2) {
@@ -866,7 +1021,7 @@ function removeOverriddenMultiSelectorProperties (rules) {
     for (const declaration of declarations) {
       const property = declaration.property;
       const allSelectorsOverridden = normalizedSelectors.every((selector) => {
-        return isSelectorPropertyOverriddenLater(rules, ruleIndex, selector, property);
+        return isSelectorPropertyOverriddenLater(lastRuleIndexBySelector, ruleIndex, selector, property);
       });
       if (allSelectorsOverridden) {
         propertiesToRemove.add(property);
@@ -885,41 +1040,6 @@ function removeOverriddenMultiSelectorProperties (rules) {
   return rules;
 }
 
-/**
- * Checks whether a given selector has a specific property overridden
- * by any later rule in the stylesheet. A property is considered
- * overridden if a subsequent rule contains that selector (as its only
- * selector or among its selectors) and declares the same property.
- *
- * @param  {Array}   rules       The full list of AST rule nodes.
- * @param  {number}  startIndex  The index of the current rule (search starts after this).
- * @param  {string}  selector    The normalized selector to check.
- * @param  {string}  property    The CSS property name to check.
- * @return {boolean}             True if a later rule overrides this selector+property.
- */
-function isSelectorPropertyOverriddenLater (rules, startIndex, selector, property) {
-  for (let laterIndex = startIndex + 1; laterIndex < rules.length; laterIndex++) {
-    const laterRule = rules[laterIndex];
-    if (laterRule.type !== 'rule' || !laterRule.selectors) {
-      continue;
-    }
-    const laterSelectors = laterRule.selectors.map(normalizeSelector);
-    if (!laterSelectors.includes(selector)) {
-      continue;
-    }
-    const laterDeclarations = (laterRule.declarations || []).filter((declaration) => {
-      return declaration.type === 'declaration';
-    });
-    const hasOverride = laterDeclarations.some((declaration) => {
-      return declaration.property === property;
-    });
-    if (hasOverride) {
-      return true;
-    }
-  }
-  return false;
-}
-
 export {
   deduplicateKeyframes,
   expandPureNestedRules,

package/src/rules/property.js

@@ -0,0 +1,177 @@
+/**
+ * @file Analyzes `@property` at-rules, resolving each descriptor against the value the CSS engine assumes when the descriptor is absent, so redundant descriptors and pointless registrations can be dropped.
+ */
+
+/**
+ * The descriptors an `@property` rule can declare. Anything else inside the
+ * rule is an unknown descriptor, which the CSS engine discards while parsing.
+ *
+ * @type {Set<string>}
+ */
+const PROPERTY_DESCRIPTORS = new Set([
+  'syntax',
+  'inherits',
+  'initial-value'
+]);
+
+/**
+ * The syntax that accepts any token sequence. It is also the syntax a
+ * registration falls back to when the rule omits the `syntax` descriptor.
+ *
+ * @type {string}
+ */
+const UNIVERSAL_SYNTAX = '*';
+
+/**
+ * The inheritance a registration falls back to when the rule omits the
+ * `inherits` descriptor.
+ *
+ * @type {string}
+ */
+const DEFAULT_INHERITS = 'true';
+
+/**
+ * Reads a descriptor value the way the CSS engine compares it, ignoring the
+ * whitespace that surrounds the value.
+ *
+ * @param  {object} declaration  The descriptor declaration node.
+ * @return {string}              The descriptor value without surrounding whitespace.
+ */
+function readDescriptorValue (declaration) {
+  return String(declaration.value ?? '').trim();
+}
+
+/**
+ * Reads a `syntax` descriptor as the syntax it describes, rather than as the
+ * string it is written as, so it can be compared against the universal syntax.
+ *
+ * @param  {string} syntaxValue  The raw `syntax` descriptor value, such as `"<length>"`.
+ * @return {string}              The described syntax, such as `<length>`.
+ */
+function unquoteSyntax (syntaxValue) {
+  // A value wrapped in a matching pair of quotes, capturing the string contents
+  const quotedStringPattern = /^(["'])([\s\S]*)\1$/;
+  const quotedString = syntaxValue.match(quotedStringPattern);
+  if (quotedString) {
+    return quotedString[2].trim();
+  }
+  return syntaxValue;
+}
+
+/**
+ * Collects the descriptors an `@property` rule declares, keyed by descriptor
+ * name and ordered by first appearance. Unknown descriptors are left out
+ * because the CSS engine ignores them, and a descriptor declared more than
+ * once resolves to its final declaration, which is the one the engine keeps.
+ *
+ * @param  {object} rule  The `@property` AST rule node.
+ * @return {Map}          Descriptor names mapped to the declaration that wins.
+ */
+function collectPropertyDescriptors (rule) {
+  const descriptors = new Map();
+  for (const declaration of rule.declarations || []) {
+    const descriptorName = String(declaration.property ?? '').toLowerCase();
+    const isKnownDescriptor = (
+      declaration.type === 'declaration' &&
+      PROPERTY_DESCRIPTORS.has(descriptorName)
+    );
+    if (isKnownDescriptor) {
+      descriptors.set(descriptorName, declaration);
+    }
+  }
+  return descriptors;
+}
+
+/**
+ * Resolves the syntax a set of descriptors registers, falling back to the
+ * universal syntax when the `syntax` descriptor is absent.
+ *
+ * @param  {Map}    descriptors  Descriptor names mapped to their declarations.
+ * @return {string}              The registered syntax.
+ */
+function resolveRegisteredSyntax (descriptors) {
+  const syntaxDeclaration = descriptors.get('syntax');
+  if (!syntaxDeclaration) {
+    return UNIVERSAL_SYNTAX;
+  }
+  return unquoteSyntax(readDescriptorValue(syntaxDeclaration));
+}
+
+/**
+ * Reports whether the CSS engine accepts the registration a set of descriptors
+ * describes. Registering anything narrower than the universal syntax requires
+ * an `initial-value`, since the engine has no valid value to start from
+ * otherwise, and a registration it rejects has no effect on the stylesheet.
+ *
+ * @param  {Map}     descriptors  Descriptor names mapped to their declarations.
+ * @return {boolean}              True when the registration is valid.
+ */
+function isValidRegistration (descriptors) {
+  if (resolveRegisteredSyntax(descriptors) === UNIVERSAL_SYNTAX) {
+    return true;
+  }
+  return descriptors.has('initial-value');
+}
+
+/**
+ * Reports whether a descriptor declares exactly what the CSS engine already
+ * assumes, which makes writing the descriptor out pointless. An
+ * `initial-value` always says something, because the value it defaults to is
+ * the guaranteed-invalid value, which no declaration can spell out.
+ *
+ * @param  {string}  descriptorName  The lowercased descriptor name.
+ * @param  {object}  declaration     The descriptor declaration node.
+ * @return {boolean}                 True when the descriptor restates a default.
+ */
+function isDefaultDescriptor (descriptorName, declaration) {
+  const value = readDescriptorValue(declaration);
+  if (descriptorName === 'syntax') {
+    return unquoteSyntax(value) === UNIVERSAL_SYNTAX;
+  }
+  if (descriptorName === 'inherits') {
+    return value.toLowerCase() === DEFAULT_INHERITS;
+  }
+  return false;
+}
+
+/**
+ * Reduces an `@property` rule to the descriptors worth writing out, meaning
+ * the ones that describe something other than what the CSS engine assumes on
+ * its own. An empty result means the entire rule can be dropped, either
+ * because the engine rejects the registration or because the registration
+ * matches an unregistered custom property in every way.
+ *
+ * @param  {object} rule  The `@property` AST rule node.
+ * @return {Array}        The descriptor declarations to render.
+ */
+function resolvePropertyDescriptors (rule) {
+  const descriptors = collectPropertyDescriptors(rule);
+  if (!isValidRegistration(descriptors)) {
+    return [];
+  }
+  const meaningfulDescriptors = [];
+  for (const [descriptorName, declaration] of descriptors) {
+    if (!isDefaultDescriptor(descriptorName, declaration)) {
+      meaningfulDescriptors.push(declaration);
+    }
+  }
+  return meaningfulDescriptors;
+}
+
+/**
+ * Reports whether an `@property` rule survives minification, which is also
+ * what decides whether the rest of the stylesheet may rely on the custom
+ * property being registered. Rules that describe nothing beyond the defaults
+ * leave the custom property just as unregistered as never mentioning it.
+ *
+ * @param  {object}  rule  The `@property` AST rule node.
+ * @return {boolean}       True when the rule registers the custom property.
+ */
+function registersCustomProperty (rule) {
+  return resolvePropertyDescriptors(rule).length > 0;
+}
+
+export {
+  registersCustomProperty,
+  resolvePropertyDescriptors
+};

package/src/rules/stringify.js

@@ -17,6 +17,7 @@ import {
   unescapeIdent,
   unescapeSelector
 } from './normalize.js';
+import { resolvePropertyDescriptors } from './property.js';
 import {
   flattenNestingParentIsSelector,
   mergeAdjacentWherePseudoClasses,
@@ -41,6 +42,14 @@ function stringifyDeclarations (declarations) {
     .join(';');
 }
 
+/**
+ * The heading element selectors, which collapse into the `:heading`
+ * pseudo-class when a rule targets every one of them.
+ *
+ * @type {Set<string>}
+ */
+const HEADING_SELECTORS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+
 /**
  * Matches a complete `@layer` statement, which declares layer names without a
  * block and ends with the semicolon that separates it from the CSS that follows
@@ -263,12 +272,11 @@ function stringifyRule (rule, context) {
       }
       uniqueSelectors = uniqueSelectors.flatMap(processIsSelector);
       uniqueSelectors = [...new Set(uniqueSelectors)];
-      const headingSet = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
       const isAllHeadings = (
-        rule.selectors.length === 6 &&
-        uniqueSelectors.length === 6 &&
+        rule.selectors.length === HEADING_SELECTORS.size &&
+        uniqueSelectors.length === HEADING_SELECTORS.size &&
         uniqueSelectors.every((selector) => {
-          return headingSet.has(selector);
+          return HEADING_SELECTORS.has(selector);
         })
       );
       if (isAllHeadings) {
@@ -511,32 +519,7 @@ function stringifyRule (rule, context) {
   }
 
   if (rule.type === 'property') {
-    const propertyDeclarations = (rule.declarations || []).filter((declaration) => {
-      return declaration.type === 'declaration' && declaration.property;
-    });
-    const hasSyntaxDescriptor = propertyDeclarations.some((declaration) => {
-      return declaration.property === 'syntax';
-    });
-    const hasInheritsDescriptor = propertyDeclarations.some((declaration) => {
-      return declaration.property === 'inherits';
-    });
-    if (!hasSyntaxDescriptor || !hasInheritsDescriptor) {
-      return '';
-    }
-
-    const syntaxDeclaration = propertyDeclarations.find((declaration) => {
-      return declaration.property === 'syntax';
-    });
-    const syntaxValue = (syntaxDeclaration.value || '').replace(/["']/g, '').trim();
-    const isUniversalSyntax = syntaxValue === '*';
-    const hasInitialValue = propertyDeclarations.some((declaration) => {
-      return declaration.property === 'initial-value';
-    });
-    if (!isUniversalSyntax && !hasInitialValue) {
-      return '';
-    }
-
-    let renderedDeclarations = stringifyDeclarations(rule.declarations || []);
+    const renderedDeclarations = stringifyDeclarations(resolvePropertyDescriptors(rule));
     if (!renderedDeclarations) {
       return '';
     }