@thejaredwilcurt/csslop 0.0.49 → 0.0.50

package/src/rules/optimize/merge-nested-rules.js

@@ -0,0 +1,117 @@
+/**
+ * @file Combines consecutive nested rules that share a declaration body and a specificity into one rule with a comma-separated selector list.
+ */
+
+import {
+  compareSpecificity,
+  maxSelectorSpecificity
+} from './specificity.js';
+
+/**
+ * Builds a normalized signature of a rule's declaration body, or null when the
+ * rule contains anything other than plain declarations (e.g. nested rules).
+ *
+ * @param  {object}      rule  The AST rule node.
+ * @return {string|null}       The sorted "property:value" signature, or null.
+ */
+function nestedRuleBodySignature (rule) {
+  const declarations = (rule.declarations || []).filter((declaration) => {
+    return declaration.type !== 'whitespace' && declaration.type !== 'comment';
+  });
+  if (declarations.length === 0) {
+    return null;
+  }
+  const isAllPlainDeclarations = declarations.every((declaration) => {
+    return declaration.type === 'declaration' && declaration.property;
+  });
+  if (!isAllPlainDeclarations) {
+    return null;
+  }
+  return declarations
+    .map((declaration) => {
+      return declaration.property + ':' + (declaration.value || '').trim();
+    })
+    .sort()
+    .join(';');
+}
+
+/**
+ * Determines whether two nested rules can be merged into a shared selector list.
+ * They must have identical declaration bodies and the same specificity level,
+ * since comma-separated nested selectors share the highest specificity of the
+ * group (like `:is()`).
+ *
+ * @param  {object}  first   The first nested rule.
+ * @param  {object}  second  The second nested rule.
+ * @return {boolean}         Whether the two nested rules may be merged.
+ */
+function nestedRulesMergeable (first, second) {
+  if (!first.selectors?.length || !second.selectors?.length) {
+    return false;
+  }
+  const firstSignature = nestedRuleBodySignature(first);
+  if (firstSignature === null || firstSignature !== nestedRuleBodySignature(second)) {
+    return false;
+  }
+  const firstSpecificity = maxSelectorSpecificity(first.selectors.join(','));
+  const secondSpecificity = maxSelectorSpecificity(second.selectors.join(','));
+  return compareSpecificity(firstSpecificity, secondSpecificity) === 0;
+}
+
+/**
+ * Recursively merges consecutive nested rules within a declaration list when
+ * they share identical bodies and specificity, combining their selector lists.
+ *
+ * @param  {Array} declarations  The declaration/nested-rule entries of a parent rule.
+ * @return {Array}               The declaration list with mergeable nested rules combined.
+ */
+function mergeConsecutiveNestedRules (declarations) {
+  const recursed = declarations.map((declaration) => {
+    if (declaration.type === 'rule' && declaration.declarations) {
+      return { ...declaration, declarations: mergeConsecutiveNestedRules(declaration.declarations) };
+    }
+    return declaration;
+  });
+
+  const result = [];
+  for (const declaration of recursed) {
+    const previous = result[result.length - 1];
+    if (
+      declaration.type === 'rule' &&
+      previous &&
+      previous.type === 'rule' &&
+      nestedRulesMergeable(previous, declaration)
+    ) {
+      result[result.length - 1] = {
+        ...previous,
+        selectors: [...previous.selectors, ...declaration.selectors]
+      };
+      continue;
+    }
+    result.push(declaration);
+  }
+  return result;
+}
+
+/**
+ * Merges mergeable nested rules within every rule's body across the stylesheet,
+ * recursing into `@media` and `@layer` blocks. Top-level rules are not merged
+ * here, since only nested (comma-grouped) selectors share specificity.
+ *
+ * @param  {Array} rules  The AST rule nodes to process.
+ * @return {Array}        The rules with mergeable nested rules combined.
+ */
+function mergeIdenticalNestedRules (rules) {
+  for (const rule of rules) {
+    if (rule.type === 'rule' && rule.declarations) {
+      rule.declarations = mergeConsecutiveNestedRules(rule.declarations);
+    } else if ((rule.type === 'media' || rule.type === 'layer') && rule.rules) {
+      rule.rules = mergeIdenticalNestedRules(rule.rules);
+    }
+  }
+  return rules;
+}
+
+export {
+  mergeIdenticalNestedRules
+};

package/src/rules/optimize/merge-selectors.js

@@ -0,0 +1,252 @@
+/**
+ * @file Merges rules that share a selector, placing the merged rule wherever the cascade reads it the same way it read the two rules apart.
+ */
+
+import {
+  expandToOverridableProperties,
+  isImportantDeclaration,
+  isPropertyDeclaration
+} from './declaration-writes.js';
+import { createOverrideIndex } from './override-index.js';
+import { normalizeSelector } from './selector-normalization.js';
+
+/**
+ * Builds the key two rules must share to be considered the same selector.
+ *
+ * @param  {object} rule  The AST rule node.
+ * @return {string}       The normalized, order independent selector key.
+ */
+function buildSelectorKey (rule) {
+  if (!rule.selectors) {
+    return '';
+  }
+  return rule.selectors
+    .map((selector) => {
+      return normalizeSelector(selector);
+    })
+    .sort()
+    .join(',');
+}
+
+/**
+ * Returns a rule's selector key, building it the first time it is needed. A
+ * merge only ever grows a rule's declarations, never its selectors, so a key
+ * stays valid for every pass of the merge.
+ *
+ * @param  {object} rule               The AST rule node.
+ * @param  {Map}    selectorKeyByRule  The selector keys already built, shared by every pass of one merge.
+ * @return {string}                    The normalized, order independent selector key.
+ */
+function getSelectorKey (rule, selectorKeyByRule) {
+  let selectorKey = selectorKeyByRule.get(rule);
+  if (selectorKey === undefined) {
+    selectorKey = buildSelectorKey(rule);
+    selectorKeyByRule.set(rule, selectorKey);
+  }
+  return selectorKey;
+}
+
+/**
+ * Placement for a merged rule whose combined declarations belong where the
+ * later of the two rules was, because the earlier declarations moved down.
+ *
+ * @type {string}
+ */
+const MERGE_AT_LATER_RULE = 'later';
+
+/**
+ * Placement for a merged rule whose combined declarations belong where the
+ * earlier of the two rules was, because the later declarations moved up.
+ *
+ * @type {string}
+ */
+const MERGE_AT_EARLIER_RULE = 'earlier';
+
+/**
+ * Finds which declaration decides each leaf property once a list of
+ * declarations is read as one rule's body. Within a rule, an important
+ * declaration beats a non-important one, and between two of equal weight the
+ * last one written wins.
+ *
+ * @param  {Array} declarations  The declarations of the combined rule, in the order they would be written.
+ * @return {Map}                 Map of leaf property name to the declaration that decides it.
+ */
+function findDecidingDeclarations (declarations) {
+  const decidingDeclarations = new Map();
+  const importantDeclarations = new Set();
+  for (const declaration of declarations) {
+    if (!isPropertyDeclaration(declaration)) {
+      continue;
+    }
+    const isImportant = isImportantDeclaration(declaration);
+    if (isImportant) {
+      importantDeclarations.add(declaration);
+    }
+    for (const leafProperty of expandToOverridableProperties(declaration.property)) {
+      const decidingDeclaration = decidingDeclarations.get(leafProperty);
+      const outranksIt = (
+        !decidingDeclaration ||
+        isImportant ||
+        !importantDeclarations.has(decidingDeclaration)
+      );
+      if (outranksIt) {
+        decidingDeclarations.set(leafProperty, declaration);
+      }
+    }
+  }
+  return decidingDeclarations;
+}
+
+/**
+ * Reports whether anything a rule brings to a merge still decides a property
+ * of the combined rule. A declaration that loses every property it writes to
+ * another declaration of the same rule is dropped from the merged rule, so
+ * where the merged rule sits cannot change how it reads.
+ *
+ * @param  {object}  rule                  The rule contributing the entries.
+ * @param  {Map}     decidingDeclarations  The deciding declaration of each leaf property of the merged rule.
+ * @return {boolean}                       True when the rule still decides something after the merge.
+ */
+function decidesAnythingAfterMerge (rule, decidingDeclarations) {
+  return (rule.declarations || []).some((entry) => {
+    if (!isPropertyDeclaration(entry)) {
+      return entry.type !== 'whitespace' && entry.type !== 'comment';
+    }
+    return [...expandToOverridableProperties(entry.property)].some((leafProperty) => {
+      return decidingDeclarations.get(leafProperty) === entry;
+    });
+  });
+}
+
+/**
+ * Decides where two rules with the same selector can be combined. Merging them
+ * always makes one set of declarations cross whatever separates the two rules,
+ * which can flip a conflict the crossing declarations used to win or lose, so
+ * the merged rule goes wherever the set that moved keeps its old standing.
+ * Nothing separates adjacent rules, so those always merge.
+ *
+ * The declarations one rule loses to the other are the exception: they are
+ * dropped from the merged rule, so the merged rule belongs wherever the
+ * declarations that outlive the merge already were, and nothing has to cross
+ * anything at all. That is what lets `.a{color:red!important}` swallow a later
+ * `.a{color:tan}` across a rule that also writes `color`.
+ *
+ * @param  {object}      overrideIndex    The index of what each position writes to.
+ * @param  {object}      earlierRule      The first of the two rules with this selector.
+ * @param  {object}      laterRule        The second of the two rules with this selector.
+ * @param  {number}      earlierPosition  The slot the earlier rule occupies.
+ * @param  {number}      laterPosition    The slot the later rule would occupy.
+ * @return {string|null}                  Where to place the merged rule, or null when merging is unsafe.
+ */
+function chooseMergePlacement (overrideIndex, earlierRule, laterRule, earlierPosition, laterPosition) {
+  const rulesAreAdjacent = earlierPosition === laterPosition - 1;
+  if (rulesAreAdjacent) {
+    return MERGE_AT_LATER_RULE;
+  }
+  const decidingDeclarations = findDecidingDeclarations([
+    ...(earlierRule.declarations || []),
+    ...(laterRule.declarations || [])
+  ]);
+  if (!decidesAnythingAfterMerge(laterRule, decidingDeclarations)) {
+    return MERGE_AT_EARLIER_RULE;
+  }
+  if (!decidesAnythingAfterMerge(earlierRule, decidingDeclarations)) {
+    return MERGE_AT_LATER_RULE;
+  }
+  if (!overrideIndex.blocksRelocation(earlierRule, earlierPosition)) {
+    return MERGE_AT_LATER_RULE;
+  }
+  if (!overrideIndex.blocksRelocation(laterRule, earlierPosition)) {
+    return MERGE_AT_EARLIER_RULE;
+  }
+  return null;
+}
+
+/**
+ * Merges rules with identical normalized selectors by combining their declarations, as long as `chooseMergePlacement` finds a spot for the combined rule that the cascade reads the same way. Non-rule entries that affect the cascade (like `@media`) break the merge window, while comments do not, since comments never influence how declarations apply.
+ *
+ * @param  {Array}  rules        The AST rule nodes to merge.
+ * @param  {object} mergeCaches  The write profiles and selector keys shared by every pass of one merge.
+ * @return {Array}               A new array of rules with same-selector rules combined.
+ */
+function mergeSelectorRulePass (rules, mergeCaches) {
+  // A rule merged at the later of the two positions 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();
+  const overrideIndex = createOverrideIndex(mergeCaches.profileByRule);
+  for (const rule of rules) {
+    if (rule.type === 'whitespace') {
+      continue;
+    }
+    if (rule.type !== 'rule') {
+      slots.push(rule);
+      // Clearing a map replaces its storage, so already empty maps are left alone
+      if (rule.type !== 'comment' && selectorMap.size) {
+        selectorMap.clear();
+        positionByRule.clear();
+      }
+      continue;
+    }
+    const selectorKey = getSelectorKey(rule, mergeCaches.selectorKeyByRule);
+    const existingRule = selectorKey && selectorMap.get(selectorKey);
+    if (existingRule) {
+      const existingPosition = positionByRule.get(existingRule);
+      const mergedPosition = slots.length;
+      const placement = chooseMergePlacement(overrideIndex, existingRule, rule, existingPosition, mergedPosition);
+      if (placement) {
+        existingRule.declarations.push(...(rule.declarations || []));
+        overrideIndex.absorbRule(existingRule, rule);
+        if (placement === MERGE_AT_LATER_RULE) {
+          slots[existingPosition] = null;
+          positionByRule.set(existingRule, mergedPosition);
+          slots.push(existingRule);
+          overrideIndex.recordRule(existingRule, mergedPosition);
+        } else {
+          // The merged declarations now live at the earlier slot, but they are
+          // recorded at the later one, since the index is only ever appended
+          // to. Reading them as later than they are can only hold back a
+          // further merge, never allow an unsafe one.
+          overrideIndex.recordRule(rule, mergedPosition);
+        }
+        continue;
+      }
+    }
+    selectorMap.set(selectorKey, rule);
+    positionByRule.set(rule, slots.length);
+    overrideIndex.recordRule(rule, slots.length);
+    slots.push(rule);
+  }
+  return slots.filter((slot) => {
+    return slot !== null;
+  });
+}
+
+/**
+ * Reconsiders blocked pairs after merges relocate the rules that blocked them.
+ * Each productive pass removes a rule, so this reaches a fixed point without
+ * rerunning parsing or unrelated optimizations.
+ *
+ * @param  {Array} rules  The sibling rules to merge.
+ * @return {Array}        Rules with all currently safe same-selector merges.
+ */
+function mergeSelectorRules (rules) {
+  const mergeCaches = {
+    profileByRule: new Map(),
+    selectorKeyByRule: new Map()
+  };
+  let previousRules = rules;
+  let mergedRules = mergeSelectorRulePass(previousRules, mergeCaches);
+  while (mergedRules.length < previousRules.length) {
+    previousRules = mergedRules;
+    mergedRules = mergeSelectorRulePass(previousRules, mergeCaches);
+  }
+  return mergedRules;
+}
+
+export {
+  mergeSelectorRules
+};

package/src/rules/optimize/nest-rules.js

@@ -0,0 +1,202 @@
+/**
+ * @file Nests flat rules under a preceding rule whose selector their own selector starts with, so CSS nesting writes the shared part once.
+ */
+
+/**
+ * Matches the part of a child selector that follows its parent when that part
+ * starts with an explicit combinator. Optional whitespace, then the combinator
+ * (`>`, `+`, or `~`) is captured, then optional whitespace, then the rest of
+ * the selector is captured.
+ *
+ * @type {RegExp}
+ */
+const LEADING_COMBINATOR_PATTERN = /^\s*([>+~])\s*(.+)$/;
+
+/**
+ * Expresses the part of a child selector that follows its parent as the
+ * selector it would be once nested inside that parent.
+ *
+ * @param  {string}      remainder  The child selector with the parent prefix removed.
+ * @return {string|null}            The nested selector, or null when the remainder cannot be nested.
+ */
+function nestSelectorRemainder (remainder) {
+  if (!remainder) {
+    return '&';
+  }
+  if (remainder.startsWith(':')) {
+    return '&' + remainder;
+  }
+  if (remainder.startsWith(' ')) {
+    return remainder.slice(1);
+  }
+  const combinatorMatch = remainder.match(LEADING_COMBINATOR_PATTERN);
+  if (combinatorMatch) {
+    return combinatorMatch[1] + combinatorMatch[2];
+  }
+  return null;
+}
+
+/**
+ * Builds a reusable matcher that expresses child selectors as nested selectors
+ * relative to one parent. Most children tested against a parent do not start
+ * with it at all, so that cheap prefix check runs before anything else.
+ *
+ * @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();
+
+  return (childSelector) => {
+    const child = childSelector.trim();
+    if (!child.startsWith(parent)) {
+      return null;
+    }
+    return nestSelectorRemainder(child.slice(parent.length));
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param  {string}      parentSelector  The parent selector string.
+ * @param  {string}      childSelector   The child selector string to try nesting.
+ * @return {string|null}                 The nested selector using & syntax, or null if the child cannot be nested under the parent.
+ */
+function tryNestSelector (parentSelector, childSelector) {
+  return createNestedSelectorMatcher(parentSelector)(childSelector);
+}
+
+/**
+ * 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)) {
+      // The second colon of a pseudo-element is part of its `::` introducer,
+      // not a boundary between a potential parent and nested child.
+      if (character === ':' && childSelector[index - 1] === ':') {
+        continue;
+      }
+      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.
+ *
+ * @param  {Array} rules  The flat AST rule nodes to nest.
+ * @return {Array}        A new array of rules with applicable children nested under their parents.
+ */
+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();
+    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) {
+      const innerRules = rule.declarations.filter((declaration) => {
+        return declaration.type === 'rule';
+      });
+      if (innerRules.length > 0) {
+        const nonRuleDeclarations = rule.declarations.filter((declaration) => {
+          return declaration.type !== 'rule';
+        });
+        rule.declarations = [...nonRuleDeclarations, ...nestFlatRules(innerRules)];
+      }
+    }
+  }
+  return result;
+}
+
+export {
+  collectCandidateParentSelectors,
+  createNestedSelectorMatcher,
+  isSelectorWhitespace,
+  nestFlatRules
+};