@fusion.dev/helix-diagnostics 0.138.0 → 0.140.0

package/dist/index.js

@@ -1,82 +1,12 @@
 export { collect } from './collect.js';
 export { DEFAULTS, pagePattern } from './config.js';
 export { report } from './console.js';
+export { diagnose } from './diagnose.js';
 export { fingerprintOf, normalize } from './identity.js';
-export { index, nearest } from './manifest.js';
+export { INSTANCE, initDiagnostics } from './init.js';
+export { index, lintOf, nearest } from './manifest.js';
 export { CATEGORIES, KINDS } from './report.js';
 export { SHIPPED_RULES } from './rules.js';
+export { TIMING } from './schedule.js';
 export { watch } from './usage.js';
 export { VERSION } from './version.js';
-import { analyze, markup, registrations, skew, versionSkew } from './analyze.js';
-import { collect } from './collect.js';
-import { pagePattern, resolveConfig } from './config.js';
-import { identify } from './identity.js';
-import { index, versionsOf } from './manifest.js';
-import { applyRules, overridesOf } from './rules.js';
-import { listed, loadedVersions, styled, walk } from './usage.js';
-import { VERSION } from './version.js';
-const runId = () => globalThis.crypto?.randomUUID?.() ??
-    `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
-export const diagnose = (options) => {
-    const started = performance.now();
-    const at = new Date().toISOString();
-    const { duplicates, environment, file, from, page, tiers, watcher, ...call } = options;
-    if (tiers.length === 0) {
-        throw new Error('diagnose() needs at least one manifest. Without one every part name is unknown and every finding would be noise.');
-    }
-    const resolved = resolveConfig(file, call);
-    const { detail } = resolved.configuration;
-    const document_ = from ?? globalThis.document;
-    const { answered, coverage, readers, rules: located, used } = collect(document_);
-    const tags = index(tiers);
-    const counted = watcher ? watcher.counts() : walk(document_);
-    const seen = loadedVersions();
-    const manifests = versionsOf(tiers);
-    const byVersion = versionSkew(manifests, seen);
-    const known = seen.length > 0 && Object.keys(manifests).length > 0;
-    const skewed = applyRules((byVersion.length > 0 ? byVersion : known ? [] : skew(tags, document_)).map((one) => identify(one, tags)), file?.rules, call.rules);
-    const judged = skewed.findings.length > 0
-        ? { findings: [], silenced: [] }
-        : applyRules([
-            ...analyze(located, tags, document_, answered, used, readers),
-            ...markup(tags, document_),
-            ...registrations(document_, duplicates),
-        ].map((one) => identify(one, tags)), file?.rules, call.rules);
-    const path = page ?? globalThis.location?.pathname;
-    const shownPage = path === undefined || detail.pages === 'none'
-        ? undefined
-        : detail.pages === 'patterns'
-            ? pagePattern(path)
-            : path;
-    return {
-        configuration: {
-            ...resolved.configuration,
-            overrides: overridesOf(file?.rules, call.rules),
-            silenced: [...skewed.silenced, ...judged.silenced],
-        },
-        coverage,
-        findings: [...skewed.findings, ...judged.findings],
-        project: resolved.project,
-        run: {
-            at,
-            duration: Math.round(performance.now() - started),
-            id: runId(),
-            source: 'page',
-            ...(environment === undefined ? {} : { environment }),
-            ...(shownPage === undefined ? {} : { page: shownPage }),
-        },
-        schema: 1,
-        usage: {
-            ...listed(counted, tags),
-            ...styled(located, tags, answered, detail.hookValues),
-            counted: watcher ? 'watched' : 'walked',
-        },
-        versions: { collector: VERSION, helix: seen, manifests, rules: VERSION },
-        withheld: Object.entries(resolved.send)
-            .filter(([, sent]) => !sent.on)
-            .map(([category, sent]) => ({
-            category: category,
-            decidedBy: sent.decidedBy,
-        })),
-    };
-};

package/dist/init.d.ts

@@ -0,0 +1,87 @@
+/**
+ * One call, in any framework: `initDiagnostics()`.
+ *
+ * ```ts
+ * import { initDiagnostics } from '@fusion.dev/helix-diagnostics'
+ *
+ * initDiagnostics({ environment: import.meta.env.MODE })
+ * ```
+ *
+ * **Once, at the app's entry, before the app mounts**, in whatever builds it:
+ * `main.ts` in Vite, Vue, Svelte, or Solid, before `bootstrapApplication` in
+ * Angular, `instrumentation-client.ts` in Next.js, or a module script with no
+ * bundler. It needs nothing from a framework: it reads the DOM, hears
+ * elements render through core's listener, and hears navigation from the
+ * browser.
+ *
+ * **It never breaks the app.** It never throws; a setting that names nothing
+ * is printed with the closest setting, and the handle it returns does
+ * nothing. A run that throws is printed, and three in a row stop it. Each
+ * place a run goes is isolated from the others.
+ *
+ * **It never runs in production by accident.** With no environment declared
+ * it runs only on a local host, since each framework says development its
+ * own way. Production runs only with `environment: 'production'` and a sample
+ * rate.
+ */
+import { type Config } from './config.js';
+import type { Tier } from './manifest.js';
+import type { Environment, Report } from './report.js';
+/** What `initDiagnostics()` takes: the settings, and where the run comes from. */
+export interface InitOptions extends Config {
+    /**
+     * Where lint data is loaded from, where `tiers` is not given: a base the
+     * package and version follow, as
+     * `https://cdn.jsdelivr.net/npm/@fusion.dev/helix@0.138.0/lint.json`.
+     * `false` loads nothing. jsDelivr by default.
+     */
+    cdn?: string | false | undefined;
+    /** `duplicateRegistrations` from `@fusion.dev/helix-core`, as `diagnose` takes it. */
+    duplicates?: (() => string[]) | undefined;
+    /**
+     * Where the page runs, as the project declares it. Undeclared, it runs only
+     * on a local host: `localhost`, `127.0.0.1`, `[::1]`, `*.localhost`, and
+     * `*.test`.
+     */
+    environment?: Environment | undefined;
+    /** The project's own file, `helix-diagnostics.json`, parsed. */
+    file?: Config | undefined;
+    /** Called with each run, after the console has it. */
+    onReport?: ((run: Report) => void) | undefined;
+    /**
+     * The page's path as the app's router names it, such as `/products/[id]`,
+     * asked at each run. The location, made a pattern, otherwise.
+     */
+    page?: (() => string | undefined) | undefined;
+    /**
+     * The lint data or manifests to check against. Loaded from `cdn`, for the
+     * Helix version core lists on the page, where not given.
+     */
+    tiers?: Tier[] | undefined;
+}
+/** What `initDiagnostics()` returns. */
+export interface Diagnostics {
+    /** Whether it is running: false where it declined to start, and after `stop()`. */
+    readonly active: boolean;
+    /** The last run, once there is one. */
+    readonly latest: Report | undefined;
+    /** Runs now, outside the schedule, and returns the run, where it can run yet. */
+    run(): Report | undefined;
+    /** Calls `listener` with every run from now on, and returns its removal. */
+    subscribe(listener: (run: Report) => void): () => void;
+    /** Stops it: nothing more runs. A later `initDiagnostics()` starts afresh. */
+    stop(): void;
+}
+/**
+ * The key the running instance is kept under: a second call returns it, as
+ * React's strict mode, hot module replacement, and a component mounting twice
+ * each make, and an end-to-end test reads it to assert a page has no findings.
+ */
+export declare const INSTANCE: unique symbol;
+/**
+ * Starts diagnostics on this page, or returns the handle it already has.
+ *
+ * Never throws. On a server, with no `document`, it returns a handle that
+ * does nothing, so it is safe in code server-side rendering also runs.
+ */
+export declare const initDiagnostics: (options?: InitOptions) => Diagnostics;

package/dist/init.js

@@ -0,0 +1,337 @@
+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 { shownRuntime } from './runtime.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 resolved;
+    try {
+        resolved = resolveConfig(file, call);
+    }
+    catch (error) {
+        once(`settings ${messageOf(error)}`, () => console.error(`helix diagnostics: not started. ${messageOf(error)}`));
+        return inert();
+    }
+    const { configuration } = resolved;
+    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,
+        measure: resolved.send.performance.on || configuration.console.performance !== 'off',
+        onReport,
+        page,
+        route,
+        sinks: configuration.sinks,
+        tiers,
+        warnings: configuration.core.warnings,
+    });
+};
+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 warnings = given.warnings;
+    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 || shownRuntime(run.runtime).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;
+                        warnings = resolveConfig(file, call).configuration.core.warnings;
+                    }
+                    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(),
+        onRuntime: () => plan.poke(),
+        performance: given.measure,
+        quiet: () => !warnings,
+    });
+    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

@@ -51,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.
  *