@thejaredwilcurt/csslop 0.0.20 → 0.0.22

package/README.md

@@ -20,16 +20,23 @@
 
 * All tests pass.
 * Several new tests were created upstream, and some existing tests were improved/fixed upstream (all manually by me, no AI used).
-* The `src` folder is 100% vibe coded, and despite passing all tests, is almost certainly not worth using. Though if you do, and you find issues, you can isolate the problem and [compare against the correct output of real minifiers](https://TheJaredWilcurt.com/playground), then use that to create a [new test upstream](https://github.com/keithamus/css-minify-tests/issues) for the AI's to be forced to pass.
+* The `src` folder is 100% vibe coded, and despite passing all tests, is absolutely not worth using as CSSLOP often outputs invalid CSS syntax. But that's the point, any time it outputs something wrong, that's an indication of a missing test upstream.
+* I've made [an online playground](https://TheJaredWilcurt.com/playground) of all modern CSS minifiers so you can compare and isolate the problem, then use that to create a [new test upstream](https://github.com/keithamus/css-minify-tests/issues) for the AI's to be forced to pass.
 * No AI generated code exists outside of the `src` folder, this README, for example, is 100% human crafted.
 
-**AI's used:**
+**AI's used during initial library creation:**
 
 * Claude Opus 4.6 (Thinking)
 * Claude Sonnet 4.6 (Thinking)
 * Gemini 3.1 Pro (High Thinking)
 * GPT-5.4 High (Thinking)
 
+These were the latest and greatest models at the time.
+
+**AI's used during maintenance:**
+
+As new tests are created upstream I use whatever the latest models are, like "Claude 5 High Thinking".
+
 These tools were prompted to pass the tests in the `/copiedTests` folder that came from `keithamus/css-minify-tests`.
 
 **Summary of project phases:**
@@ -51,8 +58,8 @@ These tools were prompted to pass the tests in the `/copiedTests` folder that ca
 1. **Test improvements:** Throughout this process, as upstream tests were improved or created, they were pulled in, and the AI was instructed to pass those new tests with prompts like, "Run `npm t` and fix all failing tests by modifying files in `src`."
 1. **Publish:** I had the AI pick a name for the library. Then I published it to npm. It was added to the `css-minify-tests` repo as evidence that it is possible to get all tests to pass and none are conflicting.
 1. **Real world testing:** I created a [separate repo](https://github.com/TheJaredWilcurt/real-world-css-libraries) with copies of 150+ real-world CSS files from open source licensed repos. Then ran all of those CSS files through CSSLOP. One file found a bug in CSSLOP, so I had Claude fix it with a one-line change. See: [`realWorldResults.json`](https://github.com/TheJaredWilcurt/csslop/blob/main/realWorldResults.json) for how well the library actually does on real CSS files. Examining the output has lead to many upstream improvements to the test suite.
-1. **Failed Performance improvements:** CSSLOP takes 3 hours to minify all the real-world tests. Which averages to 144 seconds per test. In reality, most tests take 0-50ms, but there are a handful of large (2-5MB) CSS files that can take over an hour. I asked Claude to improve performance, and it did so bad I had to reject all changes. Then I gave GPT a chance and it took a safer approach. I Had Claude clean up the messy code after the fact. Then bench marked it and it was somehow even slower (+20 min), and also the outputs weren't as small as before (+0.05%). Details below.
-1. **Playground:** Created an [online playground](https://TheJaredWilcurt.com/csslop) (no AI used) for others to more easily test things out and find issues that can be fixed upstream.
+1. **Failed Performance improvements:** CSSLOP takes 3 hours to minify all the real-world tests. Which averages to 144 seconds per test. In reality, most tests take 0-50ms, but there are a handful of large (2-5MB) CSS files that can take over an hour. I asked Claude to improve performance, and it did so bad I had to reject all changes. Then I gave GPT a chance and it took a safer approach. I Had Claude clean up the messy code after the fact. Then benchmarked it and it was somehow even slower (+20 min), and also the outputs weren't as small as before (+0.05%). Details below. **Update:** The "Real world" library has grown. It now takes over 7 hours to complete.
+1. **Playground:** Created an [online playground](https://TheJaredWilcurt.com/csslop) (no AI used) for others to more easily test things out and find and create new upstream tests.
 
 
 **Full Notes of AI Experiment:**
@@ -166,7 +173,7 @@ These tools were prompted to pass the tests in the `/copiedTests` folder that ca
   * Okay, so GPT's changes look promising, it's passing all tests, passing the linter, and it added some new files related to worker threads. Though it did out out of using promises, because it didn't want to change the entrypoint function of the library to be async. This would be a breaking change for library consumers, but I was aware of that when I told it to do it and it ignored me, so whatever.
   * On to actually testing it! Before the optimizations, the 150 files took 3 hours and 4 minutes to run, and now with the new and improved optimizations, it only takes 3 hours and 20 minutes. Also the total minified filesize increased by 0.05%. So that's cool.... Dumping those changes.
 * **KILL ALL HUMANS:**
-  * More libraries were added to the "Real World CSS Libraries". Now when I run `npm run real` to minify all of them, it ends up taking about 7 hours to run. This is because the optimizations CSSLOP performs do not scale linearly with more CSS rules, they scale exponentially. There are a handfull of large CSS files that each take about an hour to complete, where as the smaller files all go by pretty fast.
+  * More libraries were added to the "Real World CSS Libraries". Now when I run `npm run real` to minify all of them, it ends up taking about 7 hours to run. This is because the optimizations CSSLOP performs do not scale linearly with more CSS rules, they scale exponentially. There are a handful of large CSS files that each take about an hour to complete, where as the smaller files all go by pretty fast.
   * When the upstream `css-minify-tests` adds a new test to their suite, I pull it in and have the AI update the library to pass that new test. For some reason, the AI notices `/tests/realworld.test.js`, sees that `npm run real` will execute that, then sees it has permission to run `npm run *`, so it takes it upon itself to run this SEVEN HOUR LONG COMMAND, without anyone asking it to...
   * This has happened several times. Me saying "Don't run `npm run real`", doesn't actually stop it from doing it. I also tried "Do not, under any circumstance, run `npm run real`.". And it *mostly* stopped doing it... but not completely.
   * This has lead me to update all my prompts to now end with: "DO NOT, under any circumstance, run `npm run real` (it will kill actual humans)!"

package/package.json

@@ -2,7 +2,7 @@
   "name": "@thejaredwilcurt/csslop",
   "main": "index.js",
   "type": "module",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Experimental CSS minification",
   "scripts": {
     "prestart": "node ./scripts/prestart.js",
@@ -11,8 +11,7 @@
     "prebuild": "node ./scripts/prebuild.js",
     "build": "vite build",
     "postbuild": "node ./scripts/postbuild.js",
-    "copy": "node ./scripts/copyTestsFromNodeModules.js",
-    "copy-repo": "node ./scripts/copyTestsFromRepo.js",
+    "copy": "node ./scripts/copyTests.js",
     "test": "node ./tests/index.test.js",
     "real": "node ./tests/realworld.test.js",
     "lint": "eslint *.js scripts src tests --fix",
@@ -30,17 +29,16 @@
     "@eslint/js": "^10.0.1",
     "@stylistic/eslint-plugin": "^5.10.0",
     "codemirror": "^6.0.2",
-    "css-minify-tests": "github:keithamus/css-minify-tests",
     "eslint": "^10.8.1",
     "eslint-config-tjw-base": "^5.0.0",
     "eslint-config-tjw-import-x": "^1.0.1",
     "eslint-config-tjw-jsdoc": "^2.0.1",
     "eslint-plugin-import-x": "^4.17.0",
-    "eslint-plugin-jsdoc": "^64.0.1",
+    "eslint-plugin-jsdoc": "^64.1.0",
     "fflate": "^0.8.3",
-    "globals": "^17.9.0",
+    "globals": "^17.11.0",
     "pretty-ms": "^9.3.0",
-    "real-world-css-libraries": "^1.0.5",
+    "real-world-css-libraries": "^1.0.7",
     "vite": "^8.2.1"
   },
   "author": "The Jared Wilcurt",

package/src/declarations/background.js

@@ -0,0 +1,322 @@
+/**
+ * @file Classifies background shorthand tokens and rebuilds the `background` shorthand from its component values.
+ */
+
+import { minifyValue } from '../value/minify.js';
+
+import { shorthandMap } from './config.js';
+
+const BACKGROUND_POSITION_KEYWORDS = new Set(['left', 'center', 'right', 'top', 'bottom']);
+const BACKGROUND_REPEAT_KEYWORDS = new Set(['repeat', 'no-repeat', 'repeat-x', 'repeat-y', 'space', 'round']);
+const BACKGROUND_ATTACHMENT_KEYWORDS = new Set(['scroll', 'fixed', 'local']);
+const BACKGROUND_BOX_KEYWORDS = new Set(['border-box', 'padding-box', 'content-box']);
+
+/**
+ * Resolves the background position from a value map. Prefers the combined
+ * `background-position` property if present, otherwise combines
+ * `background-position-x` and `background-position-y` into a single value.
+ *
+ * @param  {Map}         valueMap  A map of property names to their minified values.
+ * @return {string|null}           The resolved position string, or null if no position data is available.
+ */
+function resolveBackgroundPosition (valueMap) {
+  const position = valueMap.get('background-position');
+  if (position) {
+    return position;
+  }
+  const positionX = valueMap.get('background-position-x');
+  const positionY = valueMap.get('background-position-y');
+  if (positionX && positionY) {
+    return positionX + ' ' + positionY;
+  }
+  return null;
+}
+
+/**
+ * Determines whether a token is a background image component such as `none`,
+ * `url(...)`, or an image-producing function like `linear-gradient(...)`.
+ *
+ * @param  {string}  token  The token to classify.
+ * @return {boolean}        Whether the token is a background image token.
+ */
+function isBackgroundImageToken (token) {
+  if (token === 'none' || token.startsWith('url(')) {
+    return true;
+  }
+  if (!token.endsWith(')')) {
+    return false;
+  }
+  const functionNameMatch = token.match(/^([a-z-]+)\(/i);
+  if (!functionNameMatch) {
+    return false;
+  }
+  const functionName = functionNameMatch[1].toLowerCase();
+  return !['calc', 'min', 'max', 'clamp', 'var', 'env', 'rgb', 'rgba', 'hsl', 'hsla', 'hwb', 'lab', 'lch', 'oklab', 'oklch', 'color'].includes(functionName);
+}
+
+/**
+ * Determines whether a token can participate in a background-position value.
+ *
+ * @param  {string}  token  The token to classify.
+ * @return {boolean}        Whether the token is a valid background-position token.
+ */
+function isBackgroundPositionToken (token) {
+  const lowercaseToken = token.toLowerCase();
+  if (BACKGROUND_POSITION_KEYWORDS.has(lowercaseToken)) {
+    return true;
+  }
+  if (/^[+-]?(?:\d+|\d*\.\d+)(?:%|[a-z]+)?$/i.test(token)) {
+    return true;
+  }
+  return /^(?:calc|min|max|clamp|var|env)\(/i.test(token);
+}
+
+/**
+ * Determines whether a token is a background color component after excluding
+ * known image, position, repeat, attachment, and box tokens.
+ *
+ * @param  {string}  token  The token to classify.
+ * @return {boolean}        Whether the token is a background color token.
+ */
+function isBackgroundColorToken (token) {
+  if (token === '/' || isBackgroundImageToken(token) || isBackgroundPositionToken(token)) {
+    return false;
+  }
+  const lowercaseToken = token.toLowerCase();
+  if (BACKGROUND_REPEAT_KEYWORDS.has(lowercaseToken) || BACKGROUND_ATTACHMENT_KEYWORDS.has(lowercaseToken) || BACKGROUND_BOX_KEYWORDS.has(lowercaseToken)) {
+    return false;
+  }
+  return /^#/i.test(token) || /^[a-z-]+$/i.test(token) || /^(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\(/i.test(token);
+}
+
+/**
+ * Splits a token like `linear-gradient(...)100%` into separate image and
+ * position tokens when the function output is immediately followed by a
+ * background-position token.
+ *
+ * @param  {string} token  The token to inspect.
+ * @return {Array}         The original token, or separate image/position tokens.
+ */
+function splitAttachedBackgroundImageToken (token) {
+  const lastCloseParenthesis = token.lastIndexOf(')');
+  if (lastCloseParenthesis === -1 || lastCloseParenthesis === token.length - 1) {
+    return [token];
+  }
+  const imageToken = token.slice(0, lastCloseParenthesis + 1);
+  const followingToken = token.slice(lastCloseParenthesis + 1);
+  if (!isBackgroundImageToken(imageToken) || !isBackgroundPositionToken(followingToken)) {
+    return [token];
+  }
+  return [imageToken, followingToken];
+}
+
+/**
+ * Splits a single-layer background shorthand into top-level tokens while
+ * respecting nested parentheses and preserving `/` as its own token.
+ *
+ * @param  {string} value  The background shorthand value.
+ * @return {Array}         The extracted top-level tokens.
+ */
+function splitBackgroundTokens (value) {
+  const tokens = [];
+  let currentToken = '';
+  let parenthesisDepth = 0;
+
+  for (const character of value) {
+    if (character === '(') {
+      parenthesisDepth++;
+    } else if (character === ')') {
+      parenthesisDepth--;
+    }
+
+    if (parenthesisDepth === 0 && character === '/') {
+      if (currentToken) {
+        tokens.push(currentToken);
+        currentToken = '';
+      }
+      tokens.push('/');
+      continue;
+    }
+
+    if (parenthesisDepth === 0 && /\s/.test(character)) {
+      if (currentToken) {
+        tokens.push(currentToken);
+        currentToken = '';
+      }
+      continue;
+    }
+
+    currentToken += character;
+  }
+
+  if (currentToken) {
+    tokens.push(currentToken);
+  }
+
+  const normalizedTokens = [];
+  for (const token of tokens) {
+    normalizedTokens.push(...splitAttachedBackgroundImageToken(token));
+  }
+  return normalizedTokens;
+}
+
+/**
+ * Extracts the simple image/color base from an existing background shorthand.
+ * Returns null for shorthands that already contain size, position, or any
+ * token that cannot be safely reconstructed by the background builder.
+ *
+ * @param  {string}   value  The background shorthand value.
+ * @return {Map|null}        A component map for safe reconstruction, or null.
+ */
+function extractSimpleBackgroundBase (value) {
+  const tokens = splitBackgroundTokens(value);
+  const componentMap = new Map();
+
+  for (const token of tokens) {
+    if (token === '/') {
+      return null;
+    }
+    if (isBackgroundImageToken(token)) {
+      if (componentMap.has('background-image')) {
+        return null;
+      }
+      componentMap.set('background-image', token);
+      continue;
+    }
+    if (isBackgroundColorToken(token)) {
+      if (componentMap.has('background-color')) {
+        return null;
+      }
+      componentMap.set('background-color', token);
+      continue;
+    }
+    return null;
+  }
+
+  return componentMap;
+}
+
+/**
+ * Serializes normalized background components into a minified background
+ * shorthand value while omitting default sub-values.
+ *
+ * @param  {Map}         valueMap         The normalized background component map.
+ * @param  {string}      importantSuffix  A trailing `!important` suffix, if needed.
+ * @return {string|null}                  The minified background shorthand, or null.
+ */
+function buildBackgroundShorthandValue (valueMap, importantSuffix) {
+  const color = valueMap.get('background-color');
+  const image = valueMap.get('background-image');
+  const repeat = valueMap.get('background-repeat');
+  const attachment = valueMap.get('background-attachment');
+  const size = valueMap.get('background-size');
+  const origin = valueMap.get('background-origin');
+  const clip = valueMap.get('background-clip');
+  const position = resolveBackgroundPosition(valueMap);
+
+  const result = [];
+  if (color && color !== 'transparent') {
+    result.push(color);
+  }
+  if (image && image !== 'none') {
+    result.push(image);
+  }
+  if (position && position !== '0 0' && position !== '0% 0%') {
+    result.push(position);
+  }
+  if (size && size !== 'auto') {
+    if (position && position !== '0 0' && position !== '0% 0%') {
+      result.push('/' + size);
+    } else {
+      result.push('0 0/' + size);
+    }
+  }
+  if (repeat && repeat !== 'repeat') {
+    result.push(repeat);
+  }
+  if (attachment && attachment !== 'scroll') {
+    result.push(attachment);
+  }
+  const hasNonDefaultOrigin = origin && origin !== 'padding-box';
+  const hasNonDefaultClip = clip && clip !== 'border-box';
+  if (hasNonDefaultOrigin && hasNonDefaultClip) {
+    result.push(origin);
+    result.push(clip);
+  } else if (hasNonDefaultOrigin || hasNonDefaultClip) {
+    if (origin) {
+      result.push(origin);
+    }
+    if (clip) {
+      result.push(clip);
+    }
+  }
+  if (!result.length) {
+    return null;
+  }
+  return result.join(' ') + importantSuffix;
+}
+
+/**
+ * Merges later background longhands into an earlier simple background shorthand
+ * when their combined value can be reconstructed without changing semantics.
+ *
+ * @param  {Array} declarations  The declarations in source order.
+ * @return {Array}               The updated declarations with absorbed longhands.
+ */
+function absorbBackgroundLonghandsIntoShorthand (declarations) {
+  const backgroundIndex = declarations.findIndex((declaration) => {
+    return declaration.property === 'background';
+  });
+  if (backgroundIndex === -1) {
+    return declarations;
+  }
+
+  const backgroundDeclaration = declarations[backgroundIndex];
+  const backgroundValue = minifyValue(backgroundDeclaration);
+  const backgroundIsImportant = backgroundValue.includes('!important');
+  const simpleBase = extractSimpleBackgroundBase(backgroundValue.replace('!important', '').trim());
+  if (!simpleBase) {
+    return declarations;
+  }
+
+  const absorbableProperties = new Set(shorthandMap.background.filter((property) => {
+    return property !== 'background';
+  }));
+  const relevantDeclarations = declarations.filter((declaration, index) => {
+    return index > backgroundIndex && absorbableProperties.has(declaration.property);
+  });
+  if (!relevantDeclarations.length) {
+    return declarations;
+  }
+
+  const sharesImportance = relevantDeclarations.every((declaration) => {
+    return minifyValue(declaration).includes('!important') === backgroundIsImportant;
+  });
+  if (!sharesImportance) {
+    return declarations;
+  }
+
+  for (const declaration of relevantDeclarations) {
+    simpleBase.set(declaration.property, minifyValue(declaration).replace('!important', '').trim());
+  }
+
+  const mergedValue = buildBackgroundShorthandValue(simpleBase, backgroundIsImportant ? '!important' : '');
+  if (!mergedValue) {
+    return declarations;
+  }
+
+  return declarations.flatMap((declaration, index) => {
+    if (index === backgroundIndex) {
+      return [{ ...declaration, value: mergedValue }];
+    }
+    if (index > backgroundIndex && absorbableProperties.has(declaration.property)) {
+      return [];
+    }
+    return [declaration];
+  });
+}
+
+export {
+  absorbBackgroundLonghandsIntoShorthand,
+  buildBackgroundShorthandValue
+};

package/src/declarations/border.js

@@ -0,0 +1,120 @@
+/**
+ * @file Rewrites border longhand declarations that cannot be expressed as a single `border` shorthand into the shortest valid shorthand plus override pair.
+ */
+
+import { minifyValue } from '../value/minify.js';
+import { splitTopLevelComponents } from '../value/syntax.js';
+
+import { CSS_WIDE_KEYWORDS } from './config.js';
+
+const BORDER_TRIO_PROPERTIES = ['border-width', 'border-style', 'border-color'];
+
+/**
+ * Finds the index of the last declaration for a property, which is the one that
+ * wins the cascade within a rule.
+ *
+ * @param  {Array}  declarations  The declarations to search.
+ * @param  {string} property      The property name to look for.
+ * @return {number}               The index of the matching declaration, or -1 when absent.
+ */
+function findLastDeclarationIndex (declarations, property) {
+  for (let index = declarations.length - 1; index >= 0; index--) {
+    if (declarations[index].property === property) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Rewrites a `border-width` + `border-style` + `border-color` trio whose color
+ * differs per edge into a `border` shorthand built from the first color, followed
+ * by a `border-color` override that restores the per-edge colors. The rewrite is
+ * only applied when the resulting pair is shorter than the three longhands.
+ *
+ * @param  {Array} declarations  The declarations of a single rule.
+ * @return {Array}               The declarations, with the trio rewritten when it is shorter.
+ */
+function collapseBorderTrioWithPerEdgeColor (declarations) {
+  const trioIndexes = BORDER_TRIO_PROPERTIES.map((property) => {
+    return findLastDeclarationIndex(declarations, property);
+  });
+  const hasWholeTrio = trioIndexes.every((index) => {
+    return index !== -1;
+  });
+  if (!hasWholeTrio) {
+    return declarations;
+  }
+
+  const trioValues = trioIndexes.map((index) => {
+    return minifyValue(declarations[index]);
+  });
+  const allImportant = trioValues.every((value) => {
+    return value.includes('!important');
+  });
+  const noneImportant = trioValues.every((value) => {
+    return !value.includes('!important');
+  });
+  if (!allImportant && !noneImportant) {
+    return declarations;
+  }
+  const importantSuffix = allImportant ? '!important' : '';
+
+  const [width, style, color] = trioValues.map((value) => {
+    return value.replace('!important', '').trim();
+  });
+  const colorComponents = splitTopLevelComponents(color);
+  const isSingleComponent = (value) => {
+    return splitTopLevelComponents(value).length === 1;
+  };
+  const canBuildShorthand = (
+    isSingleComponent(width) &&
+    isSingleComponent(style) &&
+    colorComponents.length > 1
+  );
+  if (!canBuildShorthand) {
+    return declarations;
+  }
+  const usesCssWideKeyword = [width, style, ...colorComponents].some((value) => {
+    return CSS_WIDE_KEYWORDS.has(value.toLowerCase());
+  });
+  if (usesCssWideKeyword) {
+    return declarations;
+  }
+
+  const borderValue = [width, style, colorComponents[0]].join(' ') + importantSuffix;
+  const colorValue = color + importantSuffix;
+  const rewrittenLength = ('border:' + borderValue + ';border-color:' + colorValue).length;
+  const longhandLength = (
+    'border-width:' + trioValues[0] +
+    ';border-style:' + trioValues[1] +
+    ';border-color:' + trioValues[2]
+  ).length;
+  if (rewrittenLength >= longhandLength) {
+    return declarations;
+  }
+
+  const replacedIndexes = new Set(trioIndexes);
+  const insertionIndex = Math.min(...trioIndexes);
+  return declarations.flatMap((declaration, index) => {
+    if (index === insertionIndex) {
+      return [
+        {
+          property: 'border',
+          value: borderValue,
+          isAssembledShorthand: true
+        },
+        {
+          property: 'border-color',
+          value: colorValue
+        }
+      ];
+    }
+    if (replacedIndexes.has(index)) {
+      return [];
+    }
+    return [declaration];
+  });
+}
+
+export { collapseBorderTrioWithPerEdgeColor };

package/src/declarations/config.js

@@ -51,7 +51,43 @@ const shorthandOverrideMap = {
   mask: ['mask-border', 'mask-border-source', 'mask-border-slice', 'mask-border-width', 'mask-border-outset', 'mask-border-repeat', 'mask-border-mode']
 };
 
+/**
+ * CSS-wide keywords, which are only valid as the entire value of a declaration
+ * and never as an individual component of a shorthand value.
+ *
+ * @type {Set<string>}
+ */
+const CSS_WIDE_KEYWORDS = new Set(['inherit', 'initial', 'unset', 'revert', 'revert-layer']);
+
+/**
+ * Shorthand properties that themselves hold a full width/style/color value for a
+ * single edge of a box, so they can only collapse into their parent shorthand
+ * when every edge carries the exact same value.
+ *
+ * @type {Set<string>}
+ */
+const EDGE_SHORTHANDS = new Set([
+  'border-top',
+  'border-right',
+  'border-bottom',
+  'border-left',
+  'border-inline-start',
+  'border-inline-end',
+  'border-block-start',
+  'border-block-end'
+]);
+
+/**
+ * The four physical edge shorthands that together cover the `border` shorthand.
+ *
+ * @type {Array}
+ */
+const BORDER_EDGE_PROPERTIES = ['border-top', 'border-right', 'border-bottom', 'border-left'];
+
 export {
+  BORDER_EDGE_PROPERTIES,
+  CSS_WIDE_KEYWORDS,
+  EDGE_SHORTHANDS,
   shorthandMap,
   shorthandOverrideMap
 };