@thejaredwilcurt/csslop 0.0.49 → 0.0.50

package/src/rules/optimize/override-index.js

@@ -0,0 +1,264 @@
+/**
+ * @file Indexes which properties each rule writes to and how strongly, so a merge can ask whether moving declarations past later rules would change the cascade.
+ */
+
+import { isCustomProperty } from '../../utilities.js';
+
+import { expandToOverridableProperties } from './declaration-writes.js';
+import {
+  addSpecificity,
+  compareSpecificity,
+  maximumRuleSpecificity,
+  minimumRuleSpecificity
+} from './specificity.js';
+
+/**
+ * The property that rewrites every other standard property, and so conflicts
+ * with any declaration it is ordered against.
+ *
+ * @type {string}
+ */
+const RESET_ALL_PROPERTY = 'all';
+
+/**
+ * Index key standing for "declares anything at all", used to order a rule that
+ * sets `all` against every other declaration.
+ *
+ * @type {symbol}
+ */
+const ANY_PROPERTY = Symbol('any property');
+
+/**
+ * @typedef  {object}  RuleWriteProfile
+ * @property {Map}     specificityByProperty   The strongest specificity each leaf property is written with.
+ * @property {Array}   weakestSpecificity      The weakest specificity the rule's declarations are applied with.
+ * @property {Array}   strongestSpecificity    The strongest specificity anything in the rule is written with.
+ * @property {boolean} writesStandardProperty  Whether the rule writes any property other than a custom property.
+ */
+
+/**
+ * Notes in a profile that a leaf property is written with a specificity,
+ * keeping only the strongest specificity seen for it.
+ *
+ * @param {RuleWriteProfile} profile      The profile to extend.
+ * @param {string}           property     The leaf property name.
+ * @param {Array}            specificity  The specificity the property is written with.
+ */
+function addWrittenProperty (profile, property, specificity) {
+  const strongestSoFar = profile.specificityByProperty.get(property);
+  if (!strongestSoFar || compareSpecificity(specificity, strongestSoFar) > 0) {
+    profile.specificityByProperty.set(property, specificity);
+  }
+  if (compareSpecificity(specificity, profile.strongestSpecificity) > 0) {
+    profile.strongestSpecificity = specificity;
+  }
+  profile.writesStandardProperty = profile.writesStandardProperty || !isCustomProperty(property);
+}
+
+/**
+ * Adds every leaf property a rule's declarations write to into a profile,
+ * descending into nested rules, whose declarations only ever match through the
+ * parent and so carry the specificity of both selectors.
+ *
+ * @param {RuleWriteProfile} profile      The profile to extend.
+ * @param {object}           rule         The AST rule node to read declarations from.
+ * @param {Array}            specificity  The specificity the rule's own declarations apply with.
+ */
+function addWrittenProperties (profile, rule, specificity) {
+  for (const declaration of rule.declarations || []) {
+    if (declaration.type === 'rule') {
+      const nestedSpecificity = addSpecificity(specificity, maximumRuleSpecificity(declaration.selectors));
+      addWrittenProperties(profile, declaration, nestedSpecificity);
+    } else if (declaration.type === 'declaration' && declaration.property) {
+      for (const leafProperty of expandToOverridableProperties(declaration.property)) {
+        addWrittenProperty(profile, leafProperty, specificity);
+      }
+    }
+  }
+}
+
+/**
+ * Summarizes which properties a rule writes to and how strongly, which is
+ * everything the cascade needs to know about a rule to decide whether it may be
+ * reordered against another one.
+ *
+ * @param  {object}           rule  The AST rule node.
+ * @return {RuleWriteProfile}       The rule's write profile.
+ */
+function buildRuleWriteProfile (rule) {
+  const profile = {
+    specificityByProperty: new Map(),
+    weakestSpecificity: minimumRuleSpecificity(rule.selectors),
+    strongestSpecificity: [0, 0, 0],
+    writesStandardProperty: false
+  };
+  addWrittenProperties(profile, rule, maximumRuleSpecificity(rule.selectors));
+  return profile;
+}
+
+/**
+ * Folds one rule's writes into another's profile, which is how a profile stays
+ * current after a merge appends declarations to a rule. Both rules share the
+ * same selectors, so the absorbed writes keep their recorded specificity.
+ *
+ * @param {RuleWriteProfile} profile         The profile of the rule that grew.
+ * @param {RuleWriteProfile} absorbedWrites  The profile of the rule whose declarations were appended.
+ */
+function absorbWriteProfile (profile, absorbedWrites) {
+  for (const [property, specificity] of absorbedWrites.specificityByProperty) {
+    addWrittenProperty(profile, property, specificity);
+  }
+}
+
+/**
+ * Tracks which properties each rule writes to and where it sits, so that a
+ * merge can ask whether anything after a position could override the
+ * declarations it wants to move, instead of rescanning the stylesheet once per
+ * merge.
+ *
+ * Entries for a property are appended in increasing position order, and each
+ * new entry discards the earlier ones it dominates, since a declaration that is
+ * both later and at least as specific blocks everything a weaker, earlier one
+ * would. What remains is a list whose specificity strictly decreases as
+ * position grows, so the first entry past a queried position is also the
+ * strongest one past it.
+ *
+ * @param  {Map}    profileByRule  The write profiles already built for rules, shared by every pass of one merge.
+ * @return {object}                An index exposing `recordRule` and `blocksRelocation`.
+ */
+function createOverrideIndex (profileByRule) {
+  const entriesByProperty = new Map();
+
+  /**
+   * Records that a property is written at a position with a given specificity.
+   *
+   * @param {string|symbol} property     The leaf property name, or an index key.
+   * @param {number}        position     The slot the writing rule occupies.
+   * @param {Array}         specificity  The specificity the declaration applies with.
+   */
+  function addEntry (property, position, specificity) {
+    let entries = entriesByProperty.get(property);
+    if (!entries) {
+      entries = [];
+      entriesByProperty.set(property, entries);
+    }
+    while (entries.length && compareSpecificity(entries[entries.length - 1].specificity, specificity) <= 0) {
+      entries.pop();
+    }
+    entries.push({ position, specificity });
+  }
+
+  /**
+   * Whether some rule after a position writes to a property with at least a
+   * given specificity, and could therefore win the cascade against it.
+   *
+   * @param  {string|symbol} property     The leaf property name, or an index key.
+   * @param  {number}        position     The position to search after.
+   * @param  {Array}         specificity  The specificity to compare against.
+   * @return {boolean}                    True when a later rule could override the property.
+   */
+  function hasStrongerEntryAfter (property, position, specificity) {
+    const entries = entriesByProperty.get(property);
+    if (!entries) {
+      return false;
+    }
+    let low = 0;
+    let high = entries.length;
+    while (low < high) {
+      const middle = Math.floor((low + high) / 2);
+      if (entries[middle].position > position) {
+        high = middle;
+      } else {
+        low = middle + 1;
+      }
+    }
+    if (low === entries.length) {
+      return false;
+    }
+    return compareSpecificity(entries[low].specificity, specificity) >= 0;
+  }
+
+  /**
+   * Returns a rule's write profile, building it the first time it is needed.
+   * Rules only ever grow here, by absorbing another rule's declarations, and
+   * `absorbRule` folds those into the profile, so a profile stays valid for
+   * every pass of the merge.
+   *
+   * @param  {object}           rule  The AST rule node.
+   * @return {RuleWriteProfile}       The rule's write profile.
+   */
+  function getWriteProfile (rule) {
+    let profile = profileByRule.get(rule);
+    if (!profile) {
+      profile = buildRuleWriteProfile(rule);
+      profileByRule.set(rule, profile);
+    }
+    return profile;
+  }
+
+  /**
+   * Records every property a rule writes to at the position it occupies.
+   *
+   * @param {object} rule      The AST rule node.
+   * @param {number} position  The slot the rule occupies.
+   */
+  function recordRule (rule, position) {
+    const profile = getWriteProfile(rule);
+    if (!profile.specificityByProperty.size) {
+      return;
+    }
+    for (const [property, specificity] of profile.specificityByProperty) {
+      addEntry(property, position, specificity);
+    }
+    addEntry(ANY_PROPERTY, position, profile.strongestSpecificity);
+  }
+
+  /**
+   * Folds a rule's writes into the rule that just absorbed its declarations, so
+   * the grown rule is treated as writing to both sets of properties.
+   *
+   * @param {object} rule          The rule that grew.
+   * @param {object} absorbedRule  The rule whose declarations were appended to it.
+   */
+  function absorbRule (rule, absorbedRule) {
+    absorbWriteProfile(getWriteProfile(rule), getWriteProfile(absorbedRule));
+  }
+
+  /**
+   * Whether moving a rule's declarations past everything recorded after a
+   * position would change which declaration wins the cascade. Only a rule that
+   * is strictly less specific is guaranteed to lose either way, so anything of
+   * equal or greater specificity that writes to the same properties blocks the
+   * move.
+   *
+   * @param  {object}  movingRule     The rule whose declarations would relocate.
+   * @param  {number}  afterPosition  The position the declarations would move across.
+   * @return {boolean}                True when the relocation is unsafe.
+   */
+  function blocksRelocation (movingRule, afterPosition) {
+    const profile = getWriteProfile(movingRule);
+    const specificity = profile.weakestSpecificity;
+    for (const property of profile.specificityByProperty.keys()) {
+      if (hasStrongerEntryAfter(property, afterPosition, specificity)) {
+        return true;
+      }
+    }
+    if (profile.writesStandardProperty && hasStrongerEntryAfter(RESET_ALL_PROPERTY, afterPosition, specificity)) {
+      return true;
+    }
+    return (
+      profile.specificityByProperty.has(RESET_ALL_PROPERTY) &&
+      hasStrongerEntryAfter(ANY_PROPERTY, afterPosition, specificity)
+    );
+  }
+
+  return {
+    absorbRule,
+    blocksRelocation,
+    recordRule
+  };
+}
+
+export {
+  createOverrideIndex
+};

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