@fusion.dev/helix-diagnostics 0.137.0 → 0.139.0

package/dist/init.js

@@ -0,0 +1,326 @@
+import { checkConfig, LOCAL, resolveConfig } from './config.js';
+import { report as print } from './console.js';
+import { diagnose } from './diagnose.js';
+import { overlayOn } from './overlay.js';
+import { schedule } from './schedule.js';
+import { loadedVersions, watch } from './usage.js';
+export const INSTANCE = Symbol.for('fusion.dev/helix/diagnostics');
+const CDN = 'https://cdn.jsdelivr.net/npm';
+const RELAY = 'http://127.0.0.1:7417';
+const KEEPALIVE = 60_000;
+const FAILURES = 3;
+const inert = () => ({
+    active: false,
+    latest: undefined,
+    run: () => undefined,
+    stop: () => { },
+    subscribe: () => () => { },
+});
+const said = new Set();
+const once = (key, print) => {
+    if (said.has(key)) {
+        return;
+    }
+    said.add(key);
+    try {
+        print();
+    }
+    catch {
+    }
+};
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+export const initDiagnostics = (options = {}) => {
+    const page = globalThis.document;
+    if (page === undefined) {
+        return inert();
+    }
+    const store = globalThis;
+    const existing = store[INSTANCE];
+    if (existing?.active) {
+        return existing;
+    }
+    try {
+        const started = start(options, page);
+        if (started.active) {
+            store[INSTANCE] = started;
+        }
+        return started;
+    }
+    catch (error) {
+        once(`start ${messageOf(error)}`, () => console.error('helix diagnostics: not started, and the page goes on as usual.', error));
+        return inert();
+    }
+};
+const start = (options, page) => {
+    const { cdn = CDN, duplicates, environment, file, onReport, page: route, tiers, ...call } = options;
+    let configuration;
+    try {
+        configuration = resolveConfig(file, call).configuration;
+    }
+    catch (error) {
+        once(`settings ${messageOf(error)}`, () => console.error(`helix diagnostics: not started. ${messageOf(error)}`));
+        return inert();
+    }
+    const host = globalThis.location?.hostname ?? '';
+    if (environment === undefined && !LOCAL.test(host)) {
+        once(`host ${host}`, () => console.info(`helix diagnostics: not running on ${host || 'this page'}, which is no local host, with no environment declared. Pass \`environment\` to run here.`));
+        return inert();
+    }
+    if (environment === 'production') {
+        const production = configuration.environments.production;
+        if (production === false || Math.random() >= production.sample) {
+            return inert();
+        }
+    }
+    return running({
+        call,
+        cdn,
+        duplicates,
+        environment,
+        file,
+        onReport,
+        page,
+        route,
+        sinks: configuration.sinks,
+        tiers,
+    });
+};
+const running = (given) => {
+    const { call, cdn, duplicates, environment, page, route, sinks } = given;
+    const production = environment === 'production';
+    const development = environment === undefined || environment === 'development';
+    let file = given.file;
+    let overlay;
+    const relay = production ? undefined : sinks.relay === true ? RELAY : sinks.relay || undefined;
+    let relayed = false;
+    const sent = new Map();
+    const listeners = new Set();
+    if (given.onReport) {
+        listeners.add(given.onReport);
+    }
+    const shown = new Map();
+    let lint = given.tiers;
+    let loading = false;
+    let latest;
+    let failures = 0;
+    let active = true;
+    const deliver = (where, send) => {
+        try {
+            send();
+        }
+        catch (error) {
+            once(`sink ${where}`, () => console.error(`helix diagnostics: ${where} threw on a run, and the others had it.`, error));
+        }
+    };
+    const runNow = () => {
+        const begun = globalThis.performance?.now() ?? Date.now();
+        if (!active) {
+            return 0;
+        }
+        if (!lint) {
+            load();
+            return 0;
+        }
+        let path;
+        try {
+            path = route?.();
+        }
+        catch {
+            path = undefined;
+        }
+        let run;
+        try {
+            run = diagnose({
+                ...call,
+                duplicates,
+                environment,
+                file,
+                from: page,
+                page: path,
+                tiers: lint,
+                watcher,
+            });
+            failures = 0;
+        }
+        catch (error) {
+            failures += 1;
+            once(`run ${messageOf(error)}`, () => console.error('helix diagnostics: a run failed.', error));
+            if (failures >= FAILURES) {
+                once('stopped', () => console.error(`helix diagnostics: stopped after ${FAILURES} failed runs in a row, and the page goes on as usual.`));
+                stop();
+            }
+            return (globalThis.performance?.now() ?? Date.now()) - begun;
+        }
+        latest = run;
+        const key = run.run.page ?? '';
+        const seen = shown.get(key) ?? new Set();
+        shown.set(key, seen);
+        if (!production) {
+            deliver('the console', () => print(run, console, { shown: seen }));
+        }
+        for (const listener of listeners) {
+            deliver('a subscriber', () => listener(run));
+        }
+        deliver('the helix-diagnostics event', () => page.dispatchEvent(new CustomEvent('helix-diagnostics', { detail: run })));
+        if (sinks.overlay && development) {
+            deliver('the overlay', () => {
+                if (overlay || run.findings.length > 0) {
+                    overlay ??= overlayOn(page);
+                    overlay.show(run);
+                }
+            });
+        }
+        if (relay && relayed) {
+            deliver('the relay', () => {
+                const same = JSON.stringify([
+                    run.findings.map((one) => [one.fingerprint, one.severity]),
+                    run.coverage.read,
+                    run.coverage.sheets,
+                    run.usage.tags,
+                ]);
+                if (sent.get(key) === same) {
+                    return;
+                }
+                sent.set(key, same);
+                const body = JSON.stringify(run);
+                fetch(`${relay}/runs`, {
+                    body,
+                    credentials: 'omit',
+                    headers: { 'content-type': 'text/plain' },
+                    keepalive: body.length < KEEPALIVE,
+                    method: 'POST',
+                }).catch(() => {
+                    relayed = false;
+                    once('relay gone', () => console.warn('helix diagnostics: the relay stopped answering, so runs are no longer sent to it.'));
+                });
+            });
+        }
+        return run.run.duration;
+    };
+    const load = () => {
+        if (loading || cdn === false) {
+            if (cdn === false) {
+                once('no lint', () => console.warn('helix diagnostics: no lint data, since `cdn` is false and no `tiers` were given, so this page is not checked.'));
+            }
+            return;
+        }
+        const [version] = loadedVersions();
+        if (version === undefined) {
+            return;
+        }
+        const counts = watcher.counts();
+        const tags = [...Object.keys(counts.tags), ...Object.keys(counts.composed)];
+        const styled = tags.some((tag) => tag.startsWith('helix-') && !tag.startsWith('helix-headless-'));
+        const packages = styled
+            ? ['@fusion.dev/helix', '@fusion.dev/helix-headless']
+            : ['@fusion.dev/helix-headless'];
+        loading = true;
+        Promise.all(packages.map(async (name) => {
+            const url = `${cdn}/${name}@${version}/lint.json`;
+            const response = await fetch(url, { credentials: 'omit' });
+            if (!response.ok) {
+                throw new Error(`${url} answered ${response.status}`);
+            }
+            const data = (await response.json());
+            if (typeof data?.tags !== 'object' || data.tags === null) {
+                throw new Error(`${url} is not lint data`);
+            }
+            return { lint: data };
+        })).then((loaded) => {
+            lint = loaded;
+            plan.poke();
+        }, (error) => {
+            once('no lint', () => console.warn(`helix diagnostics: the lint data for Helix ${version} could not be loaded (${messageOf(error)}), so this page is not checked. Pass \`tiers\` to initDiagnostics() to check it without the network.`));
+        });
+    };
+    if (relay) {
+        const ask = (path) => fetch(`${relay}${path}`, {
+            credentials: 'omit',
+            ...(typeof AbortSignal.timeout === 'function' ? { signal: AbortSignal.timeout(1000) } : {}),
+        });
+        ask('/health')
+            .then(async (answer) => {
+            if (!answer.ok) {
+                throw new Error(`it answered ${answer.status}`);
+            }
+            relayed = true;
+            if (!given.file) {
+                const settings = await ask('/config');
+                if (settings.ok) {
+                    const served = (await settings.json());
+                    try {
+                        checkConfig(served, 'file');
+                        file = served;
+                    }
+                    catch (error) {
+                        once(`relay settings ${messageOf(error)}`, () => console.error(`helix diagnostics: the settings the relay served were not used. ${messageOf(error)}`));
+                    }
+                }
+            }
+            plan.poke();
+        })
+            .catch((error) => once('no relay', () => console.warn(`helix diagnostics: no relay at ${relay} (${messageOf(error)}). Start it with \`helix diagnostics\`, or turn \`sinks.relay\` off.`)));
+    }
+    const plan = schedule(runNow);
+    const watcher = watch(page, { onRender: () => plan.poke() });
+    const poke = () => plan.poke();
+    const observer = typeof MutationObserver === 'function'
+        ? new MutationObserver((records) => {
+            if (records.some((record) => [...record.addedNodes, ...record.removedNodes].some((node) => node !== overlay?.element))) {
+                poke();
+            }
+        })
+        : undefined;
+    observer?.observe(page.documentElement, { childList: true, subtree: true });
+    const navigation = globalThis.navigation;
+    if (navigation) {
+        navigation.addEventListener('navigatesuccess', poke);
+    }
+    else {
+        globalThis.addEventListener?.('popstate', poke);
+        globalThis.addEventListener?.('hashchange', poke);
+    }
+    if (page.readyState === 'complete') {
+        poke();
+    }
+    else {
+        globalThis.addEventListener?.('load', poke, { once: true });
+    }
+    const stop = () => {
+        if (!active) {
+            return;
+        }
+        active = false;
+        plan.stop();
+        observer?.disconnect();
+        watcher.stop();
+        navigation?.removeEventListener('navigatesuccess', poke);
+        globalThis.removeEventListener?.('popstate', poke);
+        globalThis.removeEventListener?.('hashchange', poke);
+        globalThis.removeEventListener?.('load', poke);
+        listeners.clear();
+        overlay?.remove();
+        const store = globalThis;
+        if (store[INSTANCE] === handle) {
+            delete store[INSTANCE];
+        }
+    };
+    const handle = {
+        get active() {
+            return active;
+        },
+        get latest() {
+            return latest;
+        },
+        run: () => {
+            runNow();
+            return latest;
+        },
+        stop,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+    return handle;
+};

package/dist/manifest.d.ts

@@ -29,6 +29,18 @@ export interface ManifestSource {
         /** Where the module is, which names the family: `src/button/root/button-root.ts`. */
         path?: string;
         declarations?: Array<{
+            attributes?: Array<{
+                name: string;
+                type?: {
+                    text?: string;
+                };
+            }>;
+            members?: Array<{
+                kind?: string;
+                name: string;
+                readonly?: boolean;
+                static?: boolean;
+            }>;
             cssParts?: Array<{
                 name: string;
             }>;
@@ -39,12 +51,50 @@ export interface ManifestSource {
         }>;
     }>;
 }
-/** One manifest, and which tier shipped it. */
-export interface Tier {
+/**
+ * What diagnostics reads of one package's manifest, and nothing else: per
+ * tag, the parts, the hooks, the attributes with the values each allows, the
+ * attributes the element writes on itself, and the family.
+ *
+ * **About a seventieth of the manifest.** Measured 4 Oct 2026: 124 KB for the
+ * styled tier and 103 KB for the headless one, 18 KB and 14 KB compressed,
+ * against manifests of 8.6 MB and 7.0 MB. `analyze` writes it beside each
+ * `custom-elements.json` as `lint.json`, and every Helix package publishes
+ * it, so a page can load the data for exactly the version it runs.
+ */
+export interface LintData {
+    /** The package the data describes. */
+    package: string;
+    tags: Record<string, LintTag>;
+    /** The package's version, where the manifest says. */
+    version?: string | undefined;
+}
+/** What one tag publishes, as lint data says it. */
+export interface LintTag {
+    /** Each attribute, with the values it allows, or `null` where it takes any. */
+    attributes: Record<string, string[] | null>;
+    /** The family, from the module's path. */
+    family?: string | undefined;
+    hooks: string[];
+    parts: string[];
+    /** The attributes the element writes on itself: one named for a read-only member. */
+    written: string[];
+}
+/**
+ * One installed tier: its manifest, with the package name, or its lint data,
+ * which names the package itself.
+ */
+export type Tier = {
     manifest: ManifestSource;
     /** Package name, used verbatim in a finding's message. */
     name: string;
-}
+} | {
+    lint: LintData;
+};
+/** The lint data for a manifest: what `analyze` writes, and what `index` reads. */
+export declare const lintOf: (manifest: ManifestSource, name: string) => LintData;
+/** A tier's lint data, read from its lint data or derived from its manifest. */
+export declare const lintFor: (tier: Tier) => LintData;
 /**
  * What one tag publishes, per tier.
  *
@@ -52,9 +102,20 @@ export interface Tier {
  * scope, and `analyze.ts` needs both in the same file.
  */
 export interface Published {
+    /**
+     * Each attribute the tag takes, with the values it allows where its type
+     * is a union of string literals, and `null` where it takes any value.
+     */
+    attributes: Map<string, Set<string> | null>;
     /** The family, from the module's path: `button` for `src/button/root/button-root.ts`. */
     family?: string | undefined;
     hooks: Map<string, Set<string>>;
+    /**
+     * The attributes the element writes on itself: one named for a read-only
+     * member, as `helix-notifications` writes `unread`. Output, so never a
+     * finding when the page shows it.
+     */
+    written: Set<string>;
     parts: Map<string, Set<string>>;
 }
 /**
@@ -80,4 +141,4 @@ export declare const versionsOf: (tiers: Tier[]) => Record<string, string>;
  * `--button-background-color` however close they sort, and a confident wrong
  * suggestion costs more than none.
  */
-export declare const nearest: (wrong: string, candidates: Iterable<string>) => string | undefined;
+export declare const nearest: (wrong: string, candidates: Iterable<string>, ceiling?: number) => string | undefined;

package/dist/manifest.js

@@ -1,46 +1,105 @@
+export const lintOf = (manifest, name) => {
+    const tags = {};
+    for (const module of manifest.modules ?? []) {
+        const family = /^src\/([^/]+)\//.exec(module.path ?? '')?.[1];
+        for (const declaration of module.declarations ?? []) {
+            const tag = declaration.tagName;
+            if (!tag) {
+                continue;
+            }
+            const entry = tags[tag] ?? {
+                attributes: {},
+                family,
+                hooks: [],
+                parts: [],
+                written: [],
+            };
+            tags[tag] = entry;
+            for (const member of declaration.members ?? []) {
+                if (member.readonly && !member.static && member.kind === 'field') {
+                    entry.written.push(member.name, member.name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`));
+                }
+            }
+            for (const attribute of declaration.attributes ?? []) {
+                const values = allowed(attribute.type?.text);
+                entry.attributes[attribute.name] = values ? [...values] : null;
+            }
+            entry.parts.push(...(declaration.cssParts ?? []).map((part) => part.name));
+            entry.hooks.push(...(declaration.cssProperties ?? []).map((hook) => hook.name));
+        }
+    }
+    for (const entry of Object.values(tags)) {
+        entry.written = [...new Set(entry.written)];
+        entry.parts = [...new Set(entry.parts)];
+        entry.hooks = [...new Set(entry.hooks)];
+    }
+    return {
+        package: manifest.helix?.package ?? name,
+        tags,
+        ...(manifest.helix?.version ? { version: manifest.helix.version } : {}),
+    };
+};
+export const lintFor = (tier) => 'lint' in tier ? tier.lint : lintOf(tier.manifest, tier.name);
 export const index = (tiers) => {
     const tags = new Map();
     for (const tier of tiers) {
-        for (const module of tier.manifest.modules ?? []) {
-            const family = /^src\/([^/]+)\//.exec(module.path ?? '')?.[1];
-            for (const declaration of module.declarations ?? []) {
-                const tag = declaration.tagName;
-                if (!tag) {
-                    continue;
-                }
-                let element = tags.get(tag);
-                if (!element) {
-                    element = { family, hooks: new Map(), parts: new Map() };
-                    tags.set(tag, element);
-                }
-                for (const [field, into] of [
-                    [declaration.cssParts, element.parts],
-                    [declaration.cssProperties, element.hooks],
-                ]) {
-                    for (const entry of field ?? []) {
-                        const publishers = into.get(entry.name) ?? new Set();
-                        publishers.add(tier.name);
-                        into.set(entry.name, publishers);
-                    }
+        const lint = lintFor(tier);
+        for (const [tag, entry] of Object.entries(lint.tags)) {
+            let element = tags.get(tag);
+            if (!element) {
+                element = {
+                    attributes: new Map(),
+                    family: entry.family,
+                    hooks: new Map(),
+                    parts: new Map(),
+                    written: new Set(),
+                };
+                tags.set(tag, element);
+            }
+            for (const name of entry.written) {
+                element.written.add(name);
+            }
+            for (const [name, values] of Object.entries(entry.attributes)) {
+                element.attributes.set(name, values ? new Set(values) : null);
+            }
+            for (const [names, into] of [
+                [entry.parts, element.parts],
+                [entry.hooks, element.hooks],
+            ]) {
+                for (const name of names) {
+                    const publishers = into.get(name) ?? new Set();
+                    publishers.add(lint.package);
+                    into.set(name, publishers);
                 }
             }
         }
     }
     return tags;
 };
+const allowed = (type) => {
+    if (!type) {
+        return null;
+    }
+    const literals = [...type.matchAll(/'([^']*)'/g)].map((match) => match[1]);
+    const rest = type
+        .replace(/'[^']*'/g, '')
+        .replace(/\b(undefined|null)\b/g, '')
+        .replace(/[|\s]/g, '');
+    return literals.length > 0 && rest === '' ? new Set(literals) : null;
+};
 export const versionsOf = (tiers) => {
     const versions = {};
     for (const tier of tiers) {
-        const version = tier.manifest.helix?.version;
-        if (version) {
-            versions[tier.manifest.helix?.package ?? tier.name] = version;
+        const lint = lintFor(tier);
+        if (lint.version) {
+            versions[lint.package] = lint.version;
         }
     }
     return versions;
 };
-export const nearest = (wrong, candidates) => {
+export const nearest = (wrong, candidates, ceiling = Math.floor(wrong.length / 3)) => {
     let best;
-    let distance = Math.floor(wrong.length / 3);
+    let distance = Math.min(ceiling, Math.floor(wrong.length / 3));
     for (const candidate of candidates) {
         const found = within(wrong, candidate, distance);
         if (found !== undefined && found < distance + 1) {
@@ -57,8 +116,14 @@ const within = (from, to, ceiling) => {
     let previous = Array.from({ length: to.length + 1 }, (_, column) => column);
     for (let row = 1; row <= from.length; row += 1) {
         const current = [row];
+        let least = row;
         for (let column = 1; column <= to.length; column += 1) {
-            current[column] = Math.min((previous[column] ?? 0) + 1, (current[column - 1] ?? 0) + 1, (previous[column - 1] ?? 0) + (from[row - 1] === to[column - 1] ? 0 : 1));
+            const cell = Math.min((previous[column] ?? 0) + 1, (current[column - 1] ?? 0) + 1, (previous[column - 1] ?? 0) + (from[row - 1] === to[column - 1] ? 0 : 1));
+            current[column] = cell;
+            least = Math.min(least, cell);
+        }
+        if (least > ceiling) {
+            return undefined;
         }
         previous = current;
     }

package/dist/overlay.d.ts

@@ -0,0 +1,12 @@
+import type { Report } from './report.js';
+/** What a running instance does with the overlay. */
+export interface Overlay {
+    /** The element, so a change it makes to the page is known for its own. */
+    readonly element: HTMLElement;
+    /** Removes it from the page. */
+    remove(): void;
+    /** Shows a run: the counts on the badge and the findings in the panel. */
+    show(run: Report): void;
+}
+/** Puts the overlay on `page`. */
+export declare const overlayOn: (page: Document) => Overlay;