@describe-me/vitest 0.5.0-next.2 → 0.5.0

package/README.md

@@ -27,6 +27,10 @@ plugin detects where the tests run:
   warnings match a run without describe-me. It also works without user-event
   installed.
 
+jsdom has no layout, so positioned popovers show in the top-left corner and
+canvas stays blank
+([Limitations in jsdom](https://github.com/grzehub/describe-me#limitations-in-jsdom)).
+
 ```ts
 import { describeMe } from '@describe-me/vitest/plugin'
 

package/dist/font-audit.d.ts

@@ -0,0 +1,33 @@
+import { type FontMissing, type Manifest, type RemoteStylesheet } from '@describe-me/core/types';
+/** What the audit finds in a manifest. */
+export interface FontAuditResult {
+    fontsMissing: FontMissing[];
+    remoteStylesheets: RemoteStylesheet[];
+}
+/**
+ * Finds the font families that frames use but nothing loads, and the hosts
+ * that frames load stylesheets from. Snapshots, style chunks and assets are
+ * content-addressed, so what it read stays valid for the reporter's lifetime.
+ */
+export declare class FontAudit {
+    private readonly outDir;
+    private readonly chunks;
+    private readonly cssAssets;
+    private readonly snapshots;
+    constructor(outDir: string);
+    /** Walk the manifest in order. A file that cannot be read contributes nothing. */
+    audit(manifest: Manifest): FontAuditResult;
+    private addMissing;
+    /** Only the preview head's `@font-face` rules and font stylesheets count, not its own usage. */
+    private headFonts;
+    private snapshotFonts;
+    private readSnapshotFonts;
+    /**
+     * Add the CSS assets that stylesheets reach through asset links and
+     * `@import`s, transitively, and collect their remote URLs. Any other URL,
+     * such as a root-relative one left by a missing file, is ignored.
+     */
+    private reach;
+    private chunkUsage;
+    private cssAsset;
+}

package/dist/font-audit.js

@@ -0,0 +1,296 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ASSET_URL_PREFIX, } from '@describe-me/core/types';
+import { cssAssetReferences } from './css-asset-references.js';
+import { fontFamilyKey } from './font-family-key.js';
+import { fontShorthandFamilies } from './font-shorthand-families.js';
+import { fontStylesheetFamilies } from './font-stylesheet-families.js';
+import { fontUsage } from './font-usage.js';
+import { headStylesheets } from './head-stylesheets.js';
+import { isSystemFontFamily } from './system-font-family.js';
+import { snapshotStyles } from './snapshot-styles.js';
+/** A reference counts as level 1, so `--a: var(--b)` to `--c: Foo` still resolves. */
+const MAX_VAR_LEVELS = 3;
+/** The test server, whose URLs `assetsMissing` already covers. */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '0.0.0.0']);
+const REMOTE_URL = /^https?:/i;
+function isRemoteUrl(url) {
+    return REMOTE_URL.test(url) || url.startsWith('//');
+}
+/** The stored name behind a `describe-me-asset:` URL, or null for any other URL. */
+function assetName(url) {
+    if (!url.startsWith(ASSET_URL_PREFIX)) {
+        return null;
+    }
+    return url.slice(ASSET_URL_PREFIX.length).split(/[?#]/)[0];
+}
+function hostOf(url) {
+    const absolute = url.startsWith('//') ? `https:${url}` : url;
+    return URL.canParse(absolute) ? new URL(absolute).hostname : null;
+}
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function mergedVariables(usages) {
+    const variables = new Map();
+    for (const usage of usages) {
+        for (const [name, values] of usage.variables) {
+            variables.set(name, [...(variables.get(name) ?? []), ...values]);
+        }
+    }
+    return variables;
+}
+/**
+ * The first family of a custom property's value, or the `var()` in its place.
+ * A value reads as a `font` shorthand when it parses as one, and as a family
+ * list otherwise.
+ */
+function firstFamilyOf(value) {
+    const property = fontShorthandFamilies(value) === null ? 'font-family' : 'font';
+    const usage = fontUsage(`${property}: ${value}`);
+    return { family: usage.families[0], reference: usage.varRefs[0] };
+}
+function resolveVar(reference, variables, level) {
+    if (level > MAX_VAR_LEVELS) {
+        return [];
+    }
+    const definitions = variables.get(reference.name) ?? [];
+    let values = definitions;
+    if (definitions.length === 0) {
+        values = reference.fallback === undefined ? [] : [reference.fallback];
+    }
+    return values.flatMap((value) => {
+        const first = firstFamilyOf(value);
+        if (first.reference) {
+            return resolveVar(first.reference, variables, level + 1);
+        }
+        return first.family === undefined ? [] : [first.family];
+    });
+}
+/** Keys of the families remote stylesheets load, and whether any provider is unknown. */
+function remoteFamilies(urls) {
+    const loaded = new Set();
+    let unknownProvider = false;
+    for (const url of urls) {
+        const families = fontStylesheetFamilies(url);
+        if (families === null) {
+            unknownProvider = true;
+            continue;
+        }
+        for (const family of families) {
+            loaded.add(fontFamilyKey(family));
+        }
+    }
+    return { loaded, unknownProvider };
+}
+function remoteHosts(urls) {
+    const hosts = new Set();
+    for (const url of urls) {
+        const host = hostOf(url);
+        if (host && !LOOPBACK_HOSTS.has(host)) {
+            hosts.add(host);
+        }
+    }
+    return [...hosts];
+}
+function parsedJson(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The families that stylesheets and `style` attributes use, with each `var()`
+ * resolved against the stylesheets' custom properties. Keyed, with the first
+ * spelling, and without system families.
+ */
+function usedFamilies(sheets, attributes) {
+    const variables = mergedVariables(sheets);
+    const used = new Map();
+    const add = (family) => {
+        const key = fontFamilyKey(family);
+        if (!used.has(key) && !isSystemFontFamily(family)) {
+            used.set(key, family);
+        }
+    };
+    for (const usage of [...sheets, ...attributes]) {
+        usage.families.forEach(add);
+        for (const reference of usage.varRefs) {
+            resolveVar(reference, variables, 1).forEach(add);
+        }
+    }
+    return used;
+}
+function sortedMissing(missing) {
+    return [...missing.values()].sort((left, right) => right.tests - left.tests || left.family.localeCompare(right.family));
+}
+function sortedHosts(frames) {
+    return Array.from(frames, ([host, count]) => ({ host, frames: count })).sort((left, right) => right.frames - left.frames || left.host.localeCompare(right.host));
+}
+/**
+ * Finds the font families that frames use but nothing loads, and the hosts
+ * that frames load stylesheets from. Snapshots, style chunks and assets are
+ * content-addressed, so what it read stays valid for the reporter's lifetime.
+ */
+export class FontAudit {
+    outDir;
+    chunks = new Map();
+    cssAssets = new Map();
+    snapshots = new Map();
+    constructor(outDir) {
+        this.outDir = outDir;
+    }
+    /** Walk the manifest in order. A file that cannot be read contributes nothing. */
+    audit(manifest) {
+        const head = this.headFonts(manifest.head);
+        const missing = new Map();
+        const hostFrames = new Map();
+        for (const mod of manifest.modules) {
+            for (const test of mod.tests) {
+                const testMissing = new Map();
+                for (const frame of test.frames) {
+                    const fonts = this.snapshotFonts(frame.snapshot);
+                    for (const host of fonts.hosts) {
+                        hostFrames.set(host, (hostFrames.get(host) ?? 0) + 1);
+                    }
+                    if (!head.unknownProvider) {
+                        this.addMissing(testMissing, fonts, head);
+                    }
+                }
+                for (const [key, family] of testMissing) {
+                    const entry = missing.get(key);
+                    if (entry) {
+                        entry.tests++;
+                    }
+                    else {
+                        missing.set(key, { family, tests: 1, testId: test.id });
+                    }
+                }
+            }
+        }
+        return { fontsMissing: sortedMissing(missing), remoteStylesheets: sortedHosts(hostFrames) };
+    }
+    addMissing(testMissing, fonts, head) {
+        if (fonts.unknownProvider) {
+            return;
+        }
+        for (const [key, family] of fonts.used) {
+            if (!fonts.loaded.has(key) && !head.loaded.has(key) && !testMissing.has(key)) {
+                testMissing.set(key, family);
+            }
+        }
+    }
+    /** Only the preview head's `@font-face` rules and font stylesheets count, not its own usage. */
+    headFonts(head) {
+        const { styles, links } = headStylesheets(head ?? '');
+        const reached = this.reach(styles.map((css) => fontUsage(css)), links);
+        const remote = remoteFamilies(reached.remoteUrls);
+        const loaded = new Set(reached.usages.flatMap((usage) => usage.declared).map(fontFamilyKey));
+        for (const key of remote.loaded) {
+            loaded.add(key);
+        }
+        return { loaded, unknownProvider: remote.unknownProvider };
+    }
+    snapshotFonts(file) {
+        const cached = this.snapshots.get(file);
+        if (cached) {
+            return cached;
+        }
+        const { fonts, complete } = this.readSnapshotFonts(file);
+        if (complete) {
+            this.snapshots.set(file, fonts);
+        }
+        return fonts;
+    }
+    readSnapshotFonts(file) {
+        const json = readText(join(this.outDir, file));
+        const styles = snapshotStyles(json === null ? null : parsedJson(json));
+        const chunks = styles.chunks.map((hash) => this.chunkUsage(hash));
+        const sheets = styles.cssTexts.map((css) => fontUsage(css));
+        const reached = this.reach([...sheets, ...chunks.filter((usage) => usage !== null)], styles.stylesheetLinks);
+        const attributes = styles.styleAttributes.map((css) => fontUsage(css));
+        const remote = remoteFamilies(reached.remoteUrls);
+        for (const family of reached.usages.flatMap((usage) => usage.declared)) {
+            remote.loaded.add(fontFamilyKey(family));
+        }
+        const fonts = {
+            used: usedFamilies(reached.usages, attributes),
+            loaded: remote.loaded,
+            unknownProvider: remote.unknownProvider,
+            hosts: remoteHosts(reached.remoteUrls),
+        };
+        return { fonts, complete: json !== null && reached.complete && !chunks.includes(null) };
+    }
+    /**
+     * Add the CSS assets that stylesheets reach through asset links and
+     * `@import`s, transitively, and collect their remote URLs. Any other URL,
+     * such as a root-relative one left by a missing file, is ignored.
+     */
+    reach(sheets, links) {
+        const reached = { usages: [...sheets], remoteUrls: [], complete: true };
+        const seen = new Set();
+        const pending = [];
+        const follow = (url) => {
+            const name = assetName(url);
+            if (isRemoteUrl(url)) {
+                reached.remoteUrls.push(url);
+            }
+            else if (name !== null) {
+                pending.push(name);
+            }
+        };
+        links.forEach(follow);
+        sheets.forEach((usage) => usage.imports.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 = this.cssAsset(name);
+            if (asset === null) {
+                reached.complete = false;
+                continue;
+            }
+            reached.usages.push(asset.usage);
+            pending.push(...asset.siblings);
+            asset.usage.imports.filter(isRemoteUrl).forEach((url) => reached.remoteUrls.push(url));
+        }
+        return reached;
+    }
+    chunkUsage(hash) {
+        const cached = this.chunks.get(hash);
+        if (cached) {
+            return cached;
+        }
+        const css = readText(join(this.outDir, 'styles', `${hash}.css`));
+        if (css === null) {
+            return null;
+        }
+        const usage = fontUsage(css);
+        this.chunks.set(hash, usage);
+        return usage;
+    }
+    cssAsset(name) {
+        const cached = this.cssAssets.get(name);
+        if (cached) {
+            return cached;
+        }
+        const css = readText(join(this.outDir, 'assets', name));
+        if (css === null) {
+            return null;
+        }
+        const asset = {
+            usage: fontUsage(css),
+            siblings: cssAssetReferences(css).filter((sibling) => sibling.endsWith('.css')),
+        };
+        this.cssAssets.set(name, asset);
+        return asset;
+    }
+}

package/dist/font-family-key.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The key two spellings of one font family share, so `Noto+Sans+Arabic`,
+ * `'Noto Sans Arabic'` and `noto-sans-arabic` compare equal.
+ */
+export declare function fontFamilyKey(name: string): string;

package/dist/font-family-key.js

@@ -0,0 +1,14 @@
+/** Font URLs and CSS spell the gaps in a name as `+`, `-`, `_` or spaces. */
+const SEPARATORS = /[\s+_-]+/g;
+function unquoted(name) {
+    const first = name[0];
+    const isQuoted = name.length >= 2 && (first === '"' || first === "'") && name.endsWith(first);
+    return isQuoted ? name.slice(1, -1) : name;
+}
+/**
+ * The key two spellings of one font family share, so `Noto+Sans+Arabic`,
+ * `'Noto Sans Arabic'` and `noto-sans-arabic` compare equal.
+ */
+export function fontFamilyKey(name) {
+    return unquoted(name.trim().toLowerCase()).replace(SEPARATORS, ' ').trim();
+}

package/dist/font-family-list.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The names in a `font-family` value, unquoted, with their whitespace
+ * collapsed. Commas inside quotes or parentheses do not split, so
+ * `"Foo, Bar", serif` gives `Foo, Bar` and `serif`, and a `var()` stays whole.
+ */
+export declare function fontFamilyList(value: string): string[];

package/dist/font-family-list.js

@@ -0,0 +1,66 @@
+const WHITESPACE = /\s+/g;
+function commentEnd(value, open) {
+    const close = value.indexOf('*/', open + 2);
+    return close === -1 ? value.length : close + 2;
+}
+/** The unescaped text of the string opening at `open`, and where scanning goes on. */
+function readString(value, open) {
+    let text = '';
+    let index = open + 1;
+    while (index < value.length && value[index] !== value[open]) {
+        if (value[index] === '\\') {
+            text += value[index + 1] ?? '';
+            index += 2;
+            continue;
+        }
+        text += value[index];
+        index++;
+    }
+    return { text, next: index + 1 };
+}
+/**
+ * The names in a `font-family` value, unquoted, with their whitespace
+ * collapsed. Commas inside quotes or parentheses do not split, so
+ * `"Foo, Bar", serif` gives `Foo, Bar` and `serif`, and a `var()` stays whole.
+ */
+export function fontFamilyList(value) {
+    const names = [];
+    let current = '';
+    let depth = 0;
+    let index = 0;
+    while (index < value.length) {
+        const char = value[index];
+        if (char === '/' && value[index + 1] === '*') {
+            current += ' ';
+            index = commentEnd(value, index);
+            continue;
+        }
+        if (char === '\\') {
+            current += depth > 0 ? value.slice(index, index + 2) : (value[index + 1] ?? '');
+            index += 2;
+            continue;
+        }
+        if ((char === '"' || char === "'") && depth === 0) {
+            const string = readString(value, index);
+            current += string.text;
+            index = string.next;
+            continue;
+        }
+        if (char === ',' && depth === 0) {
+            names.push(current);
+            current = '';
+            index++;
+            continue;
+        }
+        if (char === '(') {
+            depth++;
+        }
+        else if (char === ')') {
+            depth = Math.max(0, depth - 1);
+        }
+        current += char;
+        index++;
+    }
+    names.push(current);
+    return names.map((name) => name.replace(WHITESPACE, ' ').trim()).filter((name) => name !== '');
+}

package/dist/font-shorthand-families.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The family list of a `font` shorthand value, such as `Inter` and
+ * `sans-serif` for `600 14px/1.5 Inter, sans-serif`. Null when the value is a
+ * keyword or has no size followed by a family.
+ */
+export declare function fontShorthandFamilies(value: string): string[] | null;

package/dist/font-shorthand-families.js

@@ -0,0 +1,177 @@
+import { fontFamilyList } from './font-family-list.js';
+/** Values that set the whole shorthand and name no family. */
+const KEYWORDS = new Set([
+    'inherit',
+    'initial',
+    'unset',
+    'revert',
+    'revert-layer',
+    'caption',
+    'icon',
+    'menu',
+    'message-box',
+    'small-caption',
+    'status-bar',
+]);
+const SIZE_KEYWORDS = new Set([
+    'xx-small',
+    'x-small',
+    'small',
+    'medium',
+    'large',
+    'x-large',
+    'xx-large',
+    'xxx-large',
+    'smaller',
+    'larger',
+]);
+const LENGTH_UNITS = new Set([
+    '%',
+    'px',
+    'em',
+    'rem',
+    'ex',
+    'rex',
+    'ch',
+    'rch',
+    'cap',
+    'rcap',
+    'ic',
+    'ric',
+    'lh',
+    'rlh',
+    'vw',
+    'vh',
+    'vi',
+    'vb',
+    'vmin',
+    'vmax',
+    'svw',
+    'svh',
+    'svi',
+    'svb',
+    'svmin',
+    'svmax',
+    'lvw',
+    'lvh',
+    'lvi',
+    'lvb',
+    'lvmin',
+    'lvmax',
+    'dvw',
+    'dvh',
+    'dvi',
+    'dvb',
+    'dvmin',
+    'dvmax',
+    'cqw',
+    'cqh',
+    'cqi',
+    'cqb',
+    'cqmin',
+    'cqmax',
+    'cm',
+    'mm',
+    'q',
+    'in',
+    'pt',
+    'pc',
+]);
+const SIZE_FUNCTIONS = ['calc(', 'clamp(', 'min(', 'max('];
+const NUMBER = /^[+-]?(?:\d+|\d*\.\d+)$/;
+const UNIT_CHARACTER = /[a-z%]/i;
+const WHITESPACE = /\s/;
+function commentEnd(value, open) {
+    const close = value.indexOf('*/', open + 2);
+    return close === -1 ? value.length : close + 2;
+}
+function stringEnd(value, open) {
+    let index = open + 1;
+    while (index < value.length && value[index] !== value[open]) {
+        index += value[index] === '\\' ? 2 : 1;
+    }
+    return index + 1;
+}
+/** Top-level tokens split at whitespace, with `/` as a token of its own. */
+function tokensOf(value) {
+    const tokens = [];
+    let current = null;
+    let depth = 0;
+    let index = 0;
+    const close = () => {
+        if (current !== null) {
+            tokens.push(current);
+            current = null;
+        }
+    };
+    while (index < value.length) {
+        const char = value[index];
+        if (char === '/' && value[index + 1] === '*') {
+            close();
+            index = commentEnd(value, index);
+            continue;
+        }
+        if (depth === 0 && (WHITESPACE.test(char) || char === '/')) {
+            close();
+            if (char === '/') {
+                tokens.push({ text: '/', start: index });
+            }
+            index++;
+            continue;
+        }
+        let next = index + 1;
+        if (char === '\\') {
+            next = index + 2;
+        }
+        else if (char === '"' || char === "'") {
+            next = stringEnd(value, index);
+        }
+        else if (char === '(') {
+            depth++;
+        }
+        else if (char === ')') {
+            depth = Math.max(0, depth - 1);
+        }
+        current ??= { text: '', start: index };
+        current.text += value.slice(index, next);
+        index = next;
+    }
+    close();
+    return tokens;
+}
+function isDimension(token) {
+    let end = token.length;
+    while (end > 0 && UNIT_CHARACTER.test(token[end - 1])) {
+        end--;
+    }
+    const unit = token.slice(end).toLowerCase();
+    return NUMBER.test(token.slice(0, end)) && LENGTH_UNITS.has(unit);
+}
+/** A bare number (`600`) is a weight and an angle is no size, so `font: 0/0 a` has none. */
+function isSize(token) {
+    const lower = token.toLowerCase();
+    return (SIZE_KEYWORDS.has(lower) ||
+        SIZE_FUNCTIONS.some((name) => lower.startsWith(name)) ||
+        isDimension(token));
+}
+/**
+ * The family list of a `font` shorthand value, such as `Inter` and
+ * `sans-serif` for `600 14px/1.5 Inter, sans-serif`. Null when the value is a
+ * keyword or has no size followed by a family.
+ */
+export function fontShorthandFamilies(value) {
+    if (KEYWORDS.has(value.trim().toLowerCase())) {
+        return null;
+    }
+    const tokens = tokensOf(value);
+    const size = tokens.findIndex((token) => isSize(token.text));
+    if (size === -1) {
+        return null;
+    }
+    const first = tokens[size + 1]?.text === '/' ? size + 3 : size + 1;
+    if (first >= tokens.length) {
+        return null;
+    }
+    const families = fontFamilyList(value.slice(tokens[first].start));
+    return families.length > 0 ? families : null;
+}

package/dist/font-stylesheet-families.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The families a remote stylesheet loads, read from its URL. Null when the
+ * provider is unknown: Google Fonts, Bunny Fonts and Fontsource on jsDelivr
+ * are the ones whose URLs name their families.
+ */
+export declare function fontStylesheetFamilies(url: string): string[] | null;

package/dist/font-stylesheet-families.js

@@ -0,0 +1,54 @@
+const GOOGLE_FONTS_HOST = 'fonts.googleapis.com';
+const GOOGLE_FONTS_PATHS = new Set(['/css', '/css2', '/icon']);
+const BUNNY_FONTS_HOST = 'fonts.bunny.net';
+const BUNNY_FONTS_PATHS = new Set(['/css', '/css2']);
+const JSDELIVR_HOST = 'cdn.jsdelivr.net';
+/** Fontsource names the family of `@fontsource-variable/inter` `Inter Variable`. */
+const FONTSOURCE_SCOPES = new Map([
+    ['@fontsource', ''],
+    ['@fontsource-variable', ' Variable'],
+]);
+function parsedUrl(url) {
+    const decoded = url.replaceAll('&', '&');
+    const absolute = decoded.startsWith('//') ? `https:${decoded}` : decoded;
+    return URL.canParse(absolute) ? new URL(absolute) : null;
+}
+/** `family=Open+Sans:400,700|Roboto+Mono`, repeated or not, as `Open Sans` and `Roboto Mono`. */
+function familyParameters(url) {
+    return url.searchParams
+        .getAll('family')
+        .flatMap((value) => value.split('|'))
+        .map((family) => family.split(':')[0].trim())
+        .filter((family) => family !== '');
+}
+/** `/npm/@fontsource/<package>[@version]/…` as the family the package loads. */
+function fontsourceFamilies(url) {
+    const [, registry, scope, name] = url.pathname.split('/');
+    const suffix = FONTSOURCE_SCOPES.get(scope);
+    const packageName = name?.split('@')[0];
+    if (registry !== 'npm' || suffix === undefined || !packageName) {
+        return null;
+    }
+    return [`${packageName}${suffix}`];
+}
+/**
+ * The families a remote stylesheet loads, read from its URL. Null when the
+ * provider is unknown: Google Fonts, Bunny Fonts and Fontsource on jsDelivr
+ * are the ones whose URLs name their families.
+ */
+export function fontStylesheetFamilies(url) {
+    const parsed = parsedUrl(url);
+    if (parsed === null) {
+        return null;
+    }
+    if (parsed.hostname === GOOGLE_FONTS_HOST && GOOGLE_FONTS_PATHS.has(parsed.pathname)) {
+        return familyParameters(parsed);
+    }
+    if (parsed.hostname === BUNNY_FONTS_HOST && BUNNY_FONTS_PATHS.has(parsed.pathname)) {
+        return familyParameters(parsed);
+    }
+    if (parsed.hostname === JSDELIVR_HOST) {
+        return fontsourceFamilies(parsed);
+    }
+    return null;
+}