html-minifier 4.0.0 → 5.0.0

package/src/lib/unused-css.js

@@ -0,0 +1,499 @@
+/**
+ * Unused-CSS removal
+ */
+
+import { findTagEnd, hashContent } from './utils.js';
+
+// Attributes whose values name elements by ID or hold space-separated ID lists
+const idReferenceAttributes = new Set([
+  'aria-activedescendant',
+  'aria-controls',
+  'aria-describedby',
+  'aria-details',
+  'aria-errormessage',
+  'aria-flowto',
+  'aria-labelledby',
+  'aria-owns',
+  'commandfor',
+  'contextmenu',
+  'for',
+  'form',
+  'headers',
+  'itemref',
+  'list',
+  'popovertarget'
+]);
+
+// Attributes whose value may be a same-document fragment URL (`#main`). `:target`
+// rules and SVG sprite references (`<use href="#icon">`) rest on these, so the ID
+// they name counts as used.
+const fragmentReferenceAttributes = new Set([
+  'action',
+  'cite',
+  'data',
+  'formaction',
+  'href',
+  'poster',
+  'src',
+  'usemap',
+  'xlink:href'
+]);
+
+const attributePattern = /(?:^|[\s/])([-\w:.]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
+const identifierPattern = /--[\w-]*|-?[A-Za-z_][\w-]*/g;
+// SVG paints and filters reach elements by ID through `url(#gradient)`, in
+// presentation attributes as well as in `style`
+const fragmentURLPattern = /url\(\s*['"]?#([^)'"\s]+)/gi;
+// Class names routinely carry characters that end a CSS identifier (`md:flex`,
+// `w-1/2`, `p-[3px]`), so scripts and `data-*` values contribute whole tokens
+// besides identifiers; quoted strings are where scripts keep such names
+const stringLiteralPattern = /'((?:[^'\\\n]|\\.)*)'|"((?:[^"\\\n]|\\.)*)"|`((?:[^`\\]|\\.)*)`/g;
+
+// CSS identifiers may contain escapes (`.md\:flex`, `.w-1\/2`), which have to be
+// resolved before comparing them against the plain tokens found in the markup. A
+// symbol may follow another name (`p.note`, `.a.b`); matches outside selectors
+// (`#fff`, `a.png`) are harmless, as only selectors are checked against the list.
+const cssIdentifierPattern = /(?<!\\)[.#]((?:[-_a-zA-Z]|\\[0-9a-fA-F]{1,6}[ \t\n]?|\\[^\n0-9a-fA-F])(?:[-\w]|\\[0-9a-fA-F]{1,6}[ \t\n]?|\\[^\n0-9a-fA-F])*)/g;
+// `unusedSymbols` also drops `@keyframes` and `@counter-style` rules by name, so any
+// name used there is off limits even when no element carries it as a class or ID
+const reservedAtRulePattern = /@(?:-\w+-)?(?:keyframes|counter-style)\s+(-?[_a-zA-Z][\w-]*)/gi;
+const escapePattern = /\\(?:([0-9a-fA-F]{1,6})[ \t\n]?|(.))/g;
+// Run over case-folded markup; matches inside comments and scripts only add names
+const startTagPattern = /<([a-z][^\s/>]*)/g;
+
+/**
+ * Resolve CSS escape sequences in an identifier.
+ * @param {string} identifier
+ * @returns {string}
+ */
+function unescapeIdentifier(identifier) {
+  if (identifier.indexOf('\\') === -1) {
+    return identifier;
+  }
+  return identifier.replace(escapePattern, (_match, hex, literal) => {
+    if (!hex) {
+      return literal;
+    }
+    // Per CSS Syntax spec, a null, surrogate, or out-of-range escape becomes `U+FFFD`
+    const code = parseInt(hex, 16);
+    return (code === 0 || code > 0x10FFFF || (code >= 0xD800 && code <= 0xDFFF))
+      ? '\uFFFD'
+      : String.fromCodePoint(code);
+  });
+}
+
+/**
+ * Lowercase for matching without disturbing offsets.
+ *
+ * `toLowerCase()` can change a string's length—U+0130 becomes two code units—which
+ * would misalign every offset taken from the result. Folding just ASCII preserves
+ * length, and tag names are ASCII anyway.
+ *
+ * @param {string} text
+ * @returns {string} Same length as `text`
+ */
+function foldCase(text) {
+  const lowercased = text.toLowerCase();
+  return lowercased.length === text.length
+    ? lowercased
+    : text.replace(/[A-Z]+/g, uppercase => uppercase.toLowerCase());
+}
+
+/**
+ * Locate the bodies of a raw-text element (`style`, `script`).
+ *
+ * Scanning beats one regular expression here: A pattern permissive enough for the
+ * end tags browsers accept (`</script\t\n bar>`, `</script/>`) backtracks
+ * quadratically over a document full of near-matches, and bounding it would make
+ * long start tags go unrecognized.
+ *
+ * @param {string} haystack - Case-folded markup, as returned by `foldCase`
+ * @param {string} tagName - Lowercase element name
+ * @returns {Array<{start: number, bodyStart: number, bodyEnd: number, end: number, closed: boolean}>}
+ */
+function findRawTextElements(haystack, tagName) {
+  /** @type {Array<{start: number, bodyStart: number, bodyEnd: number, end: number, closed: boolean}>} */
+  const found = [];
+  const openTag = '<' + tagName;
+  const closeTag = '</' + tagName;
+  // A tag name ends at whitespace, a slash, or the closing bracket—so `<styles>`
+  // and `</scriptfoo>` name different elements and must not match
+  const endsName = (/** @type {string} */ character) =>
+    character === '' || character === '/' || character === '>' || /\s/.test(character);
+
+  let cursor = 0;
+  for (;;) {
+    const start = haystack.indexOf(openTag, cursor);
+    if (start === -1) {
+      break;
+    }
+    if (!endsName(haystack.charAt(start + openTag.length))) {
+      cursor = start + openTag.length;
+      continue;
+    }
+    // A quoted attribute value may hold a `>`, so the tag ends where the parser
+    // says it does, not at the next bracket
+    const startTagEnd = findTagEnd(haystack, start + openTag.length);
+    if (startTagEnd === -1) {
+      break;
+    }
+
+    const bodyStart = startTagEnd + 1;
+    let search = bodyStart;
+    let bodyEnd = -1;
+    let end = -1;
+    for (;;) {
+      const candidate = haystack.indexOf(closeTag, search);
+      if (candidate === -1) {
+        break;
+      }
+      if (endsName(haystack.charAt(candidate + closeTag.length))) {
+        const closeEnd = findTagEnd(haystack, candidate + closeTag.length);
+        if (closeEnd !== -1) {
+          bodyEnd = candidate;
+          end = closeEnd + 1;
+        }
+        break;
+      }
+      search = candidate + closeTag.length;
+    }
+
+    const closed = bodyEnd !== -1;
+    found.push({
+      start,
+      bodyStart,
+      bodyEnd: closed ? bodyEnd : haystack.length,
+      end: closed ? end : haystack.length,
+      closed
+    });
+    cursor = closed ? end : haystack.length;
+  }
+
+  return found;
+}
+
+/**
+ * Collect the class names and IDs a document references.
+ *
+ * Style sheet contents are excluded, so that a style sheet never counts as
+ * evidence for its own selectors. An `iframe srcdoc` value is not scanned,
+ * either: It holds a document of its own, minified against its own symbol set.
+ * Over-collecting is safe here (a symbol wrongly considered used is merely
+ * kept), under-collecting is not.
+ *
+ * @param {string} html - Raw document markup
+ * @param {boolean} includeScripts - Also treat identifiers inside inline `script` elements as used
+ * @param {((text: string) => string)} [decode] - Resolves character references in attribute values and foreign script contents
+ * @param {Set<string>} [elements] - Receives the element names the markup uses, lowercased, and the identifiers found in scripts, as possible element names
+ * @returns {Set<string>} Symbols to keep
+ */
+function collectUsedSymbols(html, includeScripts, decode, elements) {
+  const used = new Set();
+  const haystack = foldCase(html);
+
+  // Style sheets are skipped rather than cut out, so both scans share one folded
+  // copy and offsets keep pointing into `html`. Only the body is skipped—the start
+  // tag carries ordinary attributes, and `<style id="theme">` could be what
+  // `#theme` refers to. An unclosed element is not skipped: Reading its contents
+  // as markup can only add symbols, whereas ignoring the rest of the document
+  // would lose them.
+  const skipped = findRawTextElements(haystack, 'style')
+    .filter(element => element.closed)
+    .map(element => ({ start: element.bodyStart, end: element.bodyEnd }));
+
+  if (elements) {
+    collectUsedElements(haystack, skipped, elements);
+  }
+
+  const addIdentifiers = (/** @type {string} */ text, /** @type {Set<string> | undefined} */ names = undefined) => {
+    identifierPattern.lastIndex = 0;
+    let identifier;
+    while ((identifier = identifierPattern.exec(text))) {
+      used.add(identifier[0]);
+      names?.add(identifier[0].toLowerCase());
+    }
+  };
+
+  const addTokens = (/** @type {string} */ text) => {
+    for (const token of text.split(/\s+/)) {
+      if (token) {
+        used.add(token);
+      }
+    }
+  };
+
+  // Both loops below walk forward, so one cursor over the skipped ranges suffices
+  let skipCursor = 0;
+  const isSkipped = (/** @type {number} */ index) => {
+    while (skipCursor < skipped.length && (skipped[skipCursor]?.end ?? 0) <= index) {
+      skipCursor++;
+    }
+    const element = skipped[skipCursor];
+    return element !== undefined && index >= element.start;
+  };
+
+  attributePattern.lastIndex = 0;
+  let match;
+  while ((match = attributePattern.exec(html))) {
+    const raw = match[2] ?? match[3] ?? match[4] ?? '';
+    if (!raw || isSkipped(match.index)) {
+      continue;
+    }
+    const name = (match[1] ?? '').toLowerCase();
+    // `class="us&#101;d"` names the class `used`, so compare against the decoded value
+    const value = (decode && raw.indexOf('&') !== -1) ? decode(raw) : raw;
+    if (name === 'class' || name === 'id' || idReferenceAttributes.has(name)) {
+      addTokens(value);
+    } else if (name.startsWith('data-')) {
+      // Class names are commonly parked in `data-*` attributes for scripts to apply later
+      addIdentifiers(value);
+      addTokens(value);
+    } else if (fragmentReferenceAttributes.has(name) && value.charAt(0) === '#') {
+      // Only a leading `#`: `href="/page#sec"` names a section of another document
+      addTokens(value.slice(1));
+    }
+    if (value.indexOf('(') !== -1) {
+      fragmentURLPattern.lastIndex = 0;
+      let reference;
+      while ((reference = fragmentURLPattern.exec(value))) {
+        addTokens(reference[1] ?? '');
+      }
+    }
+  }
+
+  if (includeScripts) {
+    // Script contents are raw text, so character references stay literal
+    // except in SVG and MathML, where they are resolved; as the namespace
+    // isn’t tracked here, both readings count where they differ. An unclosed
+    // `script` runs to the end of the document, as it does in a browser.
+    skipCursor = 0;
+    for (const element of findRawTextElements(haystack, 'script')) {
+      if (isSkipped(element.start)) {
+        continue;
+      }
+      const body = html.slice(element.bodyStart, element.bodyEnd);
+      const decoded = (decode && body.indexOf('&') !== -1) ? decode(body) : body;
+      for (const text of decoded === body ? [body] : [body, decoded]) {
+        addIdentifiers(text, elements);
+        stringLiteralPattern.lastIndex = 0;
+        let literal;
+        while ((literal = stringLiteralPattern.exec(text))) {
+          addTokens(literal[1] ?? literal[2] ?? literal[3] ?? '');
+        }
+      }
+    }
+  }
+
+  return used;
+}
+
+/**
+ * Determine which class/ID symbols a style sheet defines but the document doesn’t reference.
+ * @param {string} css - Style sheet contents
+ * @param {Set<string>} used - Symbols the document references
+ * @param {Array<string | RegExp>} safelist - Symbols to keep regardless
+ * @returns {string[]} Symbols safe to remove
+ */
+function findUnusedSymbols(css, used, safelist) {
+  const reserved = new Set();
+  reservedAtRulePattern.lastIndex = 0;
+  let match;
+  while ((match = reservedAtRulePattern.exec(css))) {
+    if (match[1]) {
+      reserved.add(match[1]);
+    }
+  }
+
+  const unused = [];
+  const seen = new Set();
+  cssIdentifierPattern.lastIndex = 0;
+  while ((match = cssIdentifierPattern.exec(css))) {
+    const symbol = unescapeIdentifier(match[1] ?? '');
+    if (seen.has(symbol)) {
+      continue;
+    }
+    seen.add(symbol);
+    if (used.has(symbol) || reserved.has(symbol) || isSafelisted(symbol, safelist)) {
+      continue;
+    }
+    unused.push(symbol);
+  }
+
+  return unused;
+}
+
+/**
+ * @param {string} symbol
+ * @param {Array<string | RegExp>} safelist
+ * @returns {boolean}
+ */
+function isSafelisted(symbol, safelist) {
+  return safelist.some(entry => {
+    if (!(entry instanceof RegExp)) {
+      return entry === symbol;
+    }
+    // `test()` advances `lastIndex` on global and sticky patterns, which would
+    // make a safelist entry match only every other symbol
+    entry.lastIndex = 0;
+    return entry.test(symbol);
+  });
+}
+
+/**
+ * Collect the element names a document contains, including those the parser
+ * supplies when the markup leaves them out.
+ * @param {string} haystack - Case-folded markup, as returned by `foldCase`
+ * @param {Array<{start: number, end: number}>} skipped - Style sheet bodies, in document order
+ * @param {Set<string>} elements - Lowercase element names, added to
+ */
+function collectUsedElements(haystack, skipped, elements) {
+  elements.add('html');
+  elements.add('head');
+  elements.add('body');
+
+  let skipIndex = 0;
+  startTagPattern.lastIndex = 0;
+  let match;
+  while ((match = startTagPattern.exec(haystack))) {
+    while (skipIndex < skipped.length && (skipped[skipIndex]?.end ?? 0) <= match.index) {
+      skipIndex++;
+    }
+    const element = skipped[skipIndex];
+    if (element && match.index >= element.start) {
+      continue;
+    }
+    elements.add(match[1] ?? '');
+  }
+}
+
+/**
+ * Build the unused-CSS context for a document.
+ * @param {string} html - Raw document markup
+ * @param {boolean} includeScripts - Also treat identifiers inside inline `script` elements as used
+ * @param {((text: string) => string)} [decode] - Resolves character references in attribute values and foreign script contents
+ * @returns {{usedSymbols: Set<string>, usedElements: Set<string>, usedElementsKey: string}}
+ */
+function collectUsage(html, includeScripts, decode) {
+  // A script may create the elements a rule is for, so its identifiers count as names, too
+  const usedElements = new Set();
+  const usedSymbols = collectUsedSymbols(html, includeScripts, decode, usedElements);
+  // Elements the parser supplies inside a `table`, added after script identifiers, as a script
+  // may create a `table`, too
+  if (usedElements.has('table')) {
+    usedElements.add('tbody');
+    usedElements.add('tr');
+  }
+  if (usedElements.has('col')) {
+    usedElements.add('colgroup');
+  }
+  return {
+    usedSymbols,
+    usedElements,
+    // The CSS cache outlives a document, so its keys tell element sets apart. The set
+    // is in document order, so the same elements in another order only miss the cache.
+    usedElementsKey: String(hashContent([...usedElements].join(' ')))
+  };
+}
+
+/**
+ * Create a Lightning CSS `Selector` visitor that drops selectors naming an unused
+ * class, ID, or element from their list, so the rule stays for the selectors that
+ * remain (`unusedSymbols` alone only removes rules whose selectors are all unused).
+ *
+ * Only a selector’s own compounds are judged: Names inside pseudo-class and
+ * pseudo-element arguments (`:not(.x)`, `:host(.x)`) are left alone.
+ *
+ * @param {string[]} unusedSymbols - Class/ID symbols safe to remove, from `findUnusedSymbols`
+ * @param {Set<string>} usedElements - Lowercase element names the document contains or its scripts name
+ * @param {Array<string | RegExp>} safelist - Symbols to keep regardless
+ * @returns {(selector: Array<{type: string, name?: string}>) => [] | undefined}
+ */
+function createSelectorPruner(unusedSymbols, usedElements, safelist) {
+  const unused = new Set(unusedSymbols);
+  /** @type {Map<string, boolean>} */
+  const unusedElements = new Map();
+  const isUnusedElement = (/** @type {string} */ name) => {
+    let result = unusedElements.get(name);
+    if (result === undefined) {
+      result = !usedElements.has(name.toLowerCase()) && !isSafelisted(name, safelist);
+      unusedElements.set(name, result);
+    }
+    return result;
+  };
+
+  return selector => {
+    for (const component of selector) {
+      const name = component.name;
+      if (name === undefined) {
+        continue;
+      }
+      if (((component.type === 'class' || component.type === 'id') && unused.has(name)) ||
+          (component.type === 'type' && isUnusedElement(name))) {
+        return [];
+      }
+    }
+    return undefined;
+  };
+}
+
+const unusedCSSKeys = new Set(['safelist', 'scripts']);
+
+/**
+ * Normalize the `removeUnusedCSS` option into a settled configuration.
+ *
+ * A misspelled key or a safelist that is not an array would otherwise protect
+ * nothing, and that only surfaces as a missing rule much later—so every value
+ * that gets dropped is reported.
+ *
+ * @param {boolean | {safelist?: Array<string | RegExp>, scripts?: boolean} | undefined} option
+ * @param {(message: string) => unknown} [warn] - Receives one message per ignored value
+ * @returns {{safelist: Array<string | RegExp>, scripts: boolean} | null} Null when disabled
+ */
+function normalizeUnusedCSSOptions(option, warn) {
+  if (!option) {
+    return null;
+  }
+  const report = warn ?? (() => {});
+  const config = /** @type {Record<string, any>} */ (typeof option === 'object' ? option : {});
+
+  for (const key of Object.keys(config)) {
+    if (!unusedCSSKeys.has(key)) {
+      report(`Ignoring unknown \`removeUnusedCSS\` key \`${key}\`—expected \`safelist\` or \`scripts\``);
+    }
+  }
+
+  /** @type {Array<string | RegExp>} */
+  let safelist = [];
+  if (config.safelist !== undefined) {
+    if (!Array.isArray(config.safelist)) {
+      report('Ignoring `removeUnusedCSS.safelist`—it takes an array of strings and regular expressions');
+    } else {
+      safelist = config.safelist.filter((/** @type {unknown} */ entry) => {
+        if (typeof entry === 'string' || entry instanceof RegExp) {
+          return true;
+        }
+        report(`Ignoring \`removeUnusedCSS.safelist\` entry of type ${typeof entry}—entries must be strings or regular expressions`);
+        return false;
+      });
+    }
+  }
+
+  if (config.scripts !== undefined && typeof config.scripts !== 'boolean') {
+    report('Ignoring `removeUnusedCSS.scripts`—it takes a boolean');
+  }
+
+  return {
+    safelist,
+    // Keeping identifiers seen in inline scripts costs a little of the reduction
+    // but avoids the most common breakage, so it is the default
+    scripts: typeof config.scripts === 'boolean' ? config.scripts : true
+  };
+}
+
+export {
+  collectUsage,
+  collectUsedSymbols,
+  createSelectorPruner,
+  findUnusedSymbols,
+  normalizeUnusedCSSOptions
+};

package/src/lib/urls.js

@@ -0,0 +1,146 @@
+/**
+ * URL minification using Node’s WHATWG URL API
+ *
+ * Produces the shortest equivalent URL representation:
+ * - Same origin: shortest of root-relative or path-relative
+ * - Cross-origin, same scheme: scheme-relative (`//host/path`)
+ * - Otherwise: normalized absolute URL
+ */
+
+const REJECTED_SCHEMES = new Set(['data:', 'javascript:', 'mailto:']);
+
+const DIRECTORY_INDEXES = ['index.html', 'index.htm'];
+
+/**
+ * Get the directory portion of a pathname (up to and including the last `/`).
+ * @param {string} pathname
+ * @returns {string}
+ */
+function getDirectory(pathname) {
+  const lastSlash = pathname.lastIndexOf('/');
+  return pathname.slice(0, lastSlash + 1);
+}
+
+/**
+ * Compute a path-relative URL from a base directory to a target path.
+ * @param {string} baseDir - Base directory path (must end with `/`)
+ * @param {string} targetPath - Target pathname
+ * @returns {string}
+ */
+function relativize(baseDir, targetPath) {
+  const baseSegments = baseDir.split('/').filter(Boolean);
+  const targetSegments = targetPath.split('/').filter(Boolean);
+  const isDirectoryTarget = targetPath.endsWith('/');
+
+  let common = 0;
+  while (
+    common < baseSegments.length &&
+    common < targetSegments.length &&
+    baseSegments[common] === targetSegments[common]
+  ) {
+    // Stop before the last target segment only for file targets (not directories)
+    if (!isDirectoryTarget && common === targetSegments.length - 1) break;
+    common++;
+  }
+
+  const ups = baseSegments.length - common;
+  const remaining = targetSegments.slice(common);
+
+  let relative = '../'.repeat(ups) + remaining.join('/');
+
+  if (isDirectoryTarget && relative !== '' && !relative.endsWith('/')) {
+    relative += '/';
+  }
+
+  // For directory targets, empty result means same directory
+  if (relative === '' && isDirectoryTarget) {
+    return './';
+  }
+
+  return relative;
+}
+
+/**
+ * Remove directory index from the end of a pathname.
+ * @param {string} pathname
+ * @returns {string}
+ */
+function removeDirectoryIndex(pathname) {
+  for (const index of DIRECTORY_INDEXES) {
+    if (pathname.endsWith('/' + index)) {
+      return pathname.slice(0, pathname.length - index.length);
+    }
+  }
+  return pathname;
+}
+
+/**
+ * Create a URL minifier function for the given site context.
+ * @param {string} site - The site base URL (used to compute relative URLs)
+ * @returns {(url: string) => string} Minifier function that returns the shortest URL
+ */
+export function createUrlMinifier(site) {
+  let baseUrl;
+  try {
+    baseUrl = site ? new URL(site) : null;
+  } catch {
+    baseUrl = null;
+  }
+
+  return function relate(url) {
+    if (!url || !url.trim()) return url;
+
+    // Preserve fragment-only and query-only URLs as shortest form
+    const trimmed = url.trim();
+    if (trimmed[0] === '#' || trimmed[0] === '?') return url;
+
+    let targetUrl;
+    try {
+      targetUrl = new URL(url);
+    } catch {
+      // Not a valid absolute URL—try resolving against base
+      if (baseUrl) {
+        try {
+          targetUrl = new URL(url, baseUrl);
+        } catch {
+          return url;
+        }
+      } else {
+        return url;
+      }
+    }
+
+    if (REJECTED_SCHEMES.has(targetUrl.protocol)) return url;
+
+    targetUrl.pathname = removeDirectoryIndex(targetUrl.pathname);
+
+    const suffix = targetUrl.search + targetUrl.hash;
+
+    if (!baseUrl) {
+      return targetUrl.href;
+    }
+
+    // Preserve userinfo—non-absolute URLs would drop username/password
+    if (targetUrl.username || targetUrl.password) {
+      return targetUrl.href;
+    }
+
+    const sameOrigin =
+      targetUrl.protocol === baseUrl.protocol &&
+      targetUrl.hostname === baseUrl.hostname &&
+      targetUrl.port === baseUrl.port;
+
+    if (!sameOrigin) {
+      if (targetUrl.protocol === baseUrl.protocol) {
+        return '//' + targetUrl.host + targetUrl.pathname + suffix;
+      }
+      return targetUrl.href;
+    }
+
+    const targetPath = targetUrl.pathname;
+    const rootRelative = targetPath + suffix;
+    const pathRelative = relativize(getDirectory(baseUrl.pathname), targetPath) + suffix;
+
+    return pathRelative && pathRelative.length < rootRelative.length ? pathRelative : rootRelative;
+  };
+}