@uxf/icons-generator 11.129.0 → 12.1.0

package/src/utils/_faProTarballCache.js

@@ -0,0 +1,379 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._getFaProPackage = _getFaProPackage;
+exports._getFaProDefaultVersion = _getFaProDefaultVersion;
+exports._resolveFaProSource = _resolveFaProSource;
+exports._locateEntry = _locateEntry;
+exports._prefetchFaProIcons = _prefetchFaProIcons;
+exports._readFaProSvg = _readFaProSvg;
+exports._getFaProIndex = _getFaProIndex;
+/* eslint-disable no-console */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const _npmRegistryConfig_1 = require("./_npmRegistryConfig");
+const _untar_1 = require("./_untar");
+/**
+ * Font Awesome kit holding every style the licence covers. A kit is the only
+ * distribution channel for the styles FA 7 added on top of classic/sharp/duotone,
+ * which is why the per-style npm packages can no longer be the source of truth.
+ */
+const DEFAULT_PACKAGE = "@awesome.me/kit-0618a3d496";
+/**
+ * Pinned, and pinned *here* rather than in each project's CI, because
+ * `src/fa-pro-types.ts` is generated from exactly this version and shipped in
+ * the same tarball. Keeping the two in one file is what stops them drifting:
+ * a name the union offers is always a name the archive really contains.
+ *
+ * Upgrading a kit is therefore one commit in this repo — bump this constant,
+ * run `npm run icon-types:gen`, release — and consumers pick the matching pair
+ * up by bumping `@uxf/icons-generator`. Nobody has to set an env var.
+ *
+ * `UXF_FA_PRO_VERSION=latest` asks the registry what the newest version is,
+ * which is how you find out that there is one.
+ */
+const DEFAULT_VERSION = "1.0.2";
+const DEFAULT_CACHE_ROOT = (0, path_1.join)((0, os_1.homedir)(), ".cache", "uxf-icons-generator");
+/**
+ * The one directory that holds a plain SVG per icon, grouped into a
+ * subdirectory per style. A kit nests it (`package/icons/svgs/<style>/`) while
+ * `@fortawesome/fontawesome-pro` does not (`package/svgs/<style>/`), so we
+ * anchor on the segment name rather than on its depth.
+ *
+ * Matching it exactly matters: every package also ships `svgs-full/`, a second
+ * copy of all ~85k icons, plus `sprites/`, `sprites-full/` and `webfonts/`,
+ * whose `.svg` files are whole sprite sheets and fonts rather than icons.
+ */
+const ICON_ROOT = "svgs";
+/**
+ * Bumped whenever {@link _locateEntry} changes what it derives, so a cached
+ * index written by an older build is discarded instead of silently reused —
+ * the package and version alone cannot express "same tarball, read differently".
+ */
+const INDEX_SCHEMA = 2;
+/* ------------------------------------------------------------------ paths */
+// `||` rather than `??` throughout: declaring a variable with an empty value
+// is how GitLab CI and shell wrappers spell "unset", and an empty package
+// name, version or cache root would each fail in a confusing way.
+function getCacheRoot() {
+    return process.env.UXF_FA_PRO_CACHE_ROOT || DEFAULT_CACHE_ROOT;
+}
+function _getFaProPackage() {
+    return process.env.UXF_FA_PRO_PACKAGE || DEFAULT_PACKAGE;
+}
+function _getFaProVersion() {
+    return process.env.UXF_FA_PRO_VERSION || DEFAULT_VERSION;
+}
+/** The version `src/fa-pro-types.ts` is expected to have been generated from. */
+function _getFaProDefaultVersion() {
+    return DEFAULT_VERSION;
+}
+function slugify(source) {
+    return `${source.package}@${source.version}`.replace(/[^a-zA-Z0-9.-]+/g, "_");
+}
+// The schema is part of the path, not just of `index.json`: the cached SVGs
+// were extracted under a particular reading of the archive too, so a bump
+// has to retire them along with the index.
+function sourceDir(source) {
+    return (0, path_1.join)(getCacheRoot(), "fa-pro", `v${INDEX_SCHEMA}`, slugify(source));
+}
+function indexFile(source) {
+    return (0, path_1.join)(sourceDir(source), "index.json");
+}
+function svgFile(source, namespace, iconName) {
+    return (0, path_1.join)(sourceDir(source), "svg", namespace, `${iconName}.svg`);
+}
+function writeFileAtomic(path, content) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+    // A crashed or concurrent run must never leave a half-written cache entry
+    // that later reads would treat as valid.
+    const tmp = `${path}.${process.pid}.tmp`;
+    (0, fs_1.writeFileSync)(tmp, content);
+    (0, fs_1.renameSync)(tmp, path);
+}
+/* --------------------------------------------------------------- registry */
+/**
+ * `what` decides how a rejection is explained: the same 404 means "this scope
+ * is not proxied" for a package lookup and "no such version" for a version
+ * lookup, and sending someone to reconfigure a working Verdaccio uplink over a
+ * mistyped version number wastes an afternoon.
+ */
+async function registryJson(url, accept, what) {
+    const packageName = _getFaProPackage();
+    const { authorization, registry } = (0, _npmRegistryConfig_1._resolveRegistryTarget)(packageName);
+    const response = await fetch(url, {
+        headers: { accept, ...(authorization ? { authorization } : {}) },
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new Error(`${registry} answered ${response.status} for ${packageName}.\n` +
+            `The credential it was given is missing or not accepted. Check the auth for this registry in .npmrc or .yarnrc.yml, and that the uplink's own Font Awesome token is still valid.\n` +
+            `Setup steps: docs/recipes/fontawesome-kit-verdaccio.md`);
+    }
+    if (response.status === 404 && what === "version") {
+        // The registry answers the same 404 for an unknown version and for an
+        // unknown package, and this endpoint cannot tell them apart.
+        throw new Error(`${registry} has no ${packageName}@${_getFaProVersion()}.\n` +
+            `Either the version is wrong — run with UXF_FA_PRO_VERSION=latest to see what is published — or the package name is.`);
+    }
+    if (response.status === 404) {
+        const scope = packageName.split("/").at(0);
+        throw new Error(`${registry} answered 404 for ${packageName}.\n` +
+            `Font Awesome publishes kits under the "${scope}" scope on https://npm.fontawesome.com/, so that scope needs its own uplink on our Verdaccio and a "${scope}:registry=" line in .npmrc (or npmScopes in .yarnrc.yml).\n` +
+            `Setup steps: docs/recipes/fontawesome-kit-verdaccio.md`);
+    }
+    if (!response.ok) {
+        throw new Error(`GET ${url} failed with ${response.status} ${response.statusText}.`);
+    }
+    return response.json();
+}
+let _sourcePromise;
+async function resolveSource() {
+    var _a;
+    const packageName = _getFaProPackage();
+    const requested = _getFaProVersion();
+    // Only an explicit "latest" asks the registry; anything else is a version
+    // we can use as-is, which keeps the common path free of network I/O.
+    if (requested !== "latest") {
+        return { package: packageName, version: requested };
+    }
+    const { registry } = (0, _npmRegistryConfig_1._resolveRegistryTarget)(packageName);
+    const packument = (await registryJson(`${registry}${packageName.replace("/", "%2f")}`, "application/vnd.npm.install-v1+json", "package"));
+    const version = (_a = packument["dist-tags"]) === null || _a === void 0 ? void 0 : _a.latest;
+    if (!version) {
+        throw new Error(`Registry ${registry} returned no "latest" dist-tag for ${packageName}.`);
+    }
+    return { package: packageName, version };
+}
+/**
+ * Resolve the package version to read icons from: {@link DEFAULT_VERSION}
+ * unless `UXF_FA_PRO_VERSION` overrides it, and only the literal `latest`
+ * consults the registry's mutable dist-tag.
+ *
+ * The promise is memoised so concurrent callers share one round trip, but a
+ * rejection is not: a transient network failure must not be sticky for the rest
+ * of the process, because the prefetch swallows it and later callers retry.
+ */
+function _resolveFaProSource() {
+    _sourcePromise !== null && _sourcePromise !== void 0 ? _sourcePromise : (_sourcePromise = resolveSource().catch((error) => {
+        _sourcePromise = undefined;
+        throw error;
+    }));
+    return _sourcePromise;
+}
+async function resolveTarballUrl(source) {
+    var _a;
+    const { registry } = (0, _npmRegistryConfig_1._resolveRegistryTarget)(source.package);
+    const manifest = (await registryJson(`${registry}${source.package.replace("/", "%2f")}/${source.version}`, "application/json", "version"));
+    const tarball = (_a = manifest.dist) === null || _a === void 0 ? void 0 : _a.tarball;
+    if (!tarball) {
+        throw new Error(`Registry ${registry} returned no tarball URL for ${source.package}@${source.version}.`);
+    }
+    return tarball;
+}
+async function openTarballStream(source) {
+    const url = await resolveTarballUrl(source);
+    const { authorization, registry } = (0, _npmRegistryConfig_1._resolveRegistryTarget)(source.package);
+    // `dist.tarball` is whatever the registry chose to put there, so it can
+    // point anywhere. The credential was issued for the registry and nobody
+    // else — send it only when the tarball is served from the same origin,
+    // which is how npm treats its own auth too.
+    const headers = new Headers();
+    if (authorization && new URL(url).origin === new URL(registry).origin) {
+        headers.set("authorization", authorization);
+    }
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`GET ${url} failed with ${response.status} ${response.statusText}.`);
+    }
+    if (!response.body) {
+        throw new Error(`GET ${url} returned an empty body.`);
+    }
+    // The tarball is never written to disk — it is gunzipped and parsed as it
+    // arrives, and only the SVGs a project references are kept.
+    return response.body.pipeThrough(new DecompressionStream("gzip"));
+}
+/**
+ * Derive the namespace an archive entry belongs to, or `null` for entries that
+ * are not per-icon SVGs (webfonts, sprites, the `svgs-full` duplicates, …).
+ *
+ * The namespace is the style directory verbatim, so `svgs/sharp-regular/x.svg`
+ * is `sharp-regular.x` — the same string the per-style npm packages produced.
+ */
+function _locateEntry(name) {
+    if (!name.endsWith(".svg")) {
+        return null;
+    }
+    const segments = name.split("/");
+    const root = segments.indexOf(ICON_ROOT);
+    // Exactly `<root>/<style>/<icon>.svg`: an icon file sits directly in its
+    // style directory, and anything deeper or shallower is not an icon.
+    if (root === -1 || segments.length !== root + 3) {
+        return null;
+    }
+    const [namespace, fileName] = segments.slice(root + 1);
+    const iconName = fileName.slice(0, -".svg".length);
+    if (namespace === "" || iconName === "") {
+        return null;
+    }
+    return { iconName, namespace };
+}
+/* ------------------------------------------------------------------ index */
+function readIndexFromDisk(source) {
+    const path = indexFile(source);
+    if (!(0, fs_1.existsSync)(path)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(path, "utf8"));
+        const isCurrent = parsed.schema === INDEX_SCHEMA && parsed.version === source.version && parsed.package === source.package;
+        return isCurrent ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Single streaming pass over the tarball, keeping the contents of `wanted` only.
+ *
+ * Without a `knownIndex` the pass also records every icon name it sees, which
+ * costs a full read of the archive. With one, the exact entry paths are already
+ * known, so the stream is cancelled as soon as the last wanted icon shows up.
+ */
+async function scanTarball(source, wanted, knownIndex) {
+    const seen = {};
+    const contents = new Map();
+    const stream = await openTarballStream(source);
+    const decoder = new TextDecoder();
+    for await (const entry of (0, _untar_1._untar)(stream, (name) => {
+        var _a;
+        var _b;
+        const location = _locateEntry(name);
+        if (!location) {
+            return false;
+        }
+        if (!knownIndex) {
+            ((_a = seen[_b = location.namespace]) !== null && _a !== void 0 ? _a : (seen[_b] = new Set())).add(location.iconName);
+        }
+        return wanted.has(`${location.namespace}.${location.iconName}`);
+    })) {
+        const location = _locateEntry(entry.name);
+        if (location) {
+            contents.set(`${location.namespace}.${location.iconName}`, decoder.decode(entry.content));
+        }
+        if (knownIndex && contents.size === wanted.size) {
+            break;
+        }
+    }
+    if (knownIndex) {
+        return { contents, index: null };
+    }
+    const icons = {};
+    for (const [namespace, names] of Object.entries(seen)) {
+        icons[namespace] = [...(names !== null && names !== void 0 ? names : [])].sort();
+    }
+    return {
+        contents,
+        index: { icons, package: source.package, schema: INDEX_SCHEMA, version: source.version },
+    };
+}
+/* ---------------------------------------------------------------- caching */
+function readCachedSvg(source, qualifiedName) {
+    const [namespace, ...rest] = qualifiedName.split(".");
+    const path = svgFile(source, namespace, rest.join("."));
+    return (0, fs_1.existsSync)(path) ? (0, fs_1.readFileSync)(path, "utf8") : null;
+}
+function writeCachedSvg(source, qualifiedName, svg) {
+    const [namespace, ...rest] = qualifiedName.split(".");
+    writeFileAtomic(svgFile(source, namespace, rest.join(".")), svg);
+}
+/* ------------------------------------------------------------------- API */
+const memory = new Map();
+/**
+ * Make sure every requested `"<namespace>.<icon-name>"` is available to
+ * {@link _readFaProSvg}, downloading the package tarball at most once.
+ *
+ * Icons already in the on-disk cache cost nothing but a file read, and since
+ * the version is pinned rather than resolved from a dist-tag, such a run makes
+ * no request at all.
+ */
+async function _prefetchFaProIcons(names) {
+    var _a;
+    const requested = [...new Set(names)];
+    if (requested.length === 0) {
+        return;
+    }
+    const source = await _resolveFaProSource();
+    const index = readIndexFromDisk(source);
+    const missing = new Set();
+    for (const qualifiedName of requested) {
+        if (memory.has(qualifiedName)) {
+            continue;
+        }
+        const cached = readCachedSvg(source, qualifiedName);
+        if (cached === null) {
+            missing.add(qualifiedName);
+        }
+        else {
+            memory.set(qualifiedName, cached);
+        }
+    }
+    if (missing.size === 0) {
+        return;
+    }
+    // With an index in hand we already know which icons the package does not
+    // have, so a typo costs nothing instead of a 100+ MB download. Membership
+    // is checked against a Set per namespace: the arrays run to ~4 800 names
+    // and a project can reference hundreds of icons.
+    if (index) {
+        const known = new Map();
+        for (const qualifiedName of [...missing]) {
+            const [namespace, ...rest] = qualifiedName.split(".");
+            let namespaceIcons = known.get(namespace);
+            if (!namespaceIcons) {
+                namespaceIcons = new Set((_a = index.icons[namespace]) !== null && _a !== void 0 ? _a : []);
+                known.set(namespace, namespaceIcons);
+            }
+            if (!namespaceIcons.has(rest.join("."))) {
+                missing.delete(qualifiedName);
+            }
+        }
+        if (missing.size === 0) {
+            return;
+        }
+    }
+    console.log(`Streaming ${missing.size} icon(s) from ${source.package}@${source.version}…`);
+    // Without an index this pass builds one on the way, so a cold cache still
+    // costs a single download rather than one for the index and one for the icons.
+    const { contents, index: builtIndex } = await scanTarball(source, missing, index !== null && index !== void 0 ? index : undefined);
+    if (builtIndex) {
+        writeFileAtomic(indexFile(source), JSON.stringify(builtIndex));
+    }
+    for (const [qualifiedName, svg] of contents) {
+        memory.set(qualifiedName, svg);
+        writeCachedSvg(source, qualifiedName, svg);
+    }
+}
+/** Read a prefetched icon. Returns `null` when the icon is not in the package. */
+function _readFaProSvg(qualifiedName) {
+    var _a;
+    return (_a = memory.get(qualifiedName)) !== null && _a !== void 0 ? _a : null;
+}
+let _indexPromise;
+async function loadIndex() {
+    const source = await _resolveFaProSource();
+    const fromDisk = readIndexFromDisk(source);
+    if (fromDisk) {
+        return fromDisk;
+    }
+    const { index } = await scanTarball(source, new Set());
+    if (!index) {
+        throw new Error(`Could not index ${source.package}@${source.version}.`);
+    }
+    writeFileAtomic(indexFile(source), JSON.stringify(index));
+    return index;
+}
+/** Namespaces the resolved package provides, with their icon names. */
+function _getFaProIndex() {
+    _indexPromise !== null && _indexPromise !== void 0 ? _indexPromise : (_indexPromise = loadIndex());
+    return _indexPromise;
+}

package/src/utils/_generateAdapterFallback.js

@@ -7,7 +7,9 @@ function _generateAdapterFallback(key, iconName, iconDefinition, config) {
     (0, _createPath_1._createPath)(config.configFile);
     (0, _createPath_1._createPath)(config.fallbackFilesDirectory);
     const filePath = config.fallbackFilesDirectory + key + ".json";
-    const currentContent = (0, fs_1.readFileSync)(filePath).toString();
+    // The snapshot is written by this function and by nothing else, so on a
+    // project adopting a provider for the first time it does not exist yet.
+    const currentContent = (0, fs_1.existsSync)(filePath) ? (0, fs_1.readFileSync)(filePath).toString() : "";
     const content = currentContent ? JSON.parse(currentContent) : {};
     content[iconName] = iconDefinition;
     (0, fs_1.writeFileSync)(filePath, JSON.stringify(content));

package/src/utils/_generateSpriteFile.js

@@ -6,5 +6,9 @@ const _createPath_1 = require("./_createPath");
 const _createSpriteContent_1 = require("./_createSpriteContent");
 function _generateSpriteFile(config) {
     (0, _createPath_1._createPath)(config.configFile);
+    // The sprite lands in `generatedDirectory`, which on a project generating
+    // icons for the first time does not exist yet — `configFile` above only
+    // covers the directory the definition file goes into.
+    (0, _createPath_1._createPath)(config.spriteFile);
     (0, fs_1.writeFileSync)(config.spriteFile, (0, _createSpriteContent_1._createSpriteContent)(config));
 }

package/src/utils/_npmRegistryConfig.d.ts

@@ -0,0 +1,13 @@
+export interface RegistryTarget {
+    /** Registry base URL, always with a trailing slash. */
+    registry: string;
+    /** Ready-made `Authorization` header value, or `undefined` for anonymous. */
+    authorization?: string;
+}
+/**
+ * Work out which registry serves a scoped package and how to authenticate
+ * against it, reading the same `.npmrc` / `.yarnrc.yml` files the package
+ * manager would. Consumer projects are on Yarn while this monorepo is on npm,
+ * so both have to be understood.
+ */
+export declare function _resolveRegistryTarget(packageName: string): RegistryTarget;