describe-me 0.5.0 → 0.5.1

package/README.md

@@ -17,6 +17,9 @@ pnpm add -D describe-me @describe-me/vitest @describe-me/react
 `vite` is a peer dependency (Vitest requires it anyway): pnpm and npm install
 it automatically; with yarn, add `vite` to your `devDependencies`.
 
+All describe-me packages must be on the same version
+([Add it to your project](https://github.com/grzehub/describe-me#add-it-to-your-project)).
+
 ## Usage
 
 ```sh
@@ -39,9 +42,16 @@ viewport sizes and shareable links
 from Google Fonts, Bunny Fonts and Fontsource on jsDelivr into the site, so
 the docs show them offline. Adobe Fonts stay remote, because their license
 does not allow self-hosting, and so do fonts on any other host. The build
-lists both. Downloads are cached in `node_modules/.cache/describe-me/fonts`.
-A font that does not download keeps loading from the network, and the build
-never fails because of it.
+lists both.
+
+This needs the network. By default `build` connects to Google Fonts, Bunny
+Fonts and jsDelivr when the data loads fonts from them and the cache has no
+fresh copy. Downloads are cached in `node_modules/.cache/describe-me/fonts`,
+so after one online build later builds run offline. An unreachable host costs
+up to about 10 s once, then it is skipped. A font that does not download keeps
+loading from the network, and the build never fails because of it.
+`--no-vendor-fonts` keeps the build off the network, for CI without network
+access or with privacy rules.
 
 The static site uses relative URLs, so it works from a sub-path such as
 GitHub Pages.

package/dist-cli/file-names-in.d.ts

@@ -0,0 +1,2 @@
+/** The sorted names of the regular files in `dir` that end in `extension`, none when it is missing. */
+export declare function fileNamesIn(dir: string, extension: string): string[];

package/dist-cli/file-names-in.js

@@ -0,0 +1,11 @@
+import { existsSync, readdirSync } from 'node:fs';
+/** The sorted names of the regular files in `dir` that end in `extension`, none when it is missing. */
+export function fileNamesIn(dir, extension) {
+    if (!existsSync(dir)) {
+        return [];
+    }
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(extension))
+        .map((entry) => entry.name)
+        .sort();
+}

package/dist-cli/remote-stylesheets.d.ts

@@ -0,0 +1,7 @@
+import type { Manifest, RemoteStylesheet } from '@describe-me/core/types';
+/**
+ * The hosts that frames load stylesheets from, most frames first, counted
+ * from the files on disk by the rules of the reporter's `FontAudit`. It is a
+ * copy, because the viewer cannot depend on the reporter's package.
+ */
+export declare function remoteStylesheets(dataDir: string, manifest: Manifest): RemoteStylesheet[];

package/dist-cli/remote-stylesheets.js

@@ -0,0 +1,178 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cssReferences } from '@describe-me/core/css-references';
+import { ASSET_URL_PREFIX, STYLE_URL_PREFIX } from '@describe-me/core/types';
+/** The test server, left out as the reporter leaves it out. */
+const TEST_SERVER_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '0.0.0.0']);
+const REMOTE_URL = /^https?:/i;
+/** A stored asset's name: a content hash and, when the file has one, its extension. */
+const ASSET_NAME = /^[0-9a-f]{16}(\.[a-z0-9]+)?$/;
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function parsedJson(json) {
+    if (json === null) {
+        return null;
+    }
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+function isRemoteUrl(url) {
+    return REMOTE_URL.test(url) || url.startsWith('//');
+}
+function withoutQuery(url) {
+    return url.split(/[?#]/)[0];
+}
+function importsOf(css) {
+    return cssReferences(css)
+        .filter((reference) => reference.kind === 'import')
+        .map((reference) => reference.url);
+}
+function chunkImports(reader, hash) {
+    const known = reader.chunks.get(hash);
+    if (known !== undefined) {
+        return known;
+    }
+    const css = readText(join(reader.dataDir, 'styles', `${hash}.css`));
+    const imports = css === null ? [] : importsOf(css);
+    reader.chunks.set(hash, imports);
+    return imports;
+}
+function cssAsset(reader, name) {
+    const known = reader.cssAssets.get(name);
+    if (known !== undefined) {
+        return known;
+    }
+    const css = readText(join(reader.dataDir, 'assets', name)) ?? '';
+    const asset = {
+        remoteImports: importsOf(css).filter(isRemoteUrl),
+        siblings: cssReferences(css)
+            .map((reference) => withoutQuery(reference.url))
+            .filter((sibling) => ASSET_NAME.test(sibling) && sibling.endsWith('.css')),
+    };
+    reader.cssAssets.set(name, asset);
+    return asset;
+}
+function isNode(value) {
+    return typeof value === 'object' && value !== null;
+}
+function childrenOf(node) {
+    return Array.isArray(node.childNodes) ? node.childNodes.filter(isNode) : [];
+}
+function isStylesheetLink(node, attributes) {
+    const rel = attributes.rel;
+    return (node.tagName === 'link' &&
+        typeof rel === 'string' &&
+        rel.toLowerCase().split(/\s+/).includes('stylesheet'));
+}
+function cssTextImports(reader, cssText) {
+    if (!cssText.startsWith(STYLE_URL_PREFIX)) {
+        return importsOf(cssText);
+    }
+    const hashes = cssText.slice(STYLE_URL_PREFIX.length).split('+');
+    return hashes.flatMap((hash) => chunkImports(reader, hash));
+}
+/**
+ * Add the `@import` targets and stylesheet links of a node and everything
+ * below it. rrweb keeps shadow roots and iframe documents among the child
+ * nodes, so they are read too.
+ */
+function addTargets(reader, node, targets) {
+    const attributes = isNode(node.attributes) ? node.attributes : {};
+    const { _cssText: cssText, href } = attributes;
+    if (typeof cssText === 'string') {
+        targets.push(...cssTextImports(reader, cssText));
+    }
+    else if (isStylesheetLink(node, attributes) && typeof href === 'string') {
+        targets.push(href);
+    }
+    const children = childrenOf(node);
+    // rrweb writes the text of a `<style>` only when it could not read the sheet.
+    if (node.tagName === 'style') {
+        for (const child of children) {
+            if (typeof child.textContent === 'string' && child.textContent.trim() !== '') {
+                targets.push(...importsOf(child.textContent));
+            }
+        }
+    }
+    for (const child of children) {
+        addTargets(reader, child, targets);
+    }
+}
+function hostOf(url) {
+    const absolute = url.startsWith('//') ? `https:${url}` : url;
+    return URL.canParse(absolute) ? new URL(absolute).hostname : null;
+}
+/** The hosts of the remote stylesheets that targets reach, through CSS assets too. */
+function reachedHosts(reader, targets) {
+    const remoteUrls = [];
+    const pending = [];
+    const seen = new Set();
+    const follow = (url) => {
+        if (isRemoteUrl(url)) {
+            remoteUrls.push(url);
+        }
+        else if (url.startsWith(ASSET_URL_PREFIX)) {
+            pending.push(withoutQuery(url.slice(ASSET_URL_PREFIX.length)));
+        }
+    };
+    targets.forEach(follow);
+    for (let name = pending.pop(); name !== undefined; name = pending.pop()) {
+        if (seen.has(name) || !name.endsWith('.css')) {
+            continue;
+        }
+        seen.add(name);
+        const asset = cssAsset(reader, name);
+        remoteUrls.push(...asset.remoteImports);
+        pending.push(...asset.siblings);
+    }
+    const hosts = new Set();
+    for (const url of remoteUrls) {
+        const host = hostOf(url);
+        if (host && !TEST_SERVER_HOSTS.has(host)) {
+            hosts.add(host);
+        }
+    }
+    return [...hosts];
+}
+function snapshotHosts(reader, file) {
+    const known = reader.snapshots.get(file);
+    if (known !== undefined) {
+        return known;
+    }
+    const node = parsedJson(readText(join(reader.dataDir, file)));
+    const targets = [];
+    if (isNode(node)) {
+        addTargets(reader, node, targets);
+    }
+    const hosts = reachedHosts(reader, targets);
+    reader.snapshots.set(file, hosts);
+    return hosts;
+}
+/**
+ * The hosts that frames load stylesheets from, most frames first, counted
+ * from the files on disk by the rules of the reporter's `FontAudit`. It is a
+ * copy, because the viewer cannot depend on the reporter's package.
+ */
+export function remoteStylesheets(dataDir, manifest) {
+    const reader = { dataDir, chunks: new Map(), cssAssets: new Map(), snapshots: new Map() };
+    const frames = new Map();
+    const snapshots = manifest.modules.flatMap((mod) => {
+        return mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot));
+    });
+    for (const snapshot of snapshots) {
+        for (const host of snapshotHosts(reader, snapshot)) {
+            frames.set(host, (frames.get(host) ?? 0) + 1);
+        }
+    }
+    return Array.from(frames, ([host, count]) => ({ host, frames: count })).sort((left, right) => right.frames - left.frames || left.host.localeCompare(right.host));
+}

package/dist-cli/replace-asset-names.d.ts

@@ -0,0 +1,2 @@
+/** The text with each `describe-me-asset:` name that `renames` maps replaced by its new name. */
+export declare function replaceAssetNames(text: string, renames: Map<string, string>): string;

package/dist-cli/replace-asset-names.js

@@ -0,0 +1,13 @@
+import { ASSET_URL_PREFIX } from '@describe-me/core/types';
+/** A stored asset's name: a content hash and, when the file has one, its extension. */
+const ASSET_REFERENCE = new RegExp(`${ASSET_URL_PREFIX}([0-9a-f]{16}(?:\\.[a-z0-9]+)?)`, 'g');
+/** The text with each `describe-me-asset:` name that `renames` maps replaced by its new name. */
+export function replaceAssetNames(text, renames) {
+    if (renames.size === 0) {
+        return text;
+    }
+    return text.replace(ASSET_REFERENCE, (reference, name) => {
+        const renamed = renames.get(name);
+        return renamed === undefined ? reference : `${ASSET_URL_PREFIX}${renamed}`;
+    });
+}

package/dist-cli/replace-remote-urls.d.ts

@@ -0,0 +1,6 @@
+import type { TextSyntax } from './find-remote-urls.js';
+/**
+ * The text with `prefix` and the stored name written in place of every remote
+ * URL that `names` maps, left to right. Other URLs stay as written.
+ */
+export declare function replaceRemoteUrls(text: string, syntax: TextSyntax, prefix: string, names: Map<string, string>): string;

package/dist-cli/replace-remote-urls.js

@@ -0,0 +1,18 @@
+import { findRemoteUrls } from './find-remote-urls.js';
+/**
+ * The text with `prefix` and the stored name written in place of every remote
+ * URL that `names` maps, left to right. Other URLs stay as written.
+ */
+export function replaceRemoteUrls(text, syntax, prefix, names) {
+    const parts = [];
+    let last = 0;
+    for (const match of findRemoteUrls(text, syntax)) {
+        const name = names.get(match.url);
+        if (name !== undefined) {
+            parts.push(text.slice(last, match.start), `${prefix}${name}`);
+            last = match.end;
+        }
+    }
+    parts.push(text.slice(last));
+    return parts.join('');
+}

package/dist-cli/rewrite-stored-files.d.ts

@@ -0,0 +1,27 @@
+/** What a data directory held before the downloads, and what they stored. */
+export interface StoredFilesInput {
+    /** The stored name for each vendored URL. */
+    names: Map<string, string>;
+    /** Names of the `assets/*.css` files before the downloads. Only these may change. */
+    cssAssets: string[];
+    /** Paths of the texts in which the scan found a URL to vendor. */
+    kept: Set<string>;
+    /** Names of the files stored in this run. Their names are final. */
+    vendored: Set<string>;
+}
+/** What the rewrite changed. */
+export interface RewrittenFiles {
+    /** Old → new name of each CSS asset stored under a new name. */
+    assetRenames: Map<string, string>;
+    /** Whether a snapshot, style chunk or CSS asset changed. */
+    changed: boolean;
+    /** Paths of the files that renamed ones replace, to remove once nothing names them. */
+    replaced: string[];
+}
+/**
+ * Point the CSS assets, style chunks and snapshots of a data directory at the
+ * vendored files, in that order. A changed CSS asset or chunk moves to the
+ * hash of its new text before anything that names it changes. The files it
+ * replaces stay until the caller removes them.
+ */
+export declare function rewriteStoredFiles(dataDir: string, input: StoredFilesInput): RewrittenFiles;

package/dist-cli/rewrite-stored-files.js

@@ -0,0 +1,174 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cssReferences } from '@describe-me/core/css-references';
+import { ASSET_URL_PREFIX, STYLE_URL_PREFIX } from '@describe-me/core/types';
+import { fileNamesIn } from './file-names-in.js';
+import { replaceAssetNames } from './replace-asset-names.js';
+import { replaceRemoteUrls } from './replace-remote-urls.js';
+import { storeVendoredFile } from './store-vendored-file.js';
+/** A name that the style and asset stores gave: the sha1-16 of the text. */
+const CONTENT_NAME = /^[0-9a-f]{16}\.css$/;
+const STYLE_REFERENCE = new RegExp(`${STYLE_URL_PREFIX}([0-9a-f]{16}(?:\\+[0-9a-f]{16})*)`, 'g');
+/**
+ * Write a changed text. A content-named file moves to the hash of its new
+ * bytes, written only when missing, so identical texts share one file. Any
+ * other file keeps its name.
+ */
+function storeText(dir, name, text) {
+    if (!CONTENT_NAME.test(name)) {
+        writeFileSync(join(dir, name), text);
+        return name;
+    }
+    return storeVendoredFile(dir, new TextEncoder().encode(text), '.css');
+}
+/** The CSS with each target replaced from the end, so earlier offsets stay valid. */
+function replaceReferences(css, replacements) {
+    let rewritten = css;
+    for (const [reference, replacement] of [...replacements].reverse()) {
+        rewritten = rewritten.slice(0, reference.start) + replacement + rewritten.slice(reference.end);
+    }
+    return rewritten;
+}
+/** Each bare `.css` sibling that moved, with its query and fragment kept. */
+function siblingReplacements(run, css) {
+    return cssReferences(css).flatMap((reference) => {
+        const name = reference.url.split(/[?#]/)[0];
+        if (!CONTENT_NAME.test(name)) {
+            return [];
+        }
+        const finalName = resolveCssAsset(run, name);
+        if (finalName === name) {
+            return [];
+        }
+        return [[reference, `${finalName}${reference.url.slice(name.length)}`]];
+    });
+}
+function rewriteCssAsset(run, name) {
+    const css = readFileSync(join(run.dir, name), 'utf8');
+    const vendored = replaceRemoteUrls(css, 'css', '', run.names);
+    const rewritten = replaceReferences(vendored, siblingReplacements(run, vendored));
+    if (rewritten === css) {
+        return name;
+    }
+    run.changed = true;
+    return storeText(run.dir, name, rewritten);
+}
+/** The name a CSS asset ends up with, its siblings resolved first. */
+function resolveCssAsset(run, name) {
+    const known = run.finalNames.get(name);
+    if (known !== undefined) {
+        return known;
+    }
+    if (!run.listed.has(name)) {
+        return name;
+    }
+    // Content hashes cannot form a cycle, so this only stops a hand-made one.
+    if (run.resolving.has(name)) {
+        return name;
+    }
+    run.resolving.add(name);
+    const finalName = rewriteCssAsset(run, name);
+    run.resolving.delete(name);
+    run.finalNames.set(name, finalName);
+    return finalName;
+}
+function rewriteCssAssets(dataDir, input) {
+    const run = {
+        dir: join(dataDir, 'assets'),
+        names: input.names,
+        listed: new Set(input.cssAssets.filter((name) => !input.vendored.has(name))),
+        finalNames: new Map(),
+        resolving: new Set(),
+        changed: false,
+    };
+    for (const name of run.listed) {
+        resolveCssAsset(run, name);
+    }
+    const renames = new Map([...run.finalNames].filter(([name, finalName]) => finalName !== name));
+    return { renames, changed: run.changed };
+}
+function rewriteChunks(dataDir, input, assetRenames) {
+    const dir = join(dataDir, 'styles');
+    const result = { renames: new Map(), changed: false };
+    for (const name of fileNamesIn(dir, '.css')) {
+        const path = join(dir, name);
+        if (assetRenames.size === 0 && !input.kept.has(path)) {
+            continue;
+        }
+        const css = readFileSync(path, 'utf8');
+        const vendored = replaceRemoteUrls(css, 'css', ASSET_URL_PREFIX, input.names);
+        const rewritten = replaceAssetNames(vendored, assetRenames);
+        if (rewritten !== css) {
+            result.changed = true;
+            const stored = storeText(dir, name, rewritten);
+            if (stored !== name) {
+                result.renames.set(name, stored);
+            }
+        }
+    }
+    return result;
+}
+/** Each renamed hash inside a `describe-me-style:` reference, in the order written. */
+function replaceChunkHashes(json, renames) {
+    if (renames.size === 0) {
+        return json;
+    }
+    return json.replace(STYLE_REFERENCE, (_reference, hashes) => {
+        const renamed = hashes.split('+').map((hash) => renames.get(hash) ?? hash);
+        return `${STYLE_URL_PREFIX}${renamed.join('+')}`;
+    });
+}
+function hashRenames(chunkRenames) {
+    const hashOf = (name) => name.slice(0, -'.css'.length);
+    return new Map([...chunkRenames].map(([name, renamed]) => [hashOf(name), hashOf(renamed)]));
+}
+/** Snapshots keep their names, because the viewer always fetches them fresh. */
+function rewriteSnapshots(dataDir, input, assetRenames, chunkRenames) {
+    const dir = join(dataDir, 'snapshots');
+    const readAll = assetRenames.size > 0 || chunkRenames.size > 0;
+    const chunkHashes = hashRenames(chunkRenames);
+    let changed = false;
+    for (const name of fileNamesIn(dir, '.json')) {
+        const path = join(dir, name);
+        if (!readAll && !input.kept.has(path)) {
+            continue;
+        }
+        const json = readFileSync(path, 'utf8');
+        const vendored = replaceRemoteUrls(json, 'json', ASSET_URL_PREFIX, input.names);
+        const rewritten = replaceChunkHashes(replaceAssetNames(vendored, assetRenames), chunkHashes);
+        if (rewritten !== json) {
+            writeFileSync(path, rewritten);
+            changed = true;
+        }
+    }
+    return changed;
+}
+/** The old files that no new name reuses. */
+function replacedPaths(dir, renames, vendored) {
+    const finalNames = new Set(renames.values());
+    return [...renames.keys()]
+        .filter((name) => !finalNames.has(name) && !vendored.has(name))
+        .map((name) => join(dir, name));
+}
+/**
+ * Point the CSS assets, style chunks and snapshots of a data directory at the
+ * vendored files, in that order. A changed CSS asset or chunk moves to the
+ * hash of its new text before anything that names it changes. The files it
+ * replaces stay until the caller removes them.
+ */
+export function rewriteStoredFiles(dataDir, input) {
+    if (input.names.size === 0) {
+        return { assetRenames: new Map(), changed: false, replaced: [] };
+    }
+    const assets = rewriteCssAssets(dataDir, input);
+    const chunks = rewriteChunks(dataDir, input, assets.renames);
+    const snapshotsChanged = rewriteSnapshots(dataDir, input, assets.renames, chunks.renames);
+    return {
+        assetRenames: assets.renames,
+        changed: assets.changed || chunks.changed || snapshotsChanged,
+        replaced: [
+            ...replacedPaths(join(dataDir, 'assets'), assets.renames, input.vendored),
+            ...replacedPaths(join(dataDir, 'styles'), chunks.renames, new Set()),
+        ],
+    };
+}

package/dist-cli/store-vendored-file.d.ts

@@ -1,2 +1,5 @@
-/** Write a downloaded file into `assets/` under its content hash and return the name. */
-export declare function storeVendoredFile(assetsDir: string, bytes: Uint8Array, extension: string): string;
+/**
+ * Write a file into `dir` under its content hash and return the name. Downloads
+ * go into `assets/`, rewritten style chunks and CSS assets into their own directory.
+ */
+export declare function storeVendoredFile(dir: string, bytes: Uint8Array, extension: string): string;

package/dist-cli/store-vendored-file.js

@@ -1,12 +1,15 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { vendoredName } from './vendored-name.js';
-/** Write a downloaded file into `assets/` under its content hash and return the name. */
-export function storeVendoredFile(assetsDir, bytes, extension) {
+/**
+ * Write a file into `dir` under its content hash and return the name. Downloads
+ * go into `assets/`, rewritten style chunks and CSS assets into their own directory.
+ */
+export function storeVendoredFile(dir, bytes, extension) {
     const name = vendoredName(bytes, extension);
-    const target = join(assetsDir, name);
+    const target = join(dir, name);
     if (!existsSync(target)) {
-        mkdirSync(assetsDir, { recursive: true });
+        mkdirSync(dir, { recursive: true });
         writeFileSync(target, bytes);
     }
     return name;

package/dist-cli/vendor-fonts.d.ts

@@ -33,7 +33,10 @@ export interface VendorReport {
 /**
  * Download the web fonts that a data directory loads from known font hosts
  * into its `assets/`, and point the manifest head, snapshots, style chunks and
- * CSS assets at the copies. Meant for the copy inside a built site. Every file
- * is stored before any text changes, so a crash leaves only valid references.
+ * CSS assets at the copies. Meant for the copy inside a built site. A style
+ * chunk or CSS asset whose text changes moves to the hash of its new text, and
+ * the manifest's `remoteStylesheets` is counted again. Every file is stored
+ * before any text that names it changes, and replaced files are removed last,
+ * so a crash leaves only valid references.
  */
 export declare function vendorFonts(dataDir: string, options: VendorFontsOptions): Promise<VendorReport>;