@thejaredwilcurt/csslop 0.0.49 → 0.0.51

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

@@ -0,0 +1,199 @@
+/**
+ * @file Folds a rule into the rule that follows it when the later rule restates everything the earlier one declares, so the two can share a selector list.
+ */
+
+import { normalizeSelector } from './selector-normalization.js';
+import { selectorsShareSpecificity } from './specificity.js';
+
+/**
+ * Removes duplicate selectors from a combined selector list by normalizing
+ * whitespace and preserving the first occurrence of each unique selector.
+ *
+ * @param  {Array} selectors  The selector strings to deduplicate.
+ * @return {Array}            A new array with duplicate selectors removed.
+ */
+function deduplicateSelectors (selectors) {
+  const seen = new Set();
+  return selectors.filter((selector) => {
+    // Normalize whitespace to single spaces for consistent comparison
+    const normalized = selector.trim().replace(/\s+/g, ' ');
+    if (seen.has(normalized)) {
+      return false;
+    }
+    seen.add(normalized);
+    return true;
+  });
+}
+
+/**
+ * The rule body entries that style nothing themselves, and so have no say in
+ * whether one rule's body is carried by another's.
+ *
+ * @type {Set<string>}
+ */
+const UNSTYLED_BODY_ENTRY_TYPES = new Set(['whitespace', 'comment']);
+
+/**
+ * Splits a rule body into the declarations it sets directly and the blocks
+ * nested inside it, leaving out the entries that style nothing.
+ *
+ * @param  {Array}  declarations  The rule body entries.
+ * @return {object}               The body's `plainDeclarations` and `nestedBlocks`.
+ */
+function partitionRuleBody (declarations) {
+  const plainDeclarations = [];
+  const nestedBlocks = [];
+  for (const entry of declarations || []) {
+    if (UNSTYLED_BODY_ENTRY_TYPES.has(entry.type)) {
+      continue;
+    }
+    if (entry.property) {
+      plainDeclarations.push(entry);
+    } else {
+      nestedBlocks.push(entry);
+    }
+  }
+  return {
+    nestedBlocks,
+    plainDeclarations
+  };
+}
+
+/**
+ * Describes a block nested inside a rule precisely enough to tell whether two
+ * rules nest the very same thing. Only plain nested rules can be described: an
+ * at-rule nested in a rule carries a prelude that decides when its body applies,
+ * so it is reported as indescribable rather than guessed at.
+ *
+ * @param  {object}      block  A block nested inside a rule body.
+ * @return {string|null}        The signature, or null when the block cannot be described.
+ */
+function nestedBlockSignature (block) {
+  if (block.type !== 'rule' || !block.selectors?.length) {
+    return null;
+  }
+  const {
+    nestedBlocks,
+    plainDeclarations
+  } = partitionRuleBody(block.declarations);
+  const declarationParts = plainDeclarations.map((declaration) => {
+    return declaration.property + ':' + (declaration.value || '').trim();
+  });
+  const nestedParts = nestedBlocksSignature(nestedBlocks);
+  if (nestedParts === null) {
+    return null;
+  }
+  const selectors = block.selectors.map(normalizeSelector).join(',');
+  return selectors + '{' + declarationParts.join(';') + nestedParts + '}';
+}
+
+/**
+ * Describes every block nested in a rule body as one comparable string, in the
+ * order the blocks are written, since that order decides which of them wins a
+ * conflict.
+ *
+ * @param  {Array}       nestedBlocks  The blocks nested in a rule body.
+ * @return {string|null}               The combined signature, or null when any block cannot be described.
+ */
+function nestedBlocksSignature (nestedBlocks) {
+  let combined = '';
+  for (const block of nestedBlocks) {
+    const signature = nestedBlockSignature(block);
+    if (signature === null) {
+      return null;
+    }
+    combined += signature;
+  }
+  return combined;
+}
+
+/**
+ * Combines an earlier rule with the rule that follows it when everything the
+ * earlier one styles is restated by the later one, so the earlier selector can
+ * simply join the later rule's shared part and the remainder stays behind in a
+ * rule of its own.
+ *
+ * Both rules have to nest the same blocks. A block nested in only one of them
+ * would either be lost or start matching the other rule's selector, neither of
+ * which the two rules said.
+ *
+ * @param  {object}     previousRule  The rule immediately in front of `rule`.
+ * @param  {object}     rule          The rule being folded into its predecessor.
+ * @return {Array|null}               The rules that replace the pair, or null when they cannot be combined.
+ */
+function mergeRuleIntoPredecessor (previousRule, rule) {
+  const isMergeableRulePair = (
+    previousRule?.type === 'rule' &&
+    previousRule.selectors?.length &&
+    rule.type === 'rule' &&
+    rule.selectors?.length
+  );
+  if (!isMergeableRulePair) {
+    return null;
+  }
+  const previousBody = partitionRuleBody(previousRule.declarations);
+  const currentBody = partitionRuleBody(rule.declarations);
+  if (!previousBody.plainDeclarations.length || !currentBody.plainDeclarations.length) {
+    return null;
+  }
+  const previousNesting = nestedBlocksSignature(previousBody.nestedBlocks);
+  const currentNesting = nestedBlocksSignature(currentBody.nestedBlocks);
+  if (previousNesting === null || previousNesting !== currentNesting) {
+    return null;
+  }
+  const currentValueByProperty = new Map(
+    currentBody.plainDeclarations.map((declaration) => {
+      return [declaration.property, (declaration.value || '').trim()];
+    })
+  );
+  const previousIsRestated = previousBody.plainDeclarations.every((declaration) => {
+    return currentValueByProperty.get(declaration.property) === (declaration.value || '').trim();
+  });
+  // `all` rewrites every other property, so the later rule restating a value is
+  // no promise that it applies the same way once `all` has run.
+  const currentResetsEverything = currentValueByProperty.has('all');
+  if (!previousIsRestated || currentResetsEverything) {
+    return null;
+  }
+  const combinedSelectors = deduplicateSelectors([...previousRule.selectors, ...rule.selectors]);
+  if (previousBody.nestedBlocks.length && !selectorsShareSpecificity(combinedSelectors)) {
+    return null;
+  }
+  const restatedProperties = new Set(
+    previousBody.plainDeclarations.map((declaration) => {
+      return declaration.property;
+    })
+  );
+  const remainingDeclarations = currentBody.plainDeclarations.filter((declaration) => {
+    return !restatedProperties.has(declaration.property);
+  });
+  const merged = [{ ...previousRule, selectors: combinedSelectors }];
+  if (remainingDeclarations.length) {
+    merged.push({ ...rule, declarations: remainingDeclarations });
+  }
+  return merged;
+}
+
+/**
+ * Merges consecutive rules whose declarations are a subset of the following rule, combining their selectors and splitting out any extra declarations.
+ *
+ * @param  {Array} rules  The AST rule nodes to merge.
+ * @return {Array}        A new array of rules with declaration-compatible consecutive rules combined.
+ */
+function mergeByDeclarations (rules) {
+  const result = [];
+  for (const rule of rules) {
+    const merged = mergeRuleIntoPredecessor(result[result.length - 1], rule);
+    if (merged) {
+      result.pop();
+      result.push(...merged);
+      continue;
+    }
+    result.push(rule);
+  }
+  return result;
+}
+
+export {
+  mergeByDeclarations
+};

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
+};