@turntrout/subfont 1.5.0 → 1.6.0

package/lib/fontFeatureHelpers.js

@@ -0,0 +1,249 @@
+const cssFontParser = require('css-font-parser');
+
+const featureSettingsProps = new Set([
+  'font-feature-settings',
+  'font-variant-alternates',
+  'font-variant-caps',
+  'font-variant-east-asian',
+  'font-variant-ligatures',
+  'font-variant-numeric',
+  'font-variant-position',
+]);
+
+// Map font-variant-* CSS values to their corresponding OpenType feature tags.
+const fontVariantToOTTags = {
+  'font-variant-ligatures': {
+    'common-ligatures': ['liga', 'clig'],
+    'no-common-ligatures': ['liga', 'clig'],
+    'discretionary-ligatures': ['dlig'],
+    'no-discretionary-ligatures': ['dlig'],
+    'historical-ligatures': ['hlig'],
+    'no-historical-ligatures': ['hlig'],
+    contextual: ['calt'],
+    'no-contextual': ['calt'],
+  },
+  'font-variant-caps': {
+    'small-caps': ['smcp'],
+    'all-small-caps': ['smcp', 'c2sc'],
+    'petite-caps': ['pcap'],
+    'all-petite-caps': ['pcap', 'c2pc'],
+    unicase: ['unic'],
+    'titling-caps': ['titl'],
+  },
+  'font-variant-numeric': {
+    'lining-nums': ['lnum'],
+    'oldstyle-nums': ['onum'],
+    'proportional-nums': ['pnum'],
+    'tabular-nums': ['tnum'],
+    'diagonal-fractions': ['frac'],
+    'stacked-fractions': ['afrc'],
+    ordinal: ['ordn'],
+    'slashed-zero': ['zero'],
+  },
+  'font-variant-position': {
+    sub: ['subs'],
+    super: ['sups'],
+  },
+  'font-variant-east-asian': {
+    jis78: ['jp78'],
+    jis83: ['jp83'],
+    jis90: ['jp90'],
+    jis04: ['jp04'],
+    simplified: ['smpl'],
+    traditional: ['trad'],
+    'proportional-width': ['pwid'],
+    'full-width': ['fwid'],
+    ruby: ['ruby'],
+  },
+};
+
+// Extract OpenType feature tags referenced by a CSS declaration.
+function extractFeatureTagsFromDecl(prop, value) {
+  const tags = new Set();
+  const propLower = prop.toLowerCase();
+
+  if (propLower === 'font-feature-settings') {
+    // Parse quoted 4-letter tags: "liga" 1, 'dlig', etc.
+    const re = /["']([a-zA-Z0-9]{4})["']/g;
+    let m;
+    while ((m = re.exec(value)) !== null) {
+      tags.add(m[1]);
+    }
+    return tags;
+  }
+
+  if (propLower === 'font-variant-alternates') {
+    const v = value.toLowerCase();
+    if (v.includes('historical-forms')) tags.add('hist');
+    if (/stylistic\s*\(/.test(v)) tags.add('salt');
+    if (/swash\s*\(/.test(v)) tags.add('swsh');
+    if (/ornaments\s*\(/.test(v)) tags.add('ornm');
+    if (/annotation\s*\(/.test(v)) tags.add('nalt');
+    if (/styleset\s*\(/.test(v)) {
+      for (let i = 1; i <= 20; i++) {
+        tags.add(`ss${String(i).padStart(2, '0')}`);
+      }
+    }
+    if (/character-variant\s*\(/.test(v)) {
+      for (let i = 1; i <= 99; i++) {
+        tags.add(`cv${String(i).padStart(2, '0')}`);
+      }
+    }
+    return tags;
+  }
+
+  const mapping = fontVariantToOTTags[propLower];
+  if (mapping) {
+    // Split into tokens for exact keyword matching — substring matching
+    // would falsely trigger e.g. "sub" inside "super".
+    const tokens = new Set(value.toLowerCase().split(/\s+/));
+    for (const [keyword, otTags] of Object.entries(mapping)) {
+      if (tokens.has(keyword)) {
+        for (const t of otTags) tags.add(t);
+      }
+    }
+  }
+  return tags;
+}
+
+// Collect feature tags from all feature-related declarations in a CSS rule.
+function ruleFeatureTags(rule) {
+  const tags = new Set();
+  let hasFeatureDecl = false;
+  for (const node of rule.nodes) {
+    if (
+      node.type === 'decl' &&
+      featureSettingsProps.has(node.prop.toLowerCase())
+    ) {
+      hasFeatureDecl = true;
+      for (const t of extractFeatureTagsFromDecl(node.prop, node.value)) {
+        tags.add(t);
+      }
+    }
+  }
+  return hasFeatureDecl ? tags : null;
+}
+
+function ruleFontFamily(rule) {
+  for (let i = rule.nodes.length - 1; i >= 0; i--) {
+    const node = rule.nodes[i];
+    if (node.type === 'decl' && node.prop.toLowerCase() === 'font-family') {
+      return node.value;
+    }
+  }
+  return null;
+}
+
+// Add all items from `tags` into the Set stored at `key` in `map`,
+// creating the Set if it doesn't exist yet.
+function addTagsToMapEntry(map, key, tags) {
+  let s = map.get(key);
+  if (!s) {
+    s = new Set();
+    map.set(key, s);
+  }
+  for (const t of tags) s.add(t);
+}
+
+// Record the OT tags from a single CSS rule into featureTagsByFamily,
+// keyed by font-family (or '*' when no font-family is specified).
+function recordRuleFeatureTags(rule, featureTagsByFamily) {
+  const tags = ruleFeatureTags(rule);
+  if (!tags) return null;
+
+  const fontFamily = ruleFontFamily(rule);
+  if (!fontFamily) {
+    if (featureTagsByFamily) addTagsToMapEntry(featureTagsByFamily, '*', tags);
+    return true; // signals "all families"
+  }
+
+  const families = cssFontParser.parseFontFamily(fontFamily);
+  if (featureTagsByFamily) {
+    for (const family of families) {
+      addTagsToMapEntry(featureTagsByFamily, family.toLowerCase(), tags);
+    }
+  }
+  return families;
+}
+
+// Determine which font-families use font-feature-settings or font-variant-*.
+// Returns null (none detected), a Set of lowercase family names, or true (all).
+// Also populates featureTagsByFamily with the OT tags per family (lowercase).
+function findFontFamiliesWithFeatureSettings(
+  stylesheetsWithPredicates,
+  featureTagsByFamily
+) {
+  let result = null;
+  for (const { asset } of stylesheetsWithPredicates) {
+    if (!asset || !asset.parseTree) continue;
+    asset.parseTree.walkRules((rule) => {
+      if (result === true && !featureTagsByFamily) return;
+
+      const recorded = recordRuleFeatureTags(rule, featureTagsByFamily);
+      if (!recorded) return;
+
+      if (recorded === true) {
+        result = true;
+      } else if (result !== true) {
+        if (!result) result = new Set();
+        for (const family of recorded) {
+          result.add(family.toLowerCase());
+        }
+      }
+    });
+    if (result === true && !featureTagsByFamily) break;
+  }
+  return result;
+}
+
+// Determine whether a template's font families use feature settings, and
+// collect the corresponding OT feature tags from featureTagsByFamily.
+function resolveFeatureSettings(
+  fontFamilies,
+  fontFamiliesWithFeatureSettings,
+  featureTagsByFamily
+) {
+  let hasFontFeatureSettings = false;
+  if (fontFamiliesWithFeatureSettings === true) {
+    hasFontFeatureSettings = true;
+  } else if (fontFamiliesWithFeatureSettings instanceof Set) {
+    for (const f of fontFamilies) {
+      if (fontFamiliesWithFeatureSettings.has(f.toLowerCase())) {
+        hasFontFeatureSettings = true;
+        break;
+      }
+    }
+  }
+
+  let fontFeatureTags;
+  if (hasFontFeatureSettings && featureTagsByFamily) {
+    const tags = new Set();
+    const globalTags = featureTagsByFamily.get('*');
+    if (globalTags) {
+      for (const t of globalTags) tags.add(t);
+    }
+    for (const f of fontFamilies) {
+      const familyTags = featureTagsByFamily.get(f.toLowerCase());
+      if (familyTags) {
+        for (const t of familyTags) tags.add(t);
+      }
+    }
+    if (tags.size > 0) {
+      fontFeatureTags = [...tags];
+    }
+  }
+
+  return { hasFontFeatureSettings, fontFeatureTags };
+}
+
+module.exports = {
+  featureSettingsProps,
+  fontVariantToOTTags,
+  extractFeatureTagsFromDecl,
+  ruleFeatureTags,
+  ruleFontFamily,
+  addTagsToMapEntry,
+  recordRuleFeatureTags,
+  findFontFamiliesWithFeatureSettings,
+  resolveFeatureSettings,
+};

package/lib/fontTracerWorker.js

@@ -48,16 +48,6 @@ parentPort.on('message', (msg) => {
       const textByProps = fontTracer(document, {
         stylesheetsWithPredicates,
         getCssRulesByProperty: memoizedGetCssRulesByProperty,
-        propsToReturn: [
-          'font-family',
-          'font-style',
-          'font-weight',
-          'font-variant',
-          'font-stretch',
-          'font-variation-settings',
-          'animation-timing-function',
-          'font-size',
-        ],
       });
 
       // Strip any non-serializable data from results

package/lib/parseCommandLineOptions.js

@@ -111,7 +111,7 @@ module.exports = function parseCommandLineOptions(argv) {
       },
     })
     .options('concurrency', {
-      describe: `Maximum number of worker threads for parallel font tracing. Defaults to the number of CPU cores (max 8). Upper bound: ${maxConcurrency} (based on available memory)`,
+      describe: `Maximum number of worker threads for parallel font tracing. Defaults to the number of CPU cores (max 8). Upper bound: ${maxConcurrency} (based on free memory and CPU count)`,
       type: 'number',
     })
     .check((argv) => {
@@ -121,7 +121,7 @@ module.exports = function parseCommandLineOptions(argv) {
         }
         if (argv.concurrency > maxConcurrency) {
           throw new Error(
-            `--concurrency must not exceed ${maxConcurrency} (each worker uses ~50 MB; system has ${Math.round(os.totalmem() / (1024 * 1024 * 1024))} GB total)`
+            `--concurrency must not exceed ${maxConcurrency} (each worker uses ~50 MB; ${Math.round(os.freemem() / (1024 * 1024 * 1024))} GB free, ${os.cpus().length} CPUs)`
           );
         }
       }

package/lib/progress.js

@@ -0,0 +1,101 @@
+// Helpers for surfacing phase progress to the console.
+//
+// Two audiences:
+//   1. Non-debug users want brief, always-visible signal that the tool
+//      isn't hung on large runs (banner + periodic page counts + done).
+//   2. Debug users want to pinpoint *which* phase is stuck when output
+//      goes silent. Paired "→ starting" / "← finished in Nms" markers
+//      around each slow phase mean the last line printed is always the
+//      currently-running phase.
+
+// Pick a progress step that gives roughly 10 updates across the run,
+// clamped to [1, 10]. For a 500-page run this prints every 50; for 30,
+// every 3. Avoids long silent stretches on large runs and per-page spam
+// on small ones.
+function progressStep(total) {
+  return Math.max(1, Math.min(10, Math.ceil(total / 10)));
+}
+
+// Reporter for a phase that iterates `total` items.
+//   banner(msg): optional one-line header printed immediately.
+//   tick(): call once per completed item; returns the running count.
+//   done(): prints "<label>: <total>/<total> pages done." footer.
+// All methods no-op when disabled (missing console or below minTotal).
+function createPageProgress({ total, console, label, minTotal = 5 }) {
+  const enabled = Boolean(console) && total >= minTotal;
+  const step = progressStep(total);
+  let count = 0;
+  return {
+    enabled,
+    banner(msg) {
+      if (enabled) console.log(msg);
+    },
+    tick() {
+      count++;
+      if (enabled && count % step === 0 && count < total) {
+        console.log(`  ${label}: ${count}/${total} pages...`);
+      }
+      return count;
+    },
+    done() {
+      if (enabled) {
+        console.log(`  ${label}: ${total}/${total} pages done.`);
+      }
+    },
+  };
+}
+
+// Per-page debug line emitted right after a page finishes tracing.
+// When a run hangs, the last-printed page identifies which page stalled.
+function logTracedPage(console, debug, index, total, asset, startMs) {
+  if (!debug || !console) return;
+  console.log(
+    `[subfont timing]   traced [${index}/${total}] ${asset.urlOrDescription} in ${Date.now() - startMs}ms`
+  );
+}
+
+// Start/end markers for a debug phase. The "→ label..." line is printed
+// *before* the work begins, so if the work hangs the user sees exactly
+// which phase is in flight. The returned end() logs elapsed ms and
+// returns the duration so callers can still populate a timings map.
+//
+//   const phase = logPhaseStart(console, debug, 'getSubsetsForFontUsage');
+//   await getSubsetsForFontUsage(...);
+//   timings.x = phase.end();
+function logPhaseStart(console, debug, label) {
+  if (!debug || !console) {
+    const start = Date.now();
+    return {
+      end() {
+        return Date.now() - start;
+      },
+    };
+  }
+  const start = Date.now();
+  console.log(`[subfont timing] → ${label}...`);
+  return {
+    end(extraInfo) {
+      const ms = Date.now() - start;
+      const suffix = extraInfo ? ` (${extraInfo})` : '';
+      console.log(`[subfont timing] ← ${label}: ${ms}ms${suffix}`);
+      return ms;
+    },
+  };
+}
+
+// Bind a (console, debug) pair once at the top of a function, then use
+// the returned tracker to open phases with a single short call:
+//
+//   const trackPhase = makePhaseTracker(console, debug);
+//   const p = trackPhase('codepoint generation');
+//   ...work...
+//   timings.x = p.end();
+function makePhaseTracker(console, debug) {
+  return (label) => logPhaseStart(console, debug, label);
+}
+
+module.exports = {
+  createPageProgress,
+  logTracedPage,
+  makePhaseTracker,
+};

package/lib/subfont.js

@@ -1,12 +1,14 @@
 const fsPromises = require('fs/promises');
 const os = require('os');
 const pathModule = require('path');
+const sanitizeFilename = require('sanitize-filename');
 const { getMaxConcurrency } = require('./concurrencyLimit');
 const AssetGraph = require('assetgraph');
 const prettyBytes = require('pretty-bytes');
 const urlTools = require('urltools');
 const util = require('util');
 const subsetFonts = require('./subsetFonts');
+const { makePhaseTracker } = require('./progress');
 
 class UsageError extends Error {
   constructor(message) {
@@ -49,7 +51,7 @@ module.exports = async function subfont(
   const maxConcurrency = getMaxConcurrency();
   if (concurrency !== undefined && concurrency > maxConcurrency) {
     throw new UsageError(
-      `--concurrency must not exceed ${maxConcurrency} (each worker uses ~50 MB; system has ${Math.round(os.totalmem() / (1024 * 1024 * 1024))} GB total)`
+      `--concurrency must not exceed ${maxConcurrency} (each worker uses ~50 MB; ${Math.round(os.freemem() / (1024 * 1024 * 1024))} GB free, ${os.cpus().length} CPUs)`
     );
   }
 
@@ -191,21 +193,20 @@ module.exports = async function subfont(
   }
 
   const outerTimings = {};
+  // The tracker writes with console.log (duck-typed). Route it through
+  // the silent-aware log wrapper so --silent suppresses phase markers
+  // the same way it suppresses other subfont output.
+  const trackPhase = makePhaseTracker({ log }, debug);
 
-  let phaseStart = Date.now();
+  const loadAssetsPhase = trackPhase('loadAssets');
   await assetGraph.loadAssets(inputUrls);
-  outerTimings.loadAssets = Date.now() - phaseStart;
-  if (debug) log(`[subfont timing] loadAssets: ${outerTimings.loadAssets}ms`);
+  outerTimings.loadAssets = loadAssetsPhase.end();
 
-  phaseStart = Date.now();
+  const populatePhase = trackPhase('populate (initial)');
   await assetGraph.populate({
     followRelations: followRelationsQuery,
   });
-  outerTimings['populate (initial)'] = Date.now() - phaseStart;
-  if (debug)
-    log(
-      `[subfont timing] populate (initial): ${outerTimings['populate (initial)']}ms`
-    );
+  outerTimings['populate (initial)'] = populatePhase.end();
 
   const entrypointAssets = assetGraph.findAssets({ isInitial: true });
   const redirectOrigins = new Set();
@@ -269,7 +270,7 @@ module.exports = async function subfont(
     );
   }
 
-  phaseStart = Date.now();
+  const subsetPhase = trackPhase('subsetFonts total');
   const { fontInfo, timings: subsetTimings } = await subsetFonts(assetGraph, {
     inlineCss,
     fontDisplay,
@@ -285,11 +286,9 @@ module.exports = async function subfont(
     chromeArgs: chromeFlags,
     cacheDir,
   });
+  const subsetFontsTotal = subsetPhase.end();
 
-  const subsetFontsTotal = Date.now() - phaseStart;
-  if (debug) log(`[subfont timing] subsetFonts total: ${subsetFontsTotal}ms`);
-
-  phaseStart = Date.now();
+  const postProcessingPhase = trackPhase('post-subsetFonts processing');
   let sumSizesAfter = 0;
   for (const asset of assetGraph.findAssets(sizeableAssetQuery)) {
     sumSizesAfter += asset.rawSrc.length;
@@ -313,11 +312,12 @@ module.exports = async function subfont(
       assetGraph.info(
         new Error(`Pulling down modified stylesheet ${asset.url}`)
       );
-      asset.url = `${assetGraph.root}subfont/${
-        asset.baseName || 'index'
-      }-${asset.md5Hex.slice(0, 10)}${
-        asset.extension || asset.defaultExtension
-      }`;
+      const safeName =
+        sanitizeFilename(asset.baseName || '', { replacement: '_' }) || 'index';
+      asset.url = `${assetGraph.root}subfont/${safeName}-${asset.md5Hex.slice(
+        0,
+        10
+      )}${asset.extension || asset.defaultExtension}`;
     }
   }
 
@@ -343,11 +343,7 @@ module.exports = async function subfont(
     );
   }
 
-  outerTimings['post-subsetFonts processing'] = Date.now() - phaseStart;
-  if (debug)
-    log(
-      `[subfont timing] post-subsetFonts processing: ${outerTimings['post-subsetFonts processing']}ms`
-    );
+  outerTimings['post-subsetFonts processing'] = postProcessingPhase.end();
 
   if (strict && sawWarning) {
     // In non-silent mode, assetgraph's logEvents normally exits earlier via
@@ -358,7 +354,7 @@ module.exports = async function subfont(
     );
   }
 
-  phaseStart = Date.now();
+  const writePhase = trackPhase('writeAssetsToDisc');
   if (!dryRun) {
     await assetGraph.writeAssetsToDisc(
       {
@@ -370,14 +366,9 @@ module.exports = async function subfont(
       assetGraph.root
     );
   }
+  outerTimings.writeAssetsToDisc = writePhase.end();
 
-  outerTimings.writeAssetsToDisc = Date.now() - phaseStart;
-  if (debug)
-    log(
-      `[subfont timing] writeAssetsToDisc: ${outerTimings.writeAssetsToDisc}ms`
-    );
-
-  phaseStart = Date.now();
+  const reportingPhase = trackPhase('output reporting');
   if (debug) {
     const compactFontInfo = fontInfo.map(({ fontUsages, ...rest }) => ({
       ...rest,
@@ -494,11 +485,7 @@ module.exports = async function subfont(
     )}`
   );
   log(`Total savings: ${prettyBytes(totalSavings)}`);
-  outerTimings['output reporting'] = Date.now() - phaseStart;
-  if (debug)
-    log(
-      `[subfont timing] output reporting: ${outerTimings['output reporting']}ms`
-    );
+  outerTimings['output reporting'] = reportingPhase.end();
 
   const st = subsetTimings || {};
   const details = st.collectTextsByPageDetails || {};

package/lib/subsetFontWithGlyphs.js

@@ -216,6 +216,14 @@ function extractSubsetFont(exports, subset) {
   // Fresh view AFTER the WASM calls above — memory.buffer may have been
   // detached by a grow during hb_face_reference_blob / hb_blob_get_data.
   const heapu8 = getHeapu8(exports);
+
+  if (offset + subsetByteLength > heapu8.byteLength) {
+    exports.hb_blob_destroy(result);
+    throw new Error(
+      `WASM returned out-of-bounds offset ${offset} + length ${subsetByteLength} (heap size ${heapu8.byteLength})`
+    );
+  }
+
   const subsetFont = Buffer.from(
     heapu8.subarray(offset, offset + subsetByteLength)
   );