@fusion.dev/helix-diagnostics 0.137.0 → 0.139.0

package/dist/config.js

@@ -14,6 +14,19 @@ export const DEFAULTS = {
         runtime: true,
         usage: true,
     },
+    sinks: { overlay: true, relay: false },
+};
+export const LOCAL = /^(localhost|127\.0\.0\.1|\[::1\]|.+\.localhost|.+\.test)$/;
+const local = (address) => {
+    if (!/^https?:\/\/[^/?#@]+$/.test(address)) {
+        return false;
+    }
+    try {
+        return LOCAL.test(new URL(address).hostname);
+    }
+    catch {
+        return false;
+    }
 };
 const ALLOWED = {
     console: {
@@ -29,6 +42,7 @@ const ALLOWED = {
     environments: { ci: [true, false], development: [true, false], production: 'sample' },
     project: { key: 'string', name: 'string', tags: 'tags' },
     send: Object.fromEntries(CATEGORIES.map((category) => [category, [true, false]])),
+    sinks: { overlay: [true, false], relay: 'address' },
 };
 const shown = (value) => typeof value === 'string' ? `\`${value}\`` : String(value);
 export const checkConfig = (config, layer) => {
@@ -60,22 +74,26 @@ export const checkConfig = (config, layer) => {
                 ? typeof one === 'string'
                 : takes === 'tags'
                     ? Array.isArray(one) && one.every((tag) => typeof tag === 'string')
-                    : takes === 'sample'
-                        ? one === false ||
-                            (typeof one === 'object' &&
-                                one !== null &&
-                                typeof one.sample === 'number' &&
-                                one.sample >= 0 &&
-                                one.sample <= 1)
-                        : takes.includes(one);
+                    : takes === 'address'
+                        ? typeof one === 'boolean' || (typeof one === 'string' && local(one))
+                        : takes === 'sample'
+                            ? one === false ||
+                                (typeof one === 'object' &&
+                                    one !== null &&
+                                    typeof one.sample === 'number' &&
+                                    one.sample >= 0 &&
+                                    one.sample <= 1)
+                            : takes.includes(one);
             if (!fits) {
                 const expected = takes === 'string'
                     ? 'a string'
                     : takes === 'tags'
                         ? 'a list of strings'
-                        : takes === 'sample'
-                            ? '`false`, or `{ sample }` from 0 to 1'
-                            : takes.map(shown).join(', ');
+                        : takes === 'address'
+                            ? '`true`, `false`, or an address on a local host, such as `http://127.0.0.1:7417`'
+                            : takes === 'sample'
+                                ? '`false`, or `{ sample }` from 0 to 1'
+                                : takes.map(shown).join(', ');
                 throw new Error(`The ${layer} sets \`${section}.${name}\` to \`${JSON.stringify(one)}\`. It takes ${expected}.`);
             }
         }
@@ -107,6 +125,7 @@ export const resolveConfig = (file, call) => {
             console: merged('console', { ...DEFAULTS.console }),
             detail: merged('detail', { ...DEFAULTS.detail }),
             environments: merged('environments', { ...DEFAULTS.environments }),
+            sinks: merged('sinks', { ...DEFAULTS.sinks }),
         },
         project: {
             ...(project.name === undefined ? {} : { name: project.name }),

package/dist/console.d.ts

@@ -35,4 +35,12 @@ export type ConsoleSink = Pick<Console, 'debug' | 'error' | 'group' | 'groupColl
  * every finding whatever is printed under it, and the ones the rules turned
  * off, so a quiet console never reads as a clean page.
  */
-export declare const report: (result: Report, to?: ConsoleSink) => Report;
+export declare const report: (result: Report, to?: ConsoleSink, { shown, }?: {
+    /**
+     * The fingerprints already printed for this page. Given, a finding prints
+     * only the first time its fingerprint is seen, and is added; the heading
+     * still counts every finding. `initDiagnostics()` keeps one per page, so
+     * a run after every change does not repeat itself.
+     */
+    shown?: Set<string> | undefined;
+}) => Report;

package/dist/console.js

@@ -8,7 +8,7 @@ const entry = (finding) => {
 };
 const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
 const RANK = { error: 3, info: 1, warn: 2 };
-export const report = (result, to = console) => {
+export const report = (result, to = console, { shown, } = {}) => {
     const { configuration, coverage, findings } = result;
     const levels = configuration.console;
     const bySeverity = (severity) => findings.filter((finding) => finding.severity === severity).length;
@@ -48,10 +48,20 @@ export const report = (result, to = console) => {
     }
     if (levels.findings !== 'off') {
         const floor = RANK[levels.findings];
+        let before = 0;
         for (const finding of findings) {
-            if (RANK[finding.severity] >= floor) {
-                to[finding.severity](entry(finding));
+            if (RANK[finding.severity] < floor) {
+                continue;
             }
+            if (shown?.has(finding.fingerprint)) {
+                before += 1;
+                continue;
+            }
+            shown?.add(finding.fingerprint);
+            to[finding.severity](entry(finding));
+        }
+        if (before > 0) {
+            to.info(`${counted(before, 'finding')} printed before, on this page, and not again`);
         }
     }
     if (levels.usage !== 'off') {

package/dist/diagnose.d.ts

@@ -0,0 +1,75 @@
+import { type Config } from './config.js';
+import type { Tier } from './manifest.js';
+import type { Environment, Report } from './report.js';
+import { type Watcher } from './usage.js';
+/**
+ * What to look at, what to compare it against, and the settings for this
+ * call, which win over the project's file field by field.
+ */
+export interface Options extends Config {
+    /**
+     * `duplicateRegistrations` from `@fusion.dev/helix-core`, when it is installed.
+     *
+     * **Passed in rather than imported**, so this package does not depend on the
+     * library it diagnoses. A diagnostics release would otherwise have to follow
+     * every core release, and a consumer on an older core could not run a newer
+     * collector at all. Omitted, the duplicate check falls back to comparing a
+     * live element against its own registered class, which finds the same fault
+     * from outside and cannot name the losing class.
+     */
+    duplicates?: (() => string[]) | undefined;
+    /**
+     * Where this run happens, as the project declares it. **Never inferred**:
+     * a bundler's `development` condition misfires both ways, and a run whose
+     * environment nobody declared is never sent.
+     */
+    environment?: Environment | undefined;
+    /**
+     * The project's own file, `helix-diagnostics.json`, parsed. The build reads
+     * the file, since the page cannot: import the JSON and pass it here.
+     */
+    file?: Config | undefined;
+    /**
+     * The document to scan. Defaults to the ambient one.
+     *
+     * Present so a test can hand over a constructed document, and so a page with
+     * an iframe it owns can scan that too.
+     */
+    from?: Document | undefined;
+    /**
+     * The page's path, for a router that knows its own pattern, such as
+     * `/products/[id]`. Otherwise read from the location and made a pattern, as
+     * `detail.pages` says.
+     */
+    page?: string | undefined;
+    /**
+     * The manifests to check against, one per installed tier.
+     *
+     * **Pass both tiers when both are installed.** A part `@fusion.dev/helix-headless`
+     * publishes and `@fusion.dev/helix` never forwarded is a real fault and is
+     * invisible to either manifest alone.
+     */
+    tiers: Tier[];
+    /**
+     * A watcher from `watch()`, so usage counts every element that rendered
+     * since it began. Without one, usage counts the elements in the page now.
+     */
+    watcher?: Watcher | undefined;
+}
+/**
+ * One run over the page.
+ *
+ * **It returns coverage and findings together and offers no way to have one
+ * without the other.** A collector that cannot read cross-origin sheets reports
+ * the same empty array whether it read everything or nothing. An empty
+ * `findings` is only meaningful beside the `coverage` that says what was looked
+ * at.
+ *
+ * Cheap enough to call on a route change. There is no observer and no polling
+ * loop: sheets that arrive later are found by calling it again.
+ *
+ * **A manifest from another version is refused**, with one finding that says
+ * so in place of every other: by version where both sides carry one, and
+ * otherwise by a part the manifest does not list rendering in the page.
+ */
+export declare const diagnose: (options: Options) => Report;

package/dist/diagnose.js

@@ -0,0 +1,76 @@
+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, lintFor, versionsOf } from './manifest.js';
+import { pageOf } from './page.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 walked = pageOf(document_);
+    const { answered, coverage, readers, rules: located, used } = collect(document_, walked);
+    const lints = tiers.map((tier) => ({ lint: lintFor(tier) }));
+    const tags = index(lints);
+    const counted = watcher ? watcher.counts() : walk(document_, walked);
+    const seen = loadedVersions();
+    const manifests = versionsOf(lints);
+    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_, walked)).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_, walked),
+            ...registrations(document_, duplicates, walked),
+        ].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/identity.js

@@ -2,16 +2,20 @@ const CATEGORY = {
     'dead-hook': 'styling',
     'dead-part': 'styling',
     'duplicate-registration': 'integrity',
+    'invalid-value': 'markup',
     'manifest-skew': 'integrity',
     'unforwarded-part': 'styling',
+    'unknown-attribute': 'markup',
     'unknown-tag': 'integrity',
 };
 const OWNER = {
     'dead-hook': 'consumer',
     'dead-part': 'consumer',
     'duplicate-registration': 'consumer',
+    'invalid-value': 'consumer',
     'manifest-skew': 'consumer',
     'unforwarded-part': 'helix',
+    'unknown-attribute': 'consumer',
     'unknown-tag': 'consumer',
 };
 export const normalize = (subject) => subject

package/dist/index.d.ts

@@ -30,86 +30,14 @@
 export { collect } from './collect.js';
 export { type Config, DEFAULTS, pagePattern } from './config.js';
 export { report } from './console.js';
+export { diagnose, type Options } from './diagnose.js';
 export { fingerprintOf, normalize } from './identity.js';
-export type { ManifestSource, Published, Tier } from './manifest.js';
-export { index, nearest } from './manifest.js';
+export { type Diagnostics, INSTANCE, type InitOptions, initDiagnostics } from './init.js';
+export type { LintData, LintTag, ManifestSource, Published, Tier } from './manifest.js';
+export { index, lintOf, nearest } from './manifest.js';
 export type { Category, Configuration, Coverage, Environment, Finding, FindingCategory, Kind, Layer, Origin, Owner, Report, Severity, Unreadable, Usage, } from './report.js';
 export { CATEGORIES, KINDS } from './report.js';
 export { type Override, type Rules, SHIPPED_RULES } from './rules.js';
+export { TIMING, type Timing } from './schedule.js';
 export { type Watcher, watch } from './usage.js';
 export { VERSION } from './version.js';
-import { type Config } from './config.js';
-import type { Tier } from './manifest.js';
-import type { Environment, Report } from './report.js';
-import { type Watcher } from './usage.js';
-/**
- * What to look at, what to compare it against, and the settings for this
- * call, which win over the project's file field by field.
- */
-export interface Options extends Config {
-    /**
-     * `duplicateRegistrations` from `@fusion.dev/helix-core`, when it is installed.
-     *
-     * **Passed in rather than imported**, so this package does not depend on the
-     * library it diagnoses. A diagnostics release would otherwise have to follow
-     * every core release, and a consumer on an older core could not run a newer
-     * collector at all. Omitted, the duplicate check falls back to comparing a
-     * live element against its own registered class, which finds the same fault
-     * from outside and cannot name the losing class.
-     */
-    duplicates?: () => string[];
-    /**
-     * Where this run happens, as the project declares it. **Never inferred**:
-     * a bundler's `development` condition misfires both ways, and a run whose
-     * environment nobody declared is never sent.
-     */
-    environment?: Environment | undefined;
-    /**
-     * The project's own file, `helix-diagnostics.json`, parsed. The build reads
-     * the file, since the page cannot: import the JSON and pass it here.
-     */
-    file?: Config | undefined;
-    /**
-     * The document to scan. Defaults to the ambient one.
-     *
-     * Present so a test can hand over a constructed document, and so a page with
-     * an iframe it owns can scan that too.
-     */
-    from?: Document;
-    /**
-     * The page's path, for a router that knows its own pattern, such as
-     * `/products/[id]`. Otherwise read from the location and made a pattern, as
-     * `detail.pages` says.
-     */
-    page?: string | undefined;
-    /**
-     * The manifests to check against, one per installed tier.
-     *
-     * **Pass both tiers when both are installed.** A part `@fusion.dev/helix-headless`
-     * publishes and `@fusion.dev/helix` never forwarded is a real fault and is
-     * invisible to either manifest alone.
-     */
-    tiers: Tier[];
-    /**
-     * A watcher from `watch()`, so usage counts every element that rendered
-     * since it began. Without one, usage counts the elements in the page now.
-     */
-    watcher?: Watcher | undefined;
-}
-/**
- * One run over the page.
- *
- * **It returns coverage and findings together and offers no way to have one
- * without the other.** A collector that cannot read cross-origin sheets reports
- * the same empty array whether it read everything or nothing. An empty
- * `findings` is only meaningful beside the `coverage` that says what was looked
- * at.
- *
- * Cheap enough to call on a route change. There is no observer and no polling
- * loop: sheets that arrive later are found by calling it again.
- *
- * **A manifest from another version is refused**, with one finding that says
- * so in place of every other: by version where both sides carry one, and
- * otherwise by a part the manifest does not list rendering in the page.
- */
-export declare const diagnose: (options: Options) => Report;

package/dist/index.js

@@ -1,81 +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, 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, rules: located } = 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),
-            ...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;