@thejaredwilcurt/csslop 0.0.48 → 0.0.50

package/src/rules/optimize/expand-nesting.js

@@ -0,0 +1,236 @@
+/**
+ * @file Expands nested rules into flat rules with combined selectors whenever that lets them merge with rules that already exist, and flattens `&` rules into their parent.
+ */
+
+import { tokenizeCssValue } from '../../parser/tokenizer.js';
+import { containsPseudoElement } from '../selectors.js';
+
+import { selectorsShareSpecificity } from './specificity.js';
+
+/**
+ * Reports whether an entry of a rule's body is itself a nested rule rather
+ * than a plain declaration.
+ *
+ * @param  {object}  entry  An entry of a rule's declaration list.
+ * @return {boolean}        True when the entry is a nested rule.
+ */
+function isNestedRule (entry) {
+  return entry.type === 'rule';
+}
+
+/**
+ * Expands the rules nested inside each rule's body, so a chain of wrappers
+ * collapses from the inside out and the outermost wrapper is then judged
+ * against an already flattened child. A rule's body holds the same kinds of
+ * entries a stylesheet does, so the body is expanded by the same rules, and
+ * the plain declarations it also holds pass through untouched.
+ *
+ * @param  {Array} rules  The AST rule nodes whose bodies may hold nested rules.
+ * @return {Array}        The rules, each with its body expanded.
+ */
+function expandNestedRuleBodies (rules) {
+  return rules.map((rule) => {
+    if (rule.type !== 'rule' || !(rule.declarations || []).some(isNestedRule)) {
+      return rule;
+    }
+    const declarations = expandPureNestedRules(rule.declarations);
+    const canFlattenSelf = selectorsShareSpecificity(rule.selectors) && !rule.selectors.some(containsPseudoElement);
+    let encounteredNestedContent = false;
+    const flattened = declarations.flatMap((entry) => {
+      const isSelfRule = entry.type === 'rule' && entry.selectors?.length === 1 && entry.selectors[0].trim() === '&';
+      if (canFlattenSelf && isSelfRule && !encounteredNestedContent) {
+        return entry.declarations || [];
+      }
+      if (entry.type !== 'declaration' && entry.type !== 'whitespace' && entry.type !== 'comment') {
+        encounteredNestedContent = true;
+      }
+      if (entry.type === 'rule' && rule.selectors.length === 1) {
+        entry.selectors = entry.selectors.map((selector) => {
+          return shortenRepeatedNestingSelector(rule.selectors[0], selector);
+        });
+      }
+      return [entry];
+    });
+    return {
+      ...rule,
+      declarations: flattened
+    };
+  });
+}
+
+/**
+ * Replaces repetitions of a simple class or ID beside a leading nesting
+ * selector. Token comparisons keep longer names and escaped text intact.
+ *
+ * @param  {string} parentSelector  The sole parent selector.
+ * @param  {string} childSelector   The nested selector.
+ * @return {string}                 The shorter equivalent selector.
+ */
+function shortenRepeatedNestingSelector (parentSelector, childSelector) {
+  const parentTokens = tokenizeCssValue(parentSelector);
+  const isClass = parentTokens.length === 2 && parentTokens[0].text === '.' && parentTokens[1].type === 'ident';
+  const isIdentifier = parentTokens.length === 1 && parentTokens[0].type === 'hash';
+  if (!isClass && !isIdentifier) {
+    return childSelector;
+  }
+  const childTokens = tokenizeCssValue(childSelector);
+  if (childTokens[0]?.text !== '&') {
+    return childSelector;
+  }
+  let index = 1;
+  let result = '&';
+  while (index < childTokens.length) {
+    const matchesParent = parentTokens.every((token, position) => {
+      return childTokens[index + position]?.text === token.text;
+    });
+    if (!matchesParent) {
+      break;
+    }
+    result += '&';
+    index += parentTokens.length;
+  }
+  return result + childTokens.slice(index).map((token) => {
+    return token.text;
+  }).join('');
+}
+
+/**
+ * Reports whether a nested child selector still means the same thing once it
+ * is written out in full under its parent.
+ *
+ * @param  {string}  childSelector  The selector of a rule nested inside another.
+ * @return {boolean}                True when the child can be written as a flat selector.
+ */
+function canFlattenChildSelector (childSelector) {
+  const child = childSelector.trim();
+  if (!child) {
+    return false;
+  }
+  // A `&` anywhere but the very start puts the parent where flattening cannot:
+  // `.b &` means the parent follows the child rather than leading it
+  return !child.slice(1).includes('&');
+}
+
+/**
+ * Writes a nested child selector out in full, as the selector it stands for
+ * when read through its parent.
+ *
+ * @param  {string} parentSelector  The selector of the rule the child is nested in.
+ * @param  {string} childSelector   The selector of the nested child rule.
+ * @return {string}                 The flat selector the nested pair stands for.
+ */
+function combineNestedSelector (parentSelector, childSelector) {
+  const parent = parentSelector.trim();
+  const child = childSelector.trim();
+  // A leading `&` names the parent itself, so it is what the parent replaces
+  if (child.startsWith('&')) {
+    return parent + child.slice(1);
+  }
+  return parent + ' ' + child;
+}
+
+/**
+ * Expands rules that contain only nested sub-rules into flat rules with combined selectors, enabling further merging when the combined selectors already exist elsewhere.
+ *
+ * @param  {Array} inputRules  The AST rule nodes to process.
+ * @return {Array}             A new array of rules with pure-nested rules expanded.
+ */
+function expandPureNestedRules (inputRules) {
+  const rules = expandNestedRuleBodies(inputRules);
+  const flatSelectors = new Set();
+  for (const rule of rules) {
+    if (rule.type !== 'rule' || !rule.selectors?.length) {
+      continue;
+    }
+    const nonWhitespace = (rule.declarations || []).filter((declaration) => {
+      return declaration.type !== 'whitespace';
+    });
+    const hasNonRuleDeclarations = nonWhitespace.some((declaration) => {
+      return declaration.type !== 'rule';
+    });
+    if (hasNonRuleDeclarations) {
+      rule.selectors.forEach((selector) => {
+        // Normalize selector whitespace to single space for deduplication
+        flatSelectors.add(selector.trim().replace(/\s+/g, ' '));
+      });
+    }
+  }
+
+  const result = [];
+  for (const rule of rules) {
+    if (rule.type !== 'rule' || !rule.selectors?.length) {
+      result.push(rule);
+      continue;
+    }
+    const nonWhitespace = (rule.declarations || []).filter((declaration) => {
+      return declaration.type !== 'whitespace';
+    });
+    const isPureNested = nonWhitespace.length > 0 && nonWhitespace.every((declaration) => {
+      return declaration.type === 'rule';
+    });
+    // A comma-separated parent selector list behaves like :is() for specificity,
+    // so expanding it into descendant combinations (e.g. #a,.b → #a .c,.b .c)
+    // would change specificity. Only single-selector parents can expand safely.
+    if (!isPureNested || rule.selectors.length !== 1) {
+      result.push(rule);
+      continue;
+    }
+
+    let anyMatch = false;
+    let expandedRules = [];
+    let canExpand = true;
+
+    for (const nestedRule of nonWhitespace) {
+      if (!nestedRule.selectors?.length) {
+        canExpand = false;
+        break;
+      }
+      // A child written as a comma-separated selector list, such as `.b,.c`,
+      // repeats the parent in front of every item when expanded (`.a .b,.a .c`),
+      // while the nested form states the parent once. Expanding is always
+      // longer, and leaving the rule nested keeps one pass from expanding what
+      // the next pass would then keep, so the output stays idempotent.
+      if (nestedRule.selectors.length > 1) {
+        canExpand = false;
+        break;
+      }
+      if (!nestedRule.selectors.every(canFlattenChildSelector)) {
+        canExpand = false;
+        break;
+      }
+      const combinedSelectors = [];
+      for (const parentSelector of rule.selectors) {
+        for (const childSelector of nestedRule.selectors) {
+          const combinedSelector = combineNestedSelector(parentSelector, childSelector);
+          combinedSelectors.push(combinedSelector);
+          if (flatSelectors.has(combinedSelector)) {
+            anyMatch = true;
+          }
+        }
+      }
+      expandedRules.push({ ...nestedRule, selectors: combinedSelectors });
+    }
+
+    const allChildSelectorStrings = expandedRules.map((expandedRule) => {
+      return expandedRule.selectors.join(',');
+    });
+    const allSame = (
+      allChildSelectorStrings.length > 0 &&
+      allChildSelectorStrings.every((selectorString) => {
+        return selectorString === allChildSelectorStrings[0];
+      })
+    );
+    if (canExpand && (allSame || anyMatch)) {
+      for (const expandedRule of expandedRules) {
+        result.push(expandedRule);
+      }
+    } else {
+      result.push(rule);
+    }
+  }
+  return result;
+}
+
+export {
+  expandPureNestedRules
+};

package/src/rules/optimize/factor-parents.js

@@ -0,0 +1,343 @@
+/**
+ * @file Factors the selector portions that consecutive rules share into a synthesized nesting wrapper, or into an `:is()` group when a wrapper would not pay for itself.
+ */
+
+import {
+  containsPseudoElement,
+  isUniversallyRecognizableSelector
+} from '../selectors.js';
+
+import {
+  collectCandidateParentSelectors,
+  createNestedSelectorMatcher,
+  isSelectorWhitespace
+} from './nest-rules.js';
+import { selectorsShareSpecificity } from './specificity.js';
+
+/**
+ * Splits a selector into the part before its final top-level combinator and
+ * the trailing compound that follows it, so selectors that only differ in
+ * that leading part can share the trailing compound through nesting.
+ *
+ * @param  {string}      selector  The selector string to split.
+ * @return {object|null}           The `head`, `combinator` (`' '` for descendant), and `tail`, or null when the selector has no top-level combinator.
+ */
+function splitSelectorTail (selector) {
+  const trimmed = selector.trim();
+  let bracketDepth = 0;
+  let parenthesisDepth = 0;
+  let combinatorStart = -1;
+  let combinator = '';
+  let tailStart = -1;
+  for (let index = 0; index < trimmed.length; index++) {
+    const character = trimmed[index];
+    if (character === '(') {
+      parenthesisDepth++;
+    } else if (character === ')') {
+      parenthesisDepth--;
+    } else if (character === '[') {
+      bracketDepth++;
+    } else if (character === ']') {
+      bracketDepth--;
+    } else if (parenthesisDepth === 0 && bracketDepth === 0) {
+      if (character === '>' || character === '+' || character === '~') {
+        // Whitespace written after an explicit combinator belongs to it
+        let end = index + 1;
+        while (end < trimmed.length && isSelectorWhitespace(trimmed[end])) {
+          end++;
+        }
+        combinator = character;
+        combinatorStart = index;
+        tailStart = end;
+        index = end - 1;
+      } else if (isSelectorWhitespace(character)) {
+        // Whitespace adjacent to an explicit combinator belongs to that
+        // combinator, so only a self-standing run is a descendant combinator
+        const previous = trimmed[index - 1];
+        let end = index;
+        while (end < trimmed.length && isSelectorWhitespace(trimmed[end])) {
+          end++;
+        }
+        const next = trimmed[end];
+        if (
+          next &&
+          next !== '>' && next !== '+' && next !== '~' &&
+          previous !== '>' && previous !== '+' && previous !== '~'
+        ) {
+          combinator = ' ';
+          combinatorStart = index;
+          tailStart = end;
+        }
+        index = end - 1;
+      }
+    }
+  }
+  if (!combinator || combinatorStart === 0) {
+    return null;
+  }
+  const head = trimmed.slice(0, combinatorStart).trim();
+  const tail = trimmed.slice(tailStart).trim();
+  if (!head || !tail) {
+    return null;
+  }
+  return {
+    combinator,
+    head,
+    tail
+  };
+}
+
+/**
+ * Rewrites a multi-selector rule whose selectors only differ before their
+ * final combinator into a wrapper rule that nests the shared trailing
+ * compound once, such as `&:hover .x,&:focus .x` becoming
+ * `&:hover,&:focus{.x{...}}`. The heads join a comma list, which resolves
+ * like `:is()`, so they may only be grouped while they share one specificity.
+ *
+ * @param  {object} rule  The AST rule node whose selector list may be factored.
+ * @return {object}       The rule, rewritten when factoring is valid and shorter.
+ */
+function factorCommonTrailingCompound (rule) {
+  if (rule.type !== 'rule' || !rule.selectors || rule.selectors.length < 2) {
+    return rule;
+  }
+  const splitSelectors = rule.selectors.map(splitSelectorTail);
+  if (splitSelectors.some((split) => {
+    return split === null;
+  })) {
+    return rule;
+  }
+  const first = splitSelectors[0];
+  const allShareTrailingCompound = splitSelectors.every((split) => {
+    return split.tail === first.tail && split.combinator === first.combinator;
+  });
+  if (!allShareTrailingCompound) {
+    return rule;
+  }
+  const heads = splitSelectors.map((split) => {
+    return split.head;
+  });
+  if (!selectorsShareSpecificity(heads)) {
+    return rule;
+  }
+  const nestedSelector = first.combinator === ' ' ? first.tail : first.combinator + first.tail;
+  const flatLength = rule.selectors.join(',').length;
+  const factoredLength = heads.join(',').length + nestedSelector.length + 2;
+  if (factoredLength >= flatLength) {
+    return rule;
+  }
+  return {
+    ...rule,
+    selectors: heads,
+    declarations: [{
+      type: 'rule',
+      selectors: [nestedSelector],
+      declarations: rule.declarations
+    }]
+  };
+}
+
+/**
+ * Collects every selector prefix of a rule's first selector that could serve
+ * as a shared nesting parent, including the full selector itself, which can
+ * host sibling pseudo-class variants such as `.a` of `.a,.a:hover`.
+ *
+ * @param  {object} rule  The AST rule node whose candidates are collected.
+ * @return {Set}          The candidate parent selector strings.
+ */
+function collectSharedParentCandidates (rule) {
+  const firstSelector = rule.selectors[0].trim();
+  const candidates = collectCandidateParentSelectors(firstSelector);
+  if (firstSelector) {
+    candidates.add(firstSelector);
+  }
+  return candidates;
+}
+
+/**
+ * Counts how many characters wrapping a run behind a shared parent selector
+ * saves: the parent is written once with its braces, and every wrapped
+ * selector shrinks to its nested form.
+ *
+ * @param  {Array}  run     The rules of the run paired with their nested selectors.
+ * @param  {string} parent  The shared parent selector string.
+ * @return {number}         The character savings of the wrapper, or a non-positive number when it costs more than it saves.
+ */
+function measureWrapperSavings (run, parent) {
+  const charactersSaved = run.reduce((total, entry) => {
+    return total + entry.sibling.selectors.reduce((sum, selector, position) => {
+      return sum + selector.trim().length - entry.nestedSelectors[position].length;
+    }, 0);
+  }, 0);
+  // The wrapper writes the shared selector once plus its surrounding braces.
+  return charactersSaved - (parent.length + 2);
+}
+
+/**
+ * Restores the source order of rules that are being moved under their own
+ * selector. Their relative order can affect the cascade when nested rules
+ * overlap, so it must not depend on an earlier grouping optimization.
+ *
+ * @param  {Array} rules  The nested rules to order.
+ * @return {Array}        A source-ordered copy of the rules.
+ */
+function orderRulesBySourcePosition (rules) {
+  return [...rules].sort((firstRule, secondRule) => {
+    return firstRule.position?.start?.offset - secondRule.position?.start?.offset;
+  });
+}
+
+/**
+ * Groups consecutive sibling rules that share a common leading selector
+ * portion (such as `.foo` in `.foo .a`, `.foo .b`, or `.menu .item` in
+ * `.menu .item:hover .x`) into a synthesized parent rule with the shared
+ * portion factored out. Every viable prefix of the first rule's selector is
+ * tried as the parent, and the grouping that saves the most characters wins,
+ * but only when it saves more than the wrapper itself costs. Rules with a
+ * comma-separated selector list can join a run when every one of their
+ * selectors nests under the parent.
+ *
+ * @param  {Array}   rules                  The flat AST rule nodes to factor.
+ * @param  {boolean} allowTrailingCompound  True when the rules are children of a factored wrapper, whose `&`-relative selectors may share a trailing compound that can be factored out in turn.
+ * @return {Array}                          A new array of rules with shared parent selectors factored into nesting wrappers.
+ */
+function factorCommonParents (rules, allowTrailingCompound = false) {
+  const result = [];
+  let index = 0;
+  while (index < rules.length) {
+    const rule = rules[index];
+    if (rule.type !== 'rule' || !rule.selectors?.length) {
+      result.push(rule);
+      index++;
+      continue;
+    }
+    let bestGrouping = null;
+    for (const candidateParent of collectSharedParentCandidates(rule)) {
+      if (!candidateParent || containsPseudoElement(candidateParent)) {
+        continue;
+      }
+      const matchNestedSelector = createNestedSelectorMatcher(candidateParent);
+      // Collect the run of consecutive rules whose selectors can all nest under the candidate.
+      const run = [];
+      let lookahead = index;
+      while (lookahead < rules.length) {
+        const sibling = rules[lookahead];
+        if (sibling.type !== 'rule' || !sibling.selectors?.length) {
+          break;
+        }
+        const nestedSelectors = sibling.selectors.map((selector) => {
+          return matchNestedSelector(selector.trim());
+        });
+        if (nestedSelectors.some((nestedSelector) => {
+          return nestedSelector === null;
+        })) {
+          break;
+        }
+        run.push({ sibling, nestedSelectors });
+        lookahead++;
+      }
+      const selectorCount = run.reduce((total, entry) => {
+        return total + entry.nestedSelectors.length;
+      }, 0);
+      // A lone single-selector rule has nothing to share its parent with.
+      if (run.length < 2 && selectorCount < 2) {
+        continue;
+      }
+      const savings = measureWrapperSavings(run, candidateParent);
+      if (savings > 0 && (!bestGrouping || savings > bestGrouping.savings)) {
+        bestGrouping = {
+          lookahead,
+          parent: candidateParent,
+          run,
+          savings
+        };
+      }
+    }
+    if (!bestGrouping) {
+      if (allowTrailingCompound) {
+        result.push(factorCommonTrailingCompound(rule));
+      } else {
+        result.push(rule);
+      }
+      index++;
+      continue;
+    }
+    const firstEntry = bestGrouping.run[0];
+    const firstSelectorIsParent = (
+      firstEntry.nestedSelectors.length === 1 &&
+      firstEntry.nestedSelectors[0] === '&'
+    );
+    const directDeclarations = firstSelectorIsParent ?
+      firstEntry.sibling.declarations :
+      [];
+    const entriesToNest = firstSelectorIsParent ?
+      bestGrouping.run.slice(1) :
+      bestGrouping.run;
+    const children = entriesToNest.map((entry) => {
+      return { ...entry.sibling, selectors: entry.nestedSelectors };
+    });
+    let declarations;
+    if (firstSelectorIsParent) {
+      const directNestedRules = directDeclarations.filter((declaration) => {
+        return declaration.type === 'rule';
+      });
+      const directEntries = directDeclarations.filter((declaration) => {
+        return declaration.type !== 'rule';
+      });
+      declarations = [
+        ...directEntries,
+        ...orderRulesBySourcePosition([...directNestedRules, ...children])
+      ];
+    } else {
+      declarations = factorCommonParents(children, true);
+    }
+    result.push({
+      type: 'rule',
+      selectors: [bestGrouping.parent],
+      declarations
+    });
+    index = bestGrouping.lookahead;
+  }
+  return result;
+}
+
+/**
+ * Shares a descendant prefix through `:is()` when a nesting wrapper did not
+ * save enough space to factor the parent out of the selector list.
+ *
+ * @param {object} rule  The style rule whose selector list may be shortened.
+ */
+function factorSelectorBranches (rule) {
+  if (rule.type !== 'rule' || !rule.selectors?.length) {
+    return;
+  }
+  for (const parent of [...rule.selectors]) {
+    const prefix = parent + ' ';
+    const branches = rule.selectors.filter((selector) => {
+      return selector.startsWith(prefix);
+    });
+    const children = branches.map((selector) => {
+      return selector.slice(prefix.length);
+    });
+    if (children.length < 2 || !children.every(isUniversallyRecognizableSelector) || !selectorsShareSpecificity(children)) {
+      continue;
+    }
+    const grouped = prefix + ':is(' + children.sort().join(',') + ')';
+    if (grouped.length >= branches.join(',').length) {
+      continue;
+    }
+    const branchSet = new Set(branches);
+    const firstIndex = rule.selectors.indexOf(branches[0]);
+    rule.selectors = rule.selectors.flatMap((selector, index) => {
+      if (index === firstIndex) {
+        return [grouped];
+      }
+      return branchSet.has(selector) ? [] : [selector];
+    });
+  }
+}
+
+export {
+  factorCommonParents,
+  factorSelectorBranches
+};

package/src/rules/optimize/index.js

@@ -0,0 +1,71 @@
+/**
+ * @file Optimizes CSS rule structures by merging selectors, deduplicating keyframes, nesting flat rules, and consolidating `@media` and `@layer` blocks.
+ */
+
+import {
+  deduplicateKeyframes,
+  mergeLayerRules,
+  mergeMediaRules
+} from './at-rules.js';
+import { removeEmptyRules } from './empty-rules.js';
+import { expandPureNestedRules } from './expand-nesting.js';
+import {
+  factorCommonParents,
+  factorSelectorBranches
+} from './factor-parents.js';
+import { mergeByDeclarations } from './merge-declarations.js';
+import { mergeIdenticalNestedRules } from './merge-nested-rules.js';
+import { mergeSelectorRules } from './merge-selectors.js';
+import { nestFlatRules } from './nest-rules.js';
+import {
+  removeFullyOverriddenSelectors,
+  removeOverriddenMultiSelectorProperties
+} from './prune-overridden.js';
+import { clearNormalizedSelectorCache } from './selector-normalization.js';
+import { clearSpecificityCache } from './specificity.js';
+
+/**
+ * Discards every memoized specificity and normalized selector. The minifier
+ * calls this around each stylesheet, so the caches do not outlive the pass that
+ * filled them.
+ */
+function clearSelectorCaches () {
+  clearSpecificityCache();
+  clearNormalizedSelectorCache();
+}
+
+/**
+ * Applies the structural optimization pipeline to a stylesheet or grouping
+ * block, so merging at-rules does not leave their children unoptimized.
+ *
+ * @param  {Array} rules  The sibling AST entries.
+ * @return {Array}        The optimized sibling entries.
+ */
+function optimizeRuleList (rules) {
+  let result = expandPureNestedRules(rules);
+  result = mergeLayerRules(result, mergeSelectorRules);
+  result = mergeMediaRules(result, mergeSelectorRules);
+  result = deduplicateKeyframes(result);
+  for (const rule of result) {
+    if (rule.rules) {
+      rule.rules = optimizeRuleList(rule.rules);
+    }
+  }
+  result = mergeSelectorRules(result);
+  result = removeOverriddenMultiSelectorProperties(result);
+  result = removeFullyOverriddenSelectors(result);
+  result = removeEmptyRules(result);
+  result = mergeByDeclarations(result);
+  result = nestFlatRules(result);
+  result = removeEmptyRules(result);
+  result = mergeByDeclarations(result);
+  result = factorCommonParents(result);
+  result = nestFlatRules(result);
+  result.forEach(factorSelectorBranches);
+  return mergeIdenticalNestedRules(result);
+}
+
+export {
+  clearSelectorCaches,
+  optimizeRuleList
+};