@thejaredwilcurt/csslop 0.0.49 → 0.0.51

package/src/rules/optimize/prune-overridden.js

@@ -0,0 +1,267 @@
+/**
+ * @file Removes the selectors and declarations of multi-selector rules that later rules override in full, since they no longer decide anything.
+ */
+
+import {
+  expandToOverridableProperties,
+  isImportantDeclaration
+} from './declaration-writes.js';
+import { normalizeSelector } from './selector-normalization.js';
+
+/**
+ * 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;
+}
+
+/**
+ * Indexes, for every normalized selector in the stylesheet, the last rule that
+ * covers each leaf property under it, where coverage follows the same "writes
+ * to" model as `expandToOverridableProperties` (a later `border` declaration
+ * on the same selector also overrides an earlier `border-color` on it), along
+ * with whether that covering declaration is important. A last-covering entry
+ * is consulted to answer "is every declaration this selector still gets from
+ * the rule at position X re-declared later".
+ *
+ * @param  {Array} rules  The flat list of AST rule nodes.
+ * @return {Map}          Map of normalized selector to a map of covered leaf property name to `{ ruleIndex, important }`.
+ */
+function indexFinalCoveringRuleBySelector (rules) {
+  const coverageBySelector = new Map();
+  rules.forEach((rule, ruleIndex) => {
+    if (rule.type !== 'rule' || !rule.selectors?.length) {
+      return;
+    }
+    const declarations = (rule.declarations || []).filter((declaration) => {
+      return declaration.type === 'declaration' && declaration.property;
+    });
+    if (!declarations.length) {
+      return;
+    }
+    for (const selector of rule.selectors) {
+      const normalizedSelector = normalizeSelector(selector);
+      let coverageByProperty = coverageBySelector.get(normalizedSelector);
+      if (!coverageByProperty) {
+        coverageByProperty = new Map();
+        coverageBySelector.set(normalizedSelector, coverageByProperty);
+      }
+      for (const declaration of declarations) {
+        const important = isImportantDeclaration(declaration);
+        for (const leafProperty of expandToOverridableProperties(declaration.property)) {
+          coverageByProperty.set(leafProperty, { important, ruleIndex });
+        }
+      }
+    }
+  });
+  return coverageBySelector;
+}
+
+/**
+ * Determines whether a later rule overrides every leaf property an earlier
+ * declaration writes to for the same selector, including via shorthand
+ * coverage, with an important earlier write requiring an important later
+ * write to beat it.
+ *
+ * @param  {Map}     coverageByProperty      The leaf property coverage index for the selector.
+ * @param  {object}  declaration             The earlier declaration to test.
+ * @param  {number}  ruleIndex               The position of the rule holding the declaration.
+ * @param  {boolean} declarationIsImportant  Whether the earlier write of this property is important.
+ * @return {boolean}                         True when the declaration is conclusively overridden later.
+ */
+function isDeclarationOverriddenLater (coverageByProperty, declaration, ruleIndex, declarationIsImportant) {
+  for (const leafProperty of expandToOverridableProperties(declaration.property)) {
+    const coverage = coverageByProperty.get(leafProperty);
+    if (!coverage || coverage.ruleIndex <= ruleIndex) {
+      return false;
+    }
+    // An important declaration outlives a later non-important one
+    if (declarationIsImportant && !coverage.important) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Removes a selector from a multi-selector rule's list when every declaration
+ * the rule would still give that selector is overridden by a later rule that
+ * contains the same selector. For example, if `h1,h2{color:red}` is followed
+ * by `h2{color:tan}`, the `h2` entry contributes nothing and can be dropped,
+ * leaving `h1{color:red}`. If the list empties out entirely, the rule is
+ * stripped of declarations so `removeEmptyRules` discards it.
+ *
+ * @param  {Array} rules  The flat list of AST rule nodes.
+ * @return {Array}        The rules with fully overridden selectors removed from their lists.
+ */
+function removeFullyOverriddenSelectors (rules) {
+  // Pruning a selector only ever shrinks lists: a covering entry that wins
+  // today is supplied by a later rule, and pruning earlier rules never moves
+  // coverage forward, so a single index built up front stays accurate.
+  const coverageBySelector = indexFinalCoveringRuleBySelector(rules);
+
+  for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex++) {
+    const rule = rules[ruleIndex];
+    if (rule.type !== 'rule' || !rule.selectors || rule.selectors.length < 2) {
+      continue;
+    }
+    const entries = rule.declarations || [];
+    // Removing a selector would also un-scope nested rules, which may depend
+    // on it, so only rules made purely of declarations qualify
+    const hasNestedContent = entries.some((entry) => {
+      return entry.type !== 'declaration' && entry.type !== 'whitespace' && entry.type !== 'comment';
+    });
+    if (hasNestedContent) {
+      continue;
+    }
+    const declarations = entries.filter((entry) => {
+      return entry.type === 'declaration' && entry.property;
+    });
+    if (!declarations.length) {
+      continue;
+    }
+    // Within a rule, any important declaration of a property makes the rule's
+    // write of that property important (a conservative stand-in for tracking
+    // which of several same-property declarations survives inside the rule)
+    const importantByProperty = new Map();
+    for (const declaration of declarations) {
+      if (isImportantDeclaration(declaration)) {
+        importantByProperty.set(declaration.property, true);
+      } else if (!importantByProperty.has(declaration.property)) {
+        importantByProperty.set(declaration.property, false);
+      }
+    }
+    const keptSelectors = rule.selectors.filter((selector) => {
+      const coverageByProperty = coverageBySelector.get(normalizeSelector(selector));
+      if (!coverageByProperty) {
+        return true;
+      }
+      // Keep the selector while at least one declaration is not conclusively
+      // overridden for it by a later rule
+      return declarations.some((declaration) => {
+        return !isDeclarationOverriddenLater(
+          coverageByProperty,
+          declaration,
+          ruleIndex,
+          importantByProperty.get(declaration.property)
+        );
+      });
+    });
+    if (keptSelectors.length !== rule.selectors.length) {
+      if (!keptSelectors.length) {
+        rule.declarations = entries.filter((entry) => {
+          return entry.type !== 'declaration';
+        });
+      }
+      rule.selectors = keptSelectors;
+    }
+  }
+  return rules;
+}
+
+/**
+ * Removes properties from multi-selector rules when every selector in
+ * the rule has that property overridden by a later rule. For example,
+ * if `h1,h2{color:red}` is followed by `h1{color:blue}` and
+ * `h2{color:green}`, the `color` in the first rule is redundant and
+ * can be removed. If all properties are removed, the empty rule will
+ * be cleaned up by `removeEmptyRules`.
+ *
+ * @param  {Array} rules  The flat list of AST rule nodes.
+ * @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) {
+      continue;
+    }
+    const normalizedSelectors = rule.selectors.map(normalizeSelector);
+    const declarations = (rule.declarations || []).filter((declaration) => {
+      return declaration.type === 'declaration';
+    });
+    if (declarations.length === 0) {
+      continue;
+    }
+
+    // For each property in this multi-selector rule, check if ALL selectors
+    // get that property overridden in later rules
+    const propertiesToRemove = new Set();
+    for (const declaration of declarations) {
+      const property = declaration.property;
+      const allSelectorsOverridden = normalizedSelectors.every((selector) => {
+        return isSelectorPropertyOverriddenLater(lastRuleIndexBySelector, ruleIndex, selector, property);
+      });
+      if (allSelectorsOverridden) {
+        propertiesToRemove.add(property);
+      }
+    }
+
+    if (propertiesToRemove.size > 0) {
+      rule.declarations = (rule.declarations || []).filter((declaration) => {
+        if (declaration.type !== 'declaration') {
+          return true;
+        }
+        return !propertiesToRemove.has(declaration.property);
+      });
+    }
+  }
+  return rules;
+}
+
+export {
+  removeFullyOverriddenSelectors,
+  removeOverriddenMultiSelectorProperties
+};

package/src/rules/optimize/selector-normalization.js

@@ -0,0 +1,60 @@
+/**
+ * @file Normalizes selectors into one comparable spelling, memoized per stylesheet, so rules that select the same elements are recognized as such.
+ */
+
+/**
+ * Memoizes the normalized form of each selector seen during the current
+ * stylesheet.
+ *
+ * @type {Map<string, string>}
+ */
+const normalizedSelectorCache = new Map();
+
+/**
+ * Discards every memoized normalized selector. The minifier calls this around
+ * each stylesheet, so the cache does not outlive the pass that filled it.
+ */
+function clearNormalizedSelectorCache () {
+  normalizedSelectorCache.clear();
+}
+
+/**
+ * Normalizes a selector string for consistent comparison by trimming
+ * and collapsing internal whitespace.
+ *
+ * @param  {string} selector  The raw selector string.
+ * @return {string}           The normalized selector.
+ */
+function computeNormalizedSelector (selector) {
+  // Collapse each whitespace run into a single space
+  const normalized = selector.trim().replace(/\s+/g, ' ');
+  if (!normalized.includes('::')) {
+    return normalized;
+  }
+  return normalized
+    // Convert double-colon ::before/::after to single-colon legacy form
+    .replace(/::before\b/g, ':before')
+    .replace(/::after\b/g, ':after');
+}
+
+/**
+ * Normalizes a selector string for consistent comparison, reusing the result
+ * when the same selector was already normalized during this stylesheet. Every
+ * merge pass compares the same selectors again, so each is only rewritten once.
+ *
+ * @param  {string} selector  The raw selector string.
+ * @return {string}           The normalized selector.
+ */
+function normalizeSelector (selector) {
+  let normalized = normalizedSelectorCache.get(selector);
+  if (normalized === undefined) {
+    normalized = computeNormalizedSelector(selector);
+    normalizedSelectorCache.set(selector, normalized);
+  }
+  return normalized;
+}
+
+export {
+  clearNormalizedSelectorCache,
+  normalizeSelector
+};

package/src/rules/optimize/specificity.js

@@ -0,0 +1,280 @@
+/**
+ * @file Measures the specificity of selectors and selector lists, so rules can be regrouped and reordered without changing which declaration wins the cascade.
+ */
+
+import {
+  findMatchingBracket,
+  findMatchingParenthesis,
+  splitTopLevelCommaList
+} from '../../parser/source-search.js';
+
+/**
+ * Advances past a CSS identifier (name) starting at the given index.
+ *
+ * @param  {string} text   The selector text.
+ * @param  {number} start  The index to start scanning from.
+ * @return {number}        The index just after the identifier.
+ */
+function skipSelectorName (text, start) {
+  let index = start;
+  // Advance over identifier characters (letters, digits, hyphen, underscore)
+  while (index < text.length && isSelectorNameCharacter(text.charCodeAt(index))) {
+    index++;
+  }
+  return index;
+}
+
+/**
+ * Reports whether a character code is an ASCII letter.
+ *
+ * @param  {number}  characterCode  The UTF-16 code unit of the character.
+ * @return {boolean}                True for `a`-`z` and `A`-`Z`.
+ */
+function isAsciiLetter (characterCode) {
+  return (
+    (characterCode >= 97 && characterCode <= 122) ||
+    (characterCode >= 65 && characterCode <= 90)
+  );
+}
+
+/**
+ * Reports whether a character code can appear in a selector name, which here
+ * means an ASCII letter, digit, hyphen, or underscore. Comparing character
+ * codes avoids running a regular expression once per character.
+ *
+ * @param  {number}  characterCode  The UTF-16 code unit of the character.
+ * @return {boolean}                True when the character continues a name.
+ */
+function isSelectorNameCharacter (characterCode) {
+  const isDigit = characterCode >= 48 && characterCode <= 57;
+  const isHyphen = characterCode === 45;
+  const isUnderscore = characterCode === 95;
+  return isAsciiLetter(characterCode) || isDigit || isHyphen || isUnderscore;
+}
+
+/**
+ * Compares two specificity tuples [ids, classes, types] lexicographically.
+ *
+ * @param  {Array}  first   The first specificity tuple.
+ * @param  {Array}  second  The second specificity tuple.
+ * @return {number}         Negative, zero, or positive per standard comparison.
+ */
+function compareSpecificity (first, second) {
+  for (let index = 0; index < 3; index++) {
+    if (first[index] !== second[index]) {
+      return first[index] - second[index];
+    }
+  }
+  return 0;
+}
+
+/**
+ * Computes the CSS specificity of a single complex selector as an
+ * [ids, classes, types] tuple. The nesting selector `&` is ignored because its
+ * contribution comes from the shared parent when comparing sibling selectors.
+ * Functional pseudo-classes `:is()`, `:not()`, `:has()`, and `:matches()` add
+ * the maximum specificity of their arguments; `:where()` adds nothing.
+ *
+ * @param  {string} selector  A single complex selector string.
+ * @return {Array}            The [ids, classes, types] specificity tuple.
+ */
+function computeSpecificity (selector) {
+  const specificity = [0, 0, 0];
+  const text = selector.trim();
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (character === '#') {
+      specificity[0]++;
+      index = skipSelectorName(text, index + 1);
+    } else if (character === '.') {
+      specificity[1]++;
+      index = skipSelectorName(text, index + 1);
+    } else if (character === '[') {
+      specificity[1]++;
+      // An attribute selector that never closes runs to the end of the selector
+      const closeBracketIndex = findMatchingBracket(text, index);
+      index = closeBracketIndex === -1 ? text.length : closeBracketIndex + 1;
+    } else if (character === ':') {
+      if (text[index + 1] === ':') {
+        specificity[2]++;
+        index = skipSelectorName(text, index + 2);
+      } else {
+        const nameStart = index + 1;
+        const nameEnd = skipSelectorName(text, nameStart);
+        const name = text.slice(nameStart, nameEnd).toLowerCase();
+        if (text[nameEnd] === '(') {
+          // An argument list that never closes runs to the end of the selector
+          const closeIndex = findMatchingParenthesis(text, nameEnd);
+          const argumentsEnd = closeIndex === -1 ? text.length : closeIndex;
+          const inner = text.slice(nameEnd + 1, argumentsEnd);
+          if (name === 'where') {
+            // :where() contributes zero specificity
+          } else if (name === 'is' || name === 'not' || name === 'has' || name === 'matches') {
+            const innerMax = maxSelectorSpecificity(inner);
+            specificity[0] += innerMax[0];
+            specificity[1] += innerMax[1];
+            specificity[2] += innerMax[2];
+          } else {
+            specificity[1]++;
+          }
+          index = argumentsEnd + 1;
+        } else {
+          // Legacy single-colon pseudo-elements count as pseudo-elements
+          if (name === 'before' || name === 'after' || name === 'first-line' || name === 'first-letter') {
+            specificity[2]++;
+          } else {
+            specificity[1]++;
+          }
+          index = nameEnd;
+        }
+      }
+    } else if (character === '*' || character === '&') {
+      // Universal selector and nesting selector add no counted specificity here
+      index++;
+    } else if (isAsciiLetter(text.charCodeAt(index))) {
+      specificity[2]++;
+      index = skipSelectorName(text, index);
+    } else {
+      // Combinators and whitespace do not affect specificity
+      index++;
+    }
+  }
+  return specificity;
+}
+
+/**
+ * Memoizes the strongest and weakest specificity of each selector list seen
+ * during the current stylesheet. The same rules are measured again on every
+ * merge pass, and a selector list always has the same specificity, so each
+ * distinct list is only split and scanned once per stylesheet.
+ *
+ * @type {Map<string, {strongest: Array, weakest: Array}>}
+ */
+const specificityRangeCache = new Map();
+
+/**
+ * Discards every memoized specificity range. The minifier calls this around
+ * each stylesheet, so the cache does not outlive the pass that filled it.
+ */
+function clearSpecificityCache () {
+  specificityRangeCache.clear();
+}
+
+/**
+ * Scans every selector of a comma-separated list for the strongest and the
+ * weakest specificity among them. The returned tuples are frozen because they
+ * are shared by everything that asks about the same list.
+ *
+ * @param  {string} selectorList  The selector list string.
+ * @return {object}               The `strongest` and `weakest` [ids, classes, types] tuples.
+ */
+function computeSpecificityRange (selectorList) {
+  let strongest = [0, 0, 0];
+  let weakest = null;
+  for (const selector of splitTopLevelCommaList(selectorList)) {
+    const specificity = computeSpecificity(selector);
+    if (compareSpecificity(specificity, strongest) > 0) {
+      strongest = specificity;
+    }
+    if (!weakest || compareSpecificity(specificity, weakest) < 0) {
+      weakest = specificity;
+    }
+  }
+  return {
+    strongest: Object.freeze(strongest),
+    weakest: Object.freeze(weakest || [0, 0, 0])
+  };
+}
+
+/**
+ * Returns the strongest and weakest specificity of a selector list, measuring
+ * it the first time it is asked about.
+ *
+ * @param  {string} selectorList  The selector list string.
+ * @return {object}               The `strongest` and `weakest` [ids, classes, types] tuples.
+ */
+function getSpecificityRange (selectorList) {
+  let range = specificityRangeCache.get(selectorList);
+  if (!range) {
+    range = computeSpecificityRange(selectorList);
+    specificityRangeCache.set(selectorList, range);
+  }
+  return range;
+}
+
+/**
+ * Returns the maximum specificity tuple across a comma-separated selector list,
+ * matching how a comma-separated group behaves as `:is()`.
+ *
+ * @param  {string} selectorList  The selector list string.
+ * @return {Array}                The maximum [ids, classes, types] tuple.
+ */
+function maxSelectorSpecificity (selectorList) {
+  return getSpecificityRange(selectorList).strongest;
+}
+
+/**
+ * Returns the strongest specificity a rule can match with, which is the highest
+ * of its individual selectors.
+ *
+ * @param  {Array} selectors  The rule's selector strings.
+ * @return {Array}            The [ids, classes, types] specificity tuple.
+ */
+function maximumRuleSpecificity (selectors) {
+  return maxSelectorSpecificity((selectors || []).join(','));
+}
+
+/**
+ * Returns the weakest specificity a rule's declarations are applied with. Every
+ * selector of a top-level rule applies the same declarations under its own
+ * specificity, so the weakest selector decides whether another rule is able to
+ * override the rule as a whole.
+ *
+ * @param  {Array} selectors  The rule's selector strings.
+ * @return {Array}            The [ids, classes, types] specificity tuple.
+ */
+function minimumRuleSpecificity (selectors) {
+  return getSpecificityRange((selectors || []).join(',')).weakest;
+}
+
+/**
+ * Adds two specificity tuples together, which is how a nested selector combines
+ * with the parent selector it only ever matches through.
+ *
+ * @param  {Array} first   The first [ids, classes, types] tuple.
+ * @param  {Array} second  The second [ids, classes, types] tuple.
+ * @return {Array}         The summed specificity tuple.
+ */
+function addSpecificity (first, second) {
+  return [
+    first[0] + second[0],
+    first[1] + second[1],
+    first[2] + second[2]
+  ];
+}
+
+/**
+ * Reports whether a rule that nests blocks may take on further selectors. A
+ * nested selector resolves against its parent's whole selector list as `:is()`,
+ * which matches with the specificity of the strongest selector in that list, so
+ * the list may only grow while every selector in it weighs the same.
+ *
+ * @param  {Array}   selectors  The selector list the merged rule would carry.
+ * @return {boolean}            Whether the nested blocks keep their current weight.
+ */
+function selectorsShareSpecificity (selectors) {
+  const strongest = maximumRuleSpecificity(selectors);
+  const weakest = minimumRuleSpecificity(selectors);
+  return compareSpecificity(strongest, weakest) === 0;
+}
+
+export {
+  addSpecificity,
+  clearSpecificityCache,
+  compareSpecificity,
+  maximumRuleSpecificity,
+  maxSelectorSpecificity,
+  minimumRuleSpecificity,
+  selectorsShareSpecificity
+};

package/src/{position-try.js → rules/position-try.js}

@@ -2,7 +2,7 @@
  * @file Handles `@position-try` rule analysis, usage tracking, and dead-rule elimination during CSS minification.
  */
 
-import { registersCustomProperty } from './rules/property.js';
+import { registersCustomProperty } from './property.js';
 
 /**
  * Scans top-level rules to register `@property` custom properties in the context and collect `@position-try` rule declarations and initial usage counts.

package/src/rules/stringify.js

@@ -465,6 +465,19 @@ function stringifyRule (rule, context) {
 
     declarations = processDeclarations(declarations, context);
 
+    // Check if the rule is now effectively empty after processing declarations
+    const isEffectivelyEmptyAfterProcessing = (
+      declarations.length === 0 ||
+      declarations.every((declaration) => {
+        return (
+          declaration.type === 'comment' && !declaration.comment?.startsWith('!')
+        );
+      })
+    );
+    if (isEffectivelyEmptyAfterProcessing) {
+      return '';
+    }
+
     // We need to properly output nested rules vs normal declarations.
     // Wait, the processDeclarations will now correctly keep 'rule' types because we push them in processDeclarations.
     // If we have `.foo { .bar { color: red; } }`, the inner rule is a declaration of type 'rule' with selectors: ['.bar'].

package/src/utilities.js

@@ -19,6 +19,20 @@ function resolveUnicodeEscape (hex) {
   return String.fromCodePoint(codePoint);
 }
 
+/**
+ * Reports whether a property is a custom property. A custom property holds an
+ * arbitrary token stream rather than a typed value, so every one of its tokens,
+ * whitespace included, is part of what it stores, and neither shorthands nor
+ * `all` ever reset it.
+ *
+ * @param  {string}  property  The CSS property name.
+ * @return {boolean}           Whether the property is a custom property.
+ */
+function isCustomProperty (property) {
+  return Boolean(property) && property.startsWith('--');
+}
+
 export {
+  isCustomProperty,
   resolveUnicodeEscape
 };