@thejaredwilcurt/csslop 0.0.49 → 0.0.50

package/README.md

@@ -321,6 +321,5 @@ Two different cases:
    * Ensure arrow functions always take up at least 3 lines, with explicit returns when needed.
    * Always comment regex if used.
 1. After all other code edits, run `npm run lint` and ensure the linter passes.
-1. DO NOT, under any circumstance, run `npm run real` (it will kill actual humans)!
 1. When all done, run the `beep` command to alert me you finished.
 ```

package/package.json

@@ -2,7 +2,7 @@
   "name": "@thejaredwilcurt/csslop",
   "main": "index.js",
   "type": "module",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "description": "Experimental CSS minification",
   "scripts": {
     "prestart": "node ./scripts/pre/start.js",

package/src/declarations/border.js

@@ -3,8 +3,8 @@
  */
 
 import { splitTopLevelComponents } from '../parser/source-search.js';
+import { namedColors } from '../value/color/named.js';
 import { minifyValue } from '../value/minify.js';
-import { namedColors } from '../value/named-colors.js';
 import {
   collapseShorthandParts,
   hasSubstitutedParts

package/src/index.js

@@ -14,19 +14,19 @@ import {
 import { recordStylesheetResetProperties } from './declarations/reset-hazards.js';
 import { parse } from './parser/index.js';
 import { splitTopLevelCommaList } from './parser/source-search.js';
-import {
-  analyzePositionTryRules,
-  cleanPositionTryRules,
-  collectRuleMetadata,
-  filterUnusedPositionTry
-} from './position-try.js';
 import { preprocessDeclarationBlocks } from './preprocess.js';
 import { combineLanguageSelectors } from './rules/lang.js';
 import { normalizeRuleSelectors } from './rules/normalize.js';
 import {
   clearSelectorCaches,
   optimizeRuleList
-} from './rules/optimize.js';
+} from './rules/optimize/index.js';
+import {
+  analyzePositionTryRules,
+  cleanPositionTryRules,
+  collectRuleMetadata,
+  filterUnusedPositionTry
+} from './rules/position-try.js';
 import { combineLegacyAnySelectors } from './rules/selectors.js';
 import {
   removeRedundantLayerStatementSemicolon,

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

@@ -0,0 +1,113 @@
+/**
+ * @file Consolidates grouping at-rules by merging matching `@media` and `@layer` blocks, and drops the `@keyframes` that a later definition replaces.
+ */
+
+import {
+  normalizeLayerNames,
+  normalizeMedia
+} from '../normalize.js';
+
+/**
+ * Merges adjacent `@media` rules that share an identical normalized query string and deduplicates their child selector rules.
+ *
+ * @param  {Array}                  rules               The AST rule nodes to process.
+ * @param  {function(Array): Array} mergeSelectorRules  Callback to merge selector rules within each media block.
+ * @return {Array}                                      A new array of rules with consecutive identical `@media` blocks combined.
+ */
+function mergeMediaRules (rules, mergeSelectorRules) {
+  const mediaMap = new Map();
+  const result = [];
+  for (const rule of rules) {
+    if (rule.type === 'media') {
+      const normalizedQuery = normalizeMedia(rule.media);
+      if (mediaMap.has(normalizedQuery)) {
+        mediaMap.get(normalizedQuery).rules.push(...(rule.rules || []));
+      } else {
+        mediaMap.set(normalizedQuery, rule);
+        result.push(rule);
+      }
+    } else {
+      // Clearing a map replaces its storage, so an already empty one is left alone
+      if (rule.type !== 'whitespace' && mediaMap.size) {
+        mediaMap.clear();
+      }
+      result.push(rule);
+    }
+  }
+  for (const rule of result) {
+    if (rule.type === 'media' && rule.rules && rule.rules.length) {
+      rule.rules = mergeSelectorRules(rule.rules);
+    }
+  }
+  return result;
+}
+
+/**
+ * Removes duplicate `@keyframes` definitions, keeping only the last occurrence of each named animation.
+ *
+ * @param  {Array} rules  The AST rule nodes to deduplicate.
+ * @return {Array}        A new array of rules with earlier duplicate `@keyframes` removed.
+ */
+function deduplicateKeyframes (rules) {
+  const lastIndexByName = new Map();
+  for (let i = 0; i < rules.length; i++) {
+    if (rules[i].type === 'keyframes' && rules[i].name) {
+      lastIndexByName.set(rules[i].name, i);
+    }
+  }
+  return rules.filter((rule, index) => {
+    if (rule.type === 'keyframes' && rule.name) {
+      return lastIndexByName.get(rule.name) === index;
+    }
+    return true;
+  });
+}
+
+/**
+ * Merges `@layer` blocks with the same name by combining their child rules, deduplicates layer statements, and merges selector rules within each block.
+ *
+ * @param  {Array}                  rules               The AST rule nodes to process.
+ * @param  {function(Array): Array} mergeSelectorRules  Callback to merge selector rules within each layer block.
+ * @return {Array}                                      A new array of rules with same-name `@layer` blocks combined.
+ */
+function mergeLayerRules (rules, mergeSelectorRules) {
+  const layerBlockMap = new Map();
+  const layerStatementSeen = new Set();
+  const result = [];
+  for (const rule of rules) {
+    if (rule.type === 'layer') {
+      const layerName = normalizeLayerNames(rule.layer);
+      if (rule.rules && rule.rules.length > 0) {
+        if (layerName && layerBlockMap.has(layerName)) {
+          layerBlockMap.get(layerName).rules.push(...rule.rules);
+        } else {
+          if (layerName) {
+            layerBlockMap.set(layerName, rule);
+          }
+          result.push(rule);
+        }
+      } else {
+        if (!layerName || !layerStatementSeen.has(layerName)) {
+          if (layerName) {
+            layerStatementSeen.add(layerName);
+          }
+          result.push(rule);
+        }
+      }
+    } else {
+      result.push(rule);
+    }
+  }
+  for (const rule of result) {
+    if (rule.type === 'layer' && rule.rules && rule.rules.length) {
+      rule.rules = mergeSelectorRules(rule.rules);
+    }
+  }
+  return result;
+}
+
+export {
+  deduplicateKeyframes,
+  mergeLayerRules,
+  mergeMediaRules
+};

package/src/rules/optimize/declaration-writes.js

@@ -0,0 +1,70 @@
+/**
+ * @file Describes what a declaration writes to: whether it declares a property at all, which leaf properties it can override, and whether it is flagged important.
+ */
+
+import {
+  expandToLeafProperties,
+  getOverridesOf
+} from '../../declarations/config.js';
+
+/**
+ * The leaf properties each declared property can write to, computed on first
+ * use. The shorthand tables never change, so a property always expands the same
+ * way.
+ *
+ * @type {Map<string, Set<string>>}
+ */
+const overridablePropertiesByProperty = new Map();
+
+/**
+ * Expands a declared property into every leaf longhand it can write to,
+ * including the extras a shorthand resets beyond its own longhands. Two
+ * declarations can only override one another when these sets intersect, which
+ * is what makes `margin` conflict with `margin-top` but not with `color`.
+ *
+ * @param  {string} property  The declared property name.
+ * @return {Set}              The leaf property names the declaration writes to.
+ */
+function expandToOverridableProperties (property) {
+  const cachedProperties = overridablePropertiesByProperty.get(property);
+  if (cachedProperties) {
+    return cachedProperties;
+  }
+  const overridableProperties = new Set(expandToLeafProperties(property));
+  for (const resetProperty of getOverridesOf(property)) {
+    for (const leafProperty of expandToLeafProperties(resetProperty)) {
+      overridableProperties.add(leafProperty);
+    }
+  }
+  overridablePropertiesByProperty.set(property, overridableProperties);
+  return overridableProperties;
+}
+
+/**
+ * Reports whether an entry of a rule's body is a declaration whose standing in
+ * the cascade can be read off the property it writes. Anything else a body may
+ * hold, such as a nested rule, is never shadowed by a declaration beside it.
+ *
+ * @param  {object}  entry  An entry of a rule's declaration list.
+ * @return {boolean}        True when the entry is a property declaration.
+ */
+function isPropertyDeclaration (entry) {
+  return entry.type === 'declaration' && Boolean(entry.property);
+}
+
+/**
+ * Determines whether a declaration carries a trailing `!important` flag.
+ *
+ * @param  {object}  declaration  The AST declaration node.
+ * @return {boolean}              True when the declaration is important.
+ */
+function isImportantDeclaration (declaration) {
+  // A trailing !important suffix on the raw declaration value
+  return /!\s*important\s*$/i.test(declaration.rawValue || declaration.value || '');
+}
+
+export {
+  expandToOverridableProperties,
+  isImportantDeclaration,
+  isPropertyDeclaration
+};

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

@@ -0,0 +1,51 @@
+/**
+ * @file Detects and removes rules that produce no CSS output once minified.
+ */
+
+/**
+ * Determines whether a rule is effectively empty, containing no meaningful
+ * CSS output after minification. A rule is effectively empty when it has
+ * no declarations, or all of its entries are whitespace, non-important
+ * comments, or recursively empty nested rules.
+ *
+ * @param  {object}  rule  The AST rule node to evaluate.
+ * @return {boolean}       True if the rule produces no CSS output.
+ */
+function isRuleEffectivelyEmpty (rule) {
+  if (rule.type !== 'rule') {
+    return false;
+  }
+  const nonWhitespaceEntries = (rule.declarations || []).filter((declaration) => {
+    return declaration.type !== 'whitespace';
+  });
+  if (nonWhitespaceEntries.length === 0) {
+    return true;
+  }
+  return nonWhitespaceEntries.every((entry) => {
+    if (entry.type === 'comment') {
+      return !entry.comment?.startsWith('!');
+    }
+    if (entry.type === 'rule') {
+      return isRuleEffectivelyEmpty(entry);
+    }
+    return false;
+  });
+}
+
+/**
+ * Filters out effectively empty rules from the rules array, preventing
+ * empty rules from being nested into parent rules during later
+ * optimization passes and producing incorrect non-empty output.
+ *
+ * @param  {Array} rules  The AST rule nodes to filter.
+ * @return {Array}        A new array with effectively empty rules removed.
+ */
+function removeEmptyRules (rules) {
+  return rules.filter((rule) => {
+    return !isRuleEffectivelyEmpty(rule);
+  });
+}
+
+export {
+  removeEmptyRules
+};

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