@idirdev/fontsubset 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 idirdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# fontsubset
+
+> **[EN]** Audit font files in your project — detect formats, report file sizes, validate TTF/OTF magic bytes, extract unicode ranges from CSS, and suggest WOFF2 conversion savings.
+> **[FR]** Auditez les polices de votre projet — détectez les formats, rapportez les tailles, validez les magic bytes TTF/OTF, extrayez les plages unicode depuis le CSS et suggérez les économies de conversion en WOFF2.
+
+---
+
+## Features / Fonctionnalités
+
+**[EN]**
+- Recursively finds all font files: `.woff2`, `.woff`, `.ttf`, `.otf`, `.eot`
+- Reports format name, file size (human-readable), and basic validity check
+- Validates TTF/OTF files by reading the magic bytes header (`0x00010000` / `0x4F54544F`)
+- Extracts `unicode-range` declarations from CSS content to map used character sets
+- Suggests conversion to WOFF2 and estimates potential file size savings (~30%)
+- Outputs human-readable table or full JSON with `--json`
+- Zero external dependencies — pure Node.js fs reads
+
+**[FR]**
+- Trouve récursivement tous les fichiers de polices : `.woff2`, `.woff`, `.ttf`, `.otf`, `.eot`
+- Rapporte le nom du format, la taille du fichier (lisible) et une vérification de base
+- Valide les fichiers TTF/OTF en lisant l'en-tête des magic bytes (`0x00010000` / `0x4F54544F`)
+- Extrait les déclarations `unicode-range` du contenu CSS pour cartographier les jeux de caractères utilisés
+- Suggère la conversion en WOFF2 et estime les économies potentielles de taille (~30%)
+- Sortie lisible ou JSON complet avec `--json`
+- Aucune dépendance externe — lectures fs Node.js pures
+
+---
+
+## Installation
+
+```bash
+npm install -g @idirdev/fontsubset
+```
+
+---
+
+## CLI Usage / Utilisation CLI
+
+```bash
+# Scan current directory for fonts (scanner le répertoire courant pour les polices)
+fontsubset
+
+# Scan a specific directory (scanner un répertoire spécifique)
+fontsubset ./public/fonts
+
+# Output full JSON report (sortie JSON complète)
+fontsubset ./assets --json
+
+# Show help (afficher l'aide)
+fontsubset --help
+```
+
+### Example Output / Exemple de sortie
+
+```
+$ fontsubset ./public/fonts
+5 font(s) found:
+  Inter-Regular.ttf (TrueType, 312.4KB)
+  Inter-Bold.ttf (TrueType, 318.1KB)
+  Inter-Regular.woff2 (WOFF2, 89.2KB)
+  icons.woff (WOFF, 42.8KB)
+  legacy.eot (EOT, 156.0KB)
+
+Potential savings: 157.8KB
+```
+
+---
+
+## API (Programmatic) / API (Programmation)
+
+```js
+const { analyzeFontFile, findFonts, extractUsedChars, suggestSubset, formatSize } = require('@idirdev/fontsubset');
+
+// Analyze a single font file (analyser un fichier de police unique)
+const info = analyzeFontFile('./public/fonts/Inter-Regular.ttf');
+console.log(info.format);   // 'TrueType'
+console.log(info.sizeStr);  // '312.4KB'
+console.log(info.valid);    // true (magic bytes OK)
+
+// Find all fonts in a directory tree (trouver toutes les polices dans un arbre de répertoires)
+const fonts = findFonts('./public');
+fonts.forEach(f => console.log(f.file, f.format, f.sizeStr));
+
+// Extract used unicode characters from a CSS file (extraire les caractères unicode utilisés depuis un CSS)
+const css = require('fs').readFileSync('./src/fonts.css', 'utf8');
+const usedChars = extractUsedChars(css);
+console.log(usedChars.size); // number of codepoints used
+
+// Get WOFF2 conversion suggestions with savings estimates (suggestions de conversion WOFF2 avec économies)
+const suggestions = suggestSubset(fonts);
+suggestions.forEach(s => {
+  if (s.potentialSavings > 0) {
+    console.log(`Convert ${s.file} to WOFF2 → save ~${s.savingsStr}`);
+  }
+});
+
+// Human-readable size formatting (formatage lisible des tailles)
+console.log(formatSize(328172)); // '320.5KB'
+```
+
+---
+
+## License
+
+MIT © idirdev

package/bin/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * @fileoverview CLI for fontsubset — analyze web fonts and suggest optimization.
+ * @author idirdev
+ * @usage fontsubset <dir> [--css file.css] [--json] [--suggest]
+ */
+
+const fs = require('fs');
+const m = require('../src/index');
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.length === 0) {
+  console.log([
+    'Usage: fontsubset <dir> [options]',
+    '',
+    'Options:',
+    '  --css <file>  CSS file to extract unicode-range declarations from',
+    '  --suggest     Show WOFF2 conversion suggestions',
+    '  --json        Output results as JSON',
+    '  --help        Show this help message',
+  ].join('\n'));
+  process.exit(0);
+}
+
+const target = args.find(a => !a.startsWith('-')) || '.';
+const showJson = args.includes('--json');
+const showSuggest = args.includes('--suggest');
+
+const cssIdx = args.indexOf('--css');
+const cssFile = cssIdx >= 0 ? args[cssIdx + 1] : null;
+
+let stat;
+try { stat = fs.statSync(target); } catch {
+  console.error('Error: cannot access ' + target);
+  process.exit(1);
+}
+
+const fonts = m.findFonts(target);
+
+if (!fonts.length) {
+  console.log('No font files found in: ' + target);
+  process.exit(0);
+}
+
+if (cssFile) {
+  try {
+    const css = fs.readFileSync(cssFile, 'utf8');
+    const chars = m.extractUsedChars(css);
+    if (!showJson) {
+      console.log(`Unicode ranges cover ${chars.size} code point(s).`);
+    }
+  } catch {
+    console.error('Warning: could not read CSS file: ' + cssFile);
+  }
+}
+
+const results = showSuggest ? m.suggestSubset(fonts) : fonts;
+
+if (showJson) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  console.log(m.formatReport(fonts));
+  if (showSuggest) {
+    const totalSavings = results.reduce((acc, f) => acc + (f.potentialSavings || 0), 0);
+    console.log('\nWOFF2 conversion savings estimate: ' + m.formatSize(totalSavings));
+  }
+  console.log('\n' + m.summary(fonts));
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@idirdev/fontsubset",
+  "version": "1.0.0",
+  "description": "Analyze web fonts and suggest optimization strategies",
+  "main": "src/index.js",
+  "author": "idirdev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/idirdev/fontsubset.git"
+  },
+  "keywords": [],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "test": "node --test tests/fontsubset.test.js"
+  },
+  "bin": {
+    "fontsubset": "bin/cli.js"
+  },
+  "homepage": "https://github.com/idirdev/fontsubset",
+  "bugs": {
+    "url": "https://github.com/idirdev/fontsubset/issues"
+  }
+}

package/src/index.js

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * @fileoverview Web font analyzer — detect formats, extract unicode ranges, suggest optimizations.
+ * @module fontsubset
+ * @author idirdev
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** @type {Object.<string, string>} Map file extension to format name. */
+const EXT_FORMAT = {
+  '.woff2': 'WOFF2',
+  '.woff':  'WOFF',
+  '.ttf':   'TrueType',
+  '.otf':   'OpenType',
+  '.eot':   'EOT',
+};
+
+/** Font file extensions this tool recognizes. */
+const FONT_EXTS = new Set(Object.keys(EXT_FORMAT));
+
+/**
+ * Validate a font buffer by inspecting its magic bytes.
+ *
+ * @param {Buffer} buf - File contents.
+ * @param {string} ext - Lowercase file extension (e.g. '.ttf').
+ * @returns {boolean} Whether the magic bytes match the expected format.
+ */
+function validateMagic(buf, ext) {
+  if (buf.length < 4) return false;
+  switch (ext) {
+    case '.ttf': return buf.readUInt32BE(0) === 0x00010000;
+    case '.otf': return buf.readUInt32BE(0) === 0x4F54544F; // 'OTTO'
+    case '.woff': {
+      const sig = buf.slice(0, 4).toString('ascii');
+      return sig === 'wOFF';
+    }
+    case '.woff2': {
+      const sig = buf.slice(0, 4).toString('ascii');
+      return sig === 'wOF2';
+    }
+    case '.eot': return true; // EOT has no consistent magic
+    default: return false;
+  }
+}
+
+/**
+ * Analyze a single font file.
+ *
+ * @param {string} filePath - Absolute or relative path to the font file.
+ * @returns {{ file: string, path: string, format: string, size: number, sizeStr: string, valid: boolean }}
+ */
+function analyzeFontFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const format = EXT_FORMAT[ext] || 'Unknown';
+  const stat = fs.statSync(filePath);
+  const buf = fs.readFileSync(filePath);
+  const valid = validateMagic(buf, ext);
+
+  return {
+    file: path.basename(filePath),
+    path: filePath,
+    format,
+    size: stat.size,
+    sizeStr: formatSize(stat.size),
+    valid,
+  };
+}
+
+/**
+ * Recursively find all font files in a directory.
+ *
+ * @param {string} dir - Directory to walk.
+ * @returns {object[]} Array of objects from {@link analyzeFontFile}.
+ */
+function findFonts(dir) {
+  const results = [];
+
+  function walk(d) {
+    let entries;
+    try { entries = fs.readdirSync(d); } catch { return; }
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry === '.git') continue;
+      const fp = path.join(d, entry);
+      let st;
+      try { st = fs.statSync(fp); } catch { continue; }
+      if (st.isDirectory()) {
+        walk(fp);
+      } else if (FONT_EXTS.has(path.extname(entry).toLowerCase())) {
+        try { results.push(analyzeFontFile(fp)); } catch { /* skip unreadable */ }
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+/**
+ * Parse unicode-range declarations from CSS and return the set of code points referenced.
+ *
+ * @param {string} cssContent - Raw CSS text (may contain @font-face blocks).
+ * @returns {Set<number>} Set of Unicode code points.
+ */
+function extractUsedChars(cssContent) {
+  if (typeof cssContent !== 'string') throw new TypeError('cssContent must be a string');
+  const codePoints = new Set();
+  const rangeDecls = cssContent.match(/unicode-range\s*:\s*([^;]+)/gi) || [];
+
+  for (const decl of rangeDecls) {
+    const value = decl.replace(/unicode-range\s*:\s*/i, '').trim();
+    for (const segment of value.split(',')) {
+      const s = segment.trim();
+      // Match U+XXXX or U+XXXX-XXXX
+      const m = s.match(/U\+([0-9A-Fa-f]+)(?:-([0-9A-Fa-f]+))?/i);
+      if (!m) continue;
+      const start = parseInt(m[1], 16);
+      const end = m[2] ? parseInt(m[2], 16) : start;
+      for (let cp = start; cp <= end && cp <= 0x10FFFF; cp++) {
+        codePoints.add(cp);
+      }
+    }
+  }
+
+  return codePoints;
+}
+
+/**
+ * Estimate WOFF2 conversion savings for a list of analyzed fonts.
+ *
+ * Fonts already in WOFF2 format are assumed to have no savings.
+ * Other formats are estimated to save ~30 % after conversion.
+ *
+ * @param {object[]} fonts - Array from {@link findFonts} or {@link analyzeFontFile}.
+ * @returns {object[]} Same array with added suggestedFormat, potentialSavings, savingsStr.
+ */
+function suggestSubset(fonts) {
+  return fonts.map(f => {
+    const savings = f.format === 'WOFF2' ? 0 : Math.round(f.size * 0.3);
+    return {
+      ...f,
+      suggestedFormat: 'WOFF2',
+      potentialSavings: savings,
+      savingsStr: formatSize(savings),
+    };
+  });
+}
+
+/**
+ * Format a byte count as a human-readable string.
+ *
+ * @param {number} bytes - Number of bytes.
+ * @returns {string} Human-readable size string.
+ */
+function formatSize(bytes) {
+  if (bytes < 1024) return bytes + 'B';
+  if (bytes < 1048576) return (bytes / 1024).toFixed(1) + 'KB';
+  return (bytes / 1048576).toFixed(2) + 'MB';
+}
+
+/**
+ * Format a detailed report for a list of analyzed font files.
+ *
+ * @param {object[]} fonts - Array from {@link findFonts}.
+ * @returns {string} Human-readable report.
+ */
+function formatReport(fonts) {
+  if (!fonts.length) return 'No font files found.';
+  const lines = [
+    `Font Analysis Report`,
+    `====================`,
+    `Found ${fonts.length} font file(s):`,
+    '',
+  ];
+  for (const f of fonts) {
+    lines.push(`  ${f.file}`);
+    lines.push(`    Format : ${f.format}`);
+    lines.push(`    Size   : ${f.sizeStr}`);
+    lines.push(`    Valid  : ${f.valid ? 'yes' : 'no'}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Produce a one-line summary of the font list.
+ *
+ * @param {object[]} fonts - Array from {@link findFonts}.
+ * @returns {string} Single-line summary.
+ */
+function summary(fonts) {
+  if (!fonts.length) return 'No fonts found.';
+  const totalSize = fonts.reduce((acc, f) => acc + f.size, 0);
+  const formats = [...new Set(fonts.map(f => f.format))].join(', ');
+  return `${fonts.length} font(s), ${formatSize(totalSize)} total, formats: ${formats}`;
+}
+
+module.exports = {
+  analyzeFontFile,
+  findFonts,
+  extractUsedChars,
+  suggestSubset,
+  formatSize,
+  formatReport,
+  summary,
+};

package/tests/fontsubset.test.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * @fileoverview Tests for fontsubset.
+ * @author idirdev
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  formatSize,
+  extractUsedChars,
+  suggestSubset,
+  findFonts,
+  formatReport,
+  summary,
+} = require('../src/index');
+
+// ── formatSize ────────────────────────────────────────────────────────────────
+
+describe('formatSize', () => {
+  it('formats byte values under 1 KB', () => {
+    assert.equal(formatSize(500), '500B');
+  });
+
+  it('formats kilobyte values', () => {
+    assert.ok(formatSize(2048).includes('KB'));
+  });
+
+  it('formats megabyte values', () => {
+    assert.ok(formatSize(2 * 1048576).includes('MB'));
+  });
+
+  it('handles zero bytes', () => {
+    assert.equal(formatSize(0), '0B');
+  });
+});
+
+// ── extractUsedChars ──────────────────────────────────────────────────────────
+
+describe('extractUsedChars', () => {
+  it('parses a basic unicode-range declaration', () => {
+    const chars = extractUsedChars('@font-face { unicode-range: U+0020-007F; }');
+    assert.ok(chars.size > 0);
+    // U+0041 = 'A', must be in the basic Latin range
+    assert.ok(chars.has(0x41));
+  });
+
+  it('returns empty set when no unicode-range is present', () => {
+    const chars = extractUsedChars('body { font-family: Arial; }');
+    assert.equal(chars.size, 0);
+  });
+
+  it('handles a single code point (no range)', () => {
+    const chars = extractUsedChars('unicode-range: U+0041;');
+    assert.ok(chars.has(0x41));
+    assert.equal(chars.size, 1);
+  });
+
+  it('handles multiple comma-separated ranges', () => {
+    const chars = extractUsedChars('unicode-range: U+0041, U+0042;');
+    assert.ok(chars.has(0x41));
+    assert.ok(chars.has(0x42));
+    assert.equal(chars.size, 2);
+  });
+});
+
+// ── suggestSubset ─────────────────────────────────────────────────────────────
+
+describe('suggestSubset', () => {
+  it('suggests WOFF2 for TrueType fonts', () => {
+    const r = suggestSubset([{ file: 'a.ttf', format: 'TrueType', size: 50000 }]);
+    assert.equal(r[0].suggestedFormat, 'WOFF2');
+    assert.ok(r[0].potentialSavings > 0);
+  });
+
+  it('reports zero savings for fonts already in WOFF2', () => {
+    const r = suggestSubset([{ file: 'b.woff2', format: 'WOFF2', size: 30000 }]);
+    assert.equal(r[0].potentialSavings, 0);
+  });
+
+  it('preserves original font properties', () => {
+    const input = [{ file: 'c.woff', format: 'WOFF', size: 20000, sizeStr: '19.5KB' }];
+    const r = suggestSubset(input);
+    assert.equal(r[0].file, 'c.woff');
+    assert.equal(r[0].sizeStr, '19.5KB');
+  });
+
+  it('estimates ~30% savings for non-WOFF2 fonts', () => {
+    const size = 100000;
+    const r = suggestSubset([{ file: 'x.ttf', format: 'TrueType', size }]);
+    assert.equal(r[0].potentialSavings, Math.round(size * 0.3));
+  });
+});
+
+// ── findFonts ─────────────────────────────────────────────────────────────────
+
+describe('findFonts', () => {
+  it('returns an array (possibly empty) for a temp directory', () => {
+    const r = findFonts(os.tmpdir());
+    assert.ok(Array.isArray(r));
+  });
+
+  it('finds a fake .woff2 file written to a temp dir', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fontsubset-test-'));
+    const fakeFont = path.join(tmpDir, 'test.woff2');
+    // Write wOF2 magic bytes followed by padding
+    const buf = Buffer.alloc(16);
+    buf.write('wOF2', 0, 'ascii');
+    fs.writeFileSync(fakeFont, buf);
+    try {
+      const r = findFonts(tmpDir);
+      assert.ok(r.length >= 1);
+      assert.equal(r[0].format, 'WOFF2');
+    } finally {
+      fs.unlinkSync(fakeFont);
+      fs.rmdirSync(tmpDir);
+    }
+  });
+});
+
+// ── formatReport ──────────────────────────────────────────────────────────────
+
+describe('formatReport', () => {
+  it('returns a no-fonts message for empty array', () => {
+    assert.ok(formatReport([]).includes('No font files'));
+  });
+
+  it('includes file name and format in report', () => {
+    const report = formatReport([{ file: 'font.ttf', format: 'TrueType', sizeStr: '48.8KB', valid: true }]);
+    assert.ok(report.includes('font.ttf'));
+    assert.ok(report.includes('TrueType'));
+  });
+});
+
+// ── summary ───────────────────────────────────────────────────────────────────
+
+describe('summary', () => {
+  it('returns a message for empty font list', () => {
+    assert.ok(summary([]).includes('No fonts'));
+  });
+
+  it('reports correct file count', () => {
+    const fonts = [
+      { file: 'a.ttf', format: 'TrueType', size: 40000 },
+      { file: 'b.woff2', format: 'WOFF2', size: 20000 },
+    ];
+    const s = summary(fonts);
+    assert.ok(s.includes('2 font'));
+  });
+});