@fusion.dev/helix-diagnostics 0.138.0 → 0.139.0

package/README.md

@@ -8,38 +8,140 @@ part a composed component never forwarded, two copies of the library on one page
 npm install --save-dev @fusion.dev/helix-diagnostics
 ```
 
+## Start it in your app
+
+Call `initDiagnostics()` once, at your app's entry, before the app mounts:
+
 ```js
-import { diagnose, report, watch } from '@fusion.dev/helix-diagnostics'
-import { duplicateRegistrations } from '@fusion.dev/helix-core'
-import styled from '@fusion.dev/helix/custom-elements.json' with { type: 'json' }
-import headless from '@fusion.dev/helix-headless/custom-elements.json' with { type: 'json' }
-
-// Before the components load, so every element that renders is counted.
-const watcher = watch()
-
-// Later, once the page has rendered, and again after a route change.
-report(
-  diagnose({
-    duplicates: duplicateRegistrations,
-    tiers: [
-      { manifest: styled, name: '@fusion.dev/helix' },
-      { manifest: headless, name: '@fusion.dev/helix-headless' },
-    ],
-    watcher,
-  }),
-)
+import { initDiagnostics } from '@fusion.dev/helix-diagnostics'
+
+initDiagnostics({ environment: import.meta.env.MODE })
+```
+
+It needs nothing from a framework, so the call is the same wherever Helix runs:
+
+- `main.ts` in Vite, Vue, Svelte, or Solid;
+- before `bootstrapApplication` in Angular, inside `ngZone.runOutsideAngular`
+  so its callbacks do not run change detection;
+- `instrumentation-client.ts` in Next.js;
+- a `<script type="module">` on a page with no bundler.
+
+On a server, with no `document`, it does nothing, so it is safe in code that
+server-side rendering also runs. A second call returns the first call's handle,
+so React's strict mode and hot module replacement start nothing twice.
+
+**What it does from there:**
+
+- **Counts from the start**, every Helix element that renders, including ones
+  that go, such as a closed dialog.
+- **Loads the lint data for the exact Helix version on the page**, from a public
+  npm CDN, about 18 KB compressed for each tier. Offline, or on a locked-down
+  network, pass it yourself:
+  `tiers: [{ lint }]` with `import lint from '@fusion.dev/helix/lint.json'`.
+- **Runs itself**: after the page loads, after a navigation, and after the page
+  changes, once changes stop for a second, in an idle moment, and never sooner
+  than two seconds after the last run, nor sooner than twenty times its
+  duration. A page that never stops changing still runs within ten seconds.
+  Nothing runs in a hidden tab, or when nothing changed.
+- **Prints each finding once per page**, in DevTools, at the levels your
+  `console` setting gives. The heading still counts every finding.
+- **Shows the findings on the page**, in development. A badge in the corner
+  counts them and opens a list of each finding with its evidence. Hover over a
+  finding, or focus it, to outline the element it is about. The badge shows
+  only while the page has findings.
+- **Hands each run to your app**: the `onReport` option, `subscribe()` on the
+  handle it returns, and a `helix-diagnostics` event on `document`.
+
+**It never runs in production by accident.** With no `environment`, it runs only
+on a local host: `localhost`, `127.0.0.1`, `[::1]`, `*.localhost`, and `*.test`.
+Production runs only with `environment: 'production'` and
+`environments: { production: { sample } }`, and there each run goes to your app
+alone. A visitor sees nothing in the console or on the page.
+
+**It never breaks your app.** It never throws. A setting that names nothing is
+printed with the closest real one, and the handle does nothing. A run that
+throws is printed, and three failures in a row stop it. A subscriber that
+throws stops neither the others nor the console.
+
+| Option | What it is |
+| --- | --- |
+| `environment` | `development`, `ci`, or `production`, as your build says it |
+| `tiers` | Lint data or manifests to check against, where you pass them yourself |
+| `cdn` | Where lint data loads from; `false` loads nothing |
+| `page` | A function returning the page's path as your router names it, such as `/products/[id]` |
+| `onReport` | Called with each run |
+| `duplicates` | `duplicateRegistrations` from `@fusion.dev/helix-core` |
+| `file` | Your project's `helix-diagnostics.json`, imported |
+| Any setting below | `rules`, `console`, `sinks`, `send`, `detail`, `environments`, `project` |
+
+The handle has `active`, `latest`, `run()`, `subscribe()`, and `stop()`. An
+end-to-end test reaches it at `globalThis[Symbol.for('fusion.dev/helix/diagnostics')]`
+to assert that a page has no findings.
+
+The badge is one element, `helix-diagnostics-overlay`, with its own shadow root
+and its own styles. Diagnostics leaves it out of everything it counts and reads.
+It is never on a page in CI, so your screenshots never hold it. Turn it off in
+development with `sinks: { overlay: false }`.
+
+## Print the findings in your terminal
+
+A page cannot write to your terminal, so the Helix CLI has a command that
+receives each run beside your dev server. Install the CLI, then start the
+command in the project's directory:
+
+```sh
+npm install --save-dev @fusion.dev/helix-cli
+npx helix diagnostics
+```
+
+Then turn the relay on where you call `initDiagnostics()`:
+
+```js
+initDiagnostics({ environment: import.meta.env.MODE, sinks: { relay: true } })
+```
+
+Each run that differs from the last one for its page is posted to
+`http://127.0.0.1:7417`, and the command prints each finding the first time a
+page has it. For a relay on another port, such as one started with
+`--port 7500`, pass its address: `sinks: { relay: 'http://127.0.0.1:7500' }`.
+The address is always on a local host.
+
+- **It is off by default.** A browser prints a refused connection in DevTools
+  on every page load where nothing listens. With the relay on and the command
+  not running, one warning is printed in the console, and nothing is sent.
+- **It serves your settings.** Where you pass no `file`, the page loads
+  `helix-diagnostics.json` from the directory the command runs in, so you do
+  not need to import it. Pass `--config <path>` for a file elsewhere. A file
+  that does not parse is not served.
+- **It writes the CI file.** With `--out reports/helix-diagnostics.json`, it
+  keeps the latest run of every page there, in the shape `ciSink` writes.
+- **It takes runs from pages on a local host only**: `localhost`, `127.0.0.1`,
+  `[::1]`, `*.localhost`, and `*.test`. It listens on `127.0.0.1`, so nothing
+  else on your network reaches it, and production pages never send to it.
+
+## Run it once, directly
+
+`diagnose()` is one run, which `initDiagnostics()` makes for you. Call it
+yourself in a test, a script, or anywhere you want a single report:
+
+```js
+import { diagnose, report } from '@fusion.dev/helix-diagnostics'
+import styled from '@fusion.dev/helix/lint.json' with { type: 'json' }
+import headless from '@fusion.dev/helix-headless/lint.json' with { type: 'json' }
+
+report(diagnose({ tiers: [{ lint: styled }, { lint: headless }] }))
 ```
 
-`diagnose` needs at least one manifest and says so instead of defaulting: with
-none, every part name is unknown and every finding would be noise. Pass both
-tiers when both are installed, since a part the headless tier publishes and the
-styled tier never forwarded is only visible with both. `report` is the console
-sink; the `Report` it returns is the same object, so you can send it somewhere
-else as well.
+`diagnose` needs at least one tier and says so instead of defaulting: with none,
+every part name is unknown and every finding would be noise. It takes lint data
+or a full `custom-elements.json`. Pass both tiers when both are installed, since
+a part the headless tier publishes and the styled tier never forwarded is only
+visible with both. `report` is the console sink; the `Report` it returns is the
+same object, so you can send it somewhere else as well.
 
-None of these produces an error anywhere. They are detectable only against the
-custom elements manifest, which every Helix package already publishes, so the
-diagnostic cannot drift from what is true.
+None of these faults produces an error anywhere. They are detectable only against
+the manifest, which every Helix package publishes, so the diagnostic cannot
+drift from what is true.
 
 ## What a report holds
 
@@ -148,6 +250,8 @@ diagnose({
 | `console.findings` | `error`, `warn`, `info`, or `off`: the lowest severity printed | `info` |
 | `console.coverage` | `info` or `off` | `info` |
 | `console.usage` | `debug` or `off` | `debug` |
+| `sinks.overlay` | `true` or `false`, for the badge in development | `true` |
+| `sinks.relay` | `true`, `false`, or an address on a local host, such as `http://127.0.0.1:7417` | `false` |
 | `send.<category>` | `true` or `false`, for `findings`, `usage`, `coverage`, `configuration`, `runtime`, `performance`, and `assist` | all on but `performance` |
 | `detail.evidence` | `full`, `selector`, or `none` | `full` |
 | `detail.hookValues` | `true` or `false` | `true` |
@@ -155,13 +259,14 @@ diagnose({
 | `environments.<name>` | `true` or `false`; `production` takes `{ sample }` from 0 to 1 | development and CI on |
 | `project` | `key`, `name`, and `tags` | none |
 
-`send`, `detail`, and `environments` decide what a sending sink sends, and
-nothing here sends yet: they are recorded in every report, so a dashboard
-knows what a project withheld. A setting or a value that does not exist
-throws, and names the closest that does.
+`send`, `detail`, and `environments` decide what the diagnostics service is
+sent, and the service is not built yet. They are recorded in every report, so a
+dashboard knows what a project withheld. The relay runs on your own machine and
+receives each run whole. A setting or a value that does not exist throws, and
+names the closest that does.
 
-Development only. It walks every stylesheet in the page, and it sends nothing
-anywhere.
+**What the page requests**: the lint data, from `cdn`, once per page load, and
+the relay, where `sinks.relay` is on. Nothing else leaves the page.
 
 ## In CI
 

package/dist/analyze.d.ts

@@ -18,6 +18,7 @@
  */
 import type { Answered, Located, Readers } from './collect.js';
 import { type Published } from './manifest.js';
+import { type Page } from './page.js';
 import type { Raw } from './report.js';
 /** Every `helix-*` tag a selector mentions, in source order. */
 export declare const targets: (selector: string) => string[];
@@ -26,6 +27,16 @@ export declare const parts: (selector: string) => Array<{
     names: string[];
     tag: string;
 }>;
+/**
+ * A selector made matchable now: pseudo-elements and the pseudo-classes of a
+ * moment (hover, focus) taken off, since a hook set on `.card:hover` reaches
+ * what `.card` matches. `null` where it cannot be judged from the page, as
+ * for `:host`, which only a component's own root matches.
+ *
+ * The longer pseudo-classes come first, so `:focus-visible` is taken whole
+ * and never read as `:focus` followed by `-visible`.
+ */
+export declare const matchable: (selector: string) => string | null;
 /**
  * The findings in one page's rules.
  *
@@ -51,7 +62,7 @@ export declare const analyze: (rules: Located[], tags: Map<string, Published>, f
  * version old enough to predate the warning. That case reports what it can see,
  * which is that a live element is not an instance of its own registered class.
  */
-export declare const registrations: (from?: Document, known?: () => string[]) => Raw[];
+export declare const registrations: (from?: Document, known?: () => string[], page?: Page) => Raw[];
 /**
  * Evidence that the manifest is from another version of Helix than the page
  * runs: an element rendering a part its manifest entry does not list.
@@ -67,7 +78,7 @@ export declare const registrations: (from?: Document, known?: () => string[]) =>
  * between versions reads as dead in every rule that styles it, and a hundred
  * findings that are each the same mistake are worse than one that names it.
  */
-export declare const skew: (tags: Map<string, Published>, from: Document) => Raw[];
+export declare const skew: (tags: Map<string, Published>, from: Document, page?: Page) => Raw[];
 /**
  * A manifest from another version, read from the numbers where both sides
  * have one: the version a manifest describes, against the versions of core
@@ -84,4 +95,4 @@ export declare const versionSkew: (manifests: Record<string, string>, seen: stri
  * Helix's own markup. One finding per tag, attribute, and value, however many
  * elements carry it.
  */
-export declare const markup: (tags: Map<string, Published>, from: Document) => Raw[];
+export declare const markup: (tags: Map<string, Published>, from: Document, page?: Page) => Raw[];

package/dist/analyze.js

@@ -1,4 +1,5 @@
 import { nearest } from './manifest.js';
+import { pageOf } from './page.js';
 export const targets = (selector) => {
     const found = new Set();
     for (const match of selector.matchAll(/(?<![\w.#-])helix-[a-z0-9]+(?:-[a-z0-9]+)*/g)) {
@@ -16,7 +17,7 @@ export const parts = (selector) => {
     }
     return found;
 };
-const matchable = (selector) => {
+export const matchable = (selector) => {
     if (selector.includes(':host')) {
         return null;
     }
@@ -61,7 +62,7 @@ const reachesAnswer = (host, property, answering, readers, depth = 0) => {
     }
     return false;
 };
-const loose = (located, answerers, from, used, onPage, listedBy, readers) => {
+const loose = (located, answerers, from, used, onPage, listedBy, readers, suggested) => {
     const findings = [];
     if (located.scope instanceof ShadowRoot && located.scope.host.localName.startsWith('helix-')) {
         return findings;
@@ -78,7 +79,11 @@ const loose = (located, answerers, from, used, onPage, listedBy, readers) => {
             if (used.has(property)) {
                 continue;
             }
-            const suggestion = nearest(property, answerers.keys(), HOOK_DISTANCE);
+            let suggestion = suggested.get(property);
+            if (!suggested.has(property)) {
+                suggestion = nearest(property, answerers.keys(), HOOK_DISTANCE);
+                suggested.set(property, suggestion);
+            }
             if (!suggestion) {
                 continue;
             }
@@ -152,6 +157,7 @@ export const analyze = (rules, tags, from, answered = new Map(), used = new Set(
             }
         }
     }
+    const suggested = new Map();
     const present = new Map();
     const onPage = (property, answering) => {
         let found = present.get(property);
@@ -213,7 +219,7 @@ export const analyze = (rules, tags, from, answered = new Map(), used = new Set(
         const mentioned = targets(selector).map((tag) => [tag, tags.get(tag)]);
         const known = mentioned.filter(([, element]) => element);
         if (known.length === 0) {
-            findings.push(...loose(located, answeredBy, from, used, onPage, listedBy, readers));
+            findings.push(...loose(located, answeredBy, from, used, onPage, listedBy, readers, suggested));
             continue;
         }
         for (const property of Array.from(located.rule.style ?? [])) {
@@ -267,7 +273,7 @@ export const analyze = (rules, tags, from, answered = new Map(), used = new Set(
     }
     return findings;
 };
-export const registrations = (from = document, known = () => []) => {
+export const registrations = (from = document, known = () => [], page = pageOf(from)) => {
     const findings = [];
     const registry = globalThis.customElements;
     const said = new Set();
@@ -289,7 +295,7 @@ export const registrations = (from = document, known = () => []) => {
     if (!registry) {
         return findings;
     }
-    for (const element of from.querySelectorAll('*')) {
+    for (const element of page.elements) {
         const tag = element.localName;
         if (!tag.startsWith('helix-') || said.has(tag)) {
             continue;
@@ -301,37 +307,30 @@ export const registrations = (from = document, known = () => []) => {
     }
     return findings;
 };
-export const skew = (tags, from) => {
+export const skew = (tags, from, page = pageOf(from)) => {
     const findings = [];
     const said = new Set();
-    const visit = (root, depth) => {
-        if (depth > 32) {
-            return;
+    for (const element of page.elements) {
+        const shadow = element.shadowRoot;
+        if (!shadow) {
+            continue;
         }
-        for (const element of root.querySelectorAll('*')) {
-            const shadow = element.shadowRoot;
-            if (!shadow) {
-                continue;
-            }
-            const tag = element.localName;
-            const published = tags.get(tag);
-            if (published && !said.has(tag)) {
-                const rendered = new Set([...shadow.querySelectorAll('[part]')].flatMap((node) => (node.getAttribute('part') ?? '').split(/\s+/).filter(Boolean)));
-                const missing = [...rendered].filter((name) => !published.parts.has(name)).sort();
-                if (missing.length > 0) {
-                    said.add(tag);
-                    findings.push({
-                        kind: 'manifest-skew',
-                        message: `\`${tag}\` renders ${missing.map((name) => `\`${name}\``).join(', ')}, which the manifest passed in does not list, so the manifest is from a different version of Helix than the page runs. Every other finding would be judged against the wrong version, so none are reported. Pass the \`custom-elements.json\` from the installed packages.`,
-                        subject: tag,
-                        tag,
-                    });
-                }
+        const tag = element.localName;
+        const published = tags.get(tag);
+        if (published && !said.has(tag)) {
+            const rendered = new Set([...shadow.querySelectorAll('[part]')].flatMap((node) => (node.getAttribute('part') ?? '').split(/\s+/).filter(Boolean)));
+            const missing = [...rendered].filter((name) => !published.parts.has(name)).sort();
+            if (missing.length > 0) {
+                said.add(tag);
+                findings.push({
+                    kind: 'manifest-skew',
+                    message: `\`${tag}\` renders ${missing.map((name) => `\`${name}\``).join(', ')}, which the manifest passed in does not list, so the manifest is from a different version of Helix than the page runs. Every other finding would be judged against the wrong version, so none are reported. Pass the \`custom-elements.json\` from the installed packages.`,
+                    subject: tag,
+                    tag,
+                });
             }
-            visit(shadow, depth + 1);
         }
-    };
-    visit(from, 0);
+    }
     return findings;
 };
 export const versionSkew = (manifests, seen) => seen.length === 0
@@ -380,66 +379,57 @@ const GLOBAL = new Set([
 ]);
 const PREFIXES = ['aria-', 'data-', 'on', '_ngcontent-', '_nghost-', 'ng-', 'v-', 'x-', ':', '@'];
 const HOOK_DISTANCE = 2;
-export const markup = (tags, from) => {
+export const markup = (tags, from, page = pageOf(from)) => {
     const found = new Map();
-    const visit = (root, depth) => {
-        if (depth > 32) {
-            return;
-        }
-        for (const element of root.querySelectorAll('*')) {
-            const host = element.getRootNode();
-            const composed = host instanceof ShadowRoot && host.host.localName.startsWith('helix-');
-            const published = composed ? undefined : tags.get(element.localName);
-            if (published) {
-                for (const { name, value } of Array.from(element.attributes)) {
-                    if (GLOBAL.has(name) ||
-                        PREFIXES.some((prefix) => name.startsWith(prefix)) ||
-                        published.written.has(name)) {
-                        continue;
-                    }
-                    const tag = element.localName;
-                    const allows = published.attributes.get(name);
-                    let raw;
-                    if (allows === undefined) {
-                        const suggestion = nearest(name, published.attributes.keys());
-                        raw = {
-                            expected: suggestion,
-                            kind: 'unknown-attribute',
-                            message: suggestion
-                                ? `\`${tag}\` takes no attribute \`${name}\`, so it does nothing. The closest it takes is \`${suggestion}\`.`
-                                : `\`${tag}\` takes no attribute \`${name}\`, so it does nothing.`,
-                            subject: `<${tag} ${name}>`,
-                            tag,
-                        };
-                    }
-                    else if (allows && value !== '' && !allows.has(value)) {
-                        const suggestion = nearest(value, allows);
-                        raw = {
-                            expected: suggestion,
-                            kind: 'invalid-value',
-                            message: `\`${tag}\`'s \`${name}\` takes ${[...allows].map((one) => `\`${one}\``).join(', ')}, so \`${value}\` falls back to the default.${suggestion ? ` The closest is \`${suggestion}\`.` : ''}`,
-                            subject: `<${tag} ${name}="${value}">`,
-                            tag,
-                        };
+    for (const element of page.elements) {
+        const host = element.getRootNode();
+        const composed = host instanceof ShadowRoot && host.host.localName.startsWith('helix-');
+        const published = composed ? undefined : tags.get(element.localName);
+        if (published) {
+            for (const { name, value } of Array.from(element.attributes)) {
+                if (GLOBAL.has(name) ||
+                    PREFIXES.some((prefix) => name.startsWith(prefix)) ||
+                    published.written.has(name)) {
+                    continue;
+                }
+                const tag = element.localName;
+                const allows = published.attributes.get(name);
+                let raw;
+                if (allows === undefined) {
+                    const suggestion = nearest(name, published.attributes.keys());
+                    raw = {
+                        expected: suggestion,
+                        kind: 'unknown-attribute',
+                        message: suggestion
+                            ? `\`${tag}\` takes no attribute \`${name}\`, so it does nothing. The closest it takes is \`${suggestion}\`.`
+                            : `\`${tag}\` takes no attribute \`${name}\`, so it does nothing.`,
+                        subject: `<${tag} ${name}>`,
+                        tag,
+                    };
+                }
+                else if (allows && value !== '' && !allows.has(value)) {
+                    const suggestion = nearest(value, allows);
+                    raw = {
+                        expected: suggestion,
+                        kind: 'invalid-value',
+                        message: `\`${tag}\`'s \`${name}\` takes ${[...allows].map((one) => `\`${one}\``).join(', ')}, so \`${value}\` falls back to the default.${suggestion ? ` The closest is \`${suggestion}\`.` : ''}`,
+                        subject: `<${tag} ${name}="${value}">`,
+                        tag,
+                    };
+                }
+                if (raw) {
+                    const key = `${raw.kind} ${raw.subject}`;
+                    const seen = found.get(key);
+                    if (seen) {
+                        seen.count += 1;
                     }
-                    if (raw) {
-                        const key = `${raw.kind} ${raw.subject}`;
-                        const seen = found.get(key);
-                        if (seen) {
-                            seen.count += 1;
-                        }
-                        else {
-                            found.set(key, { ...raw, count: 1 });
-                        }
+                    else {
+                        found.set(key, { ...raw, count: 1 });
                     }
                 }
             }
-            if (element.shadowRoot) {
-                visit(element.shadowRoot, depth + 1);
-            }
         }
-    };
-    visit(from, 0);
+    }
     return [...found.values()].map(({ count, ...raw }) => ({
         ...raw,
         message: count > 1 ? `${raw.message} On ${count} elements.` : raw.message,

package/dist/collect.d.ts

@@ -15,6 +15,7 @@
  * the only way to know. Each one becomes a `Coverage.unreadable` entry, so the
  * hole is in the output rather than in the reader's assumptions.
  */
+import { type Page } from './page.js';
 import type { Coverage } from './report.js';
 /** One rule, with where it came from. */
 export interface Located {
@@ -67,7 +68,7 @@ export type Readers = Map<string, Array<{
  * hundred passes over rules already read. A `Set` keyed on the sheet object
  * fixes the number and the cost together.
  */
-export declare const collect: (from?: Document) => {
+export declare const collect: (from?: Document, page?: Page) => {
     answered: Answered;
     coverage: Coverage;
     readers: Readers;

package/dist/collect.js

@@ -1,3 +1,4 @@
+import { OVERLAY, pageOf } from './page.js';
 const name = (sheet, seen, host) => {
     if (sheet.href) {
         return sheet.href;
@@ -62,19 +63,7 @@ const read = (sheet, into, unreadable, labels, depth = 0, host, reads) => {
     rules(list, label, into, depth, reads);
     return true;
 };
-const roots = (from, found, depth = 0) => {
-    if (depth > 32) {
-        return;
-    }
-    for (const element of from.querySelectorAll('*')) {
-        const root = element.shadowRoot;
-        if (root) {
-            found.push(root);
-            roots(root, found, depth + 1);
-        }
-    }
-};
-export const collect = (from = document) => {
+export const collect = (from = document, page = pageOf(from)) => {
     const located = [];
     const unreadable = [];
     const seen = new Set();
@@ -119,8 +108,7 @@ export const collect = (from = document) => {
     for (const sheet of from.adoptedStyleSheets ?? []) {
         take(sheet);
     }
-    const shadows = [];
-    roots(from, shadows);
+    const shadows = page.roots.filter((root) => root.host.localName !== OVERLAY);
     for (const root of shadows) {
         for (const sheet of Array.from(root.styleSheets ?? [])) {
             take(sheet, root.host);

package/dist/config.d.ts

@@ -21,6 +21,12 @@ export interface Config {
     rules?: Rules;
     /** Each category, sent or withheld. Nothing is sent without a key. */
     send?: Partial<Record<Category, boolean>>;
+    /**
+     * Where `initDiagnostics()` hands each run, beside the console: the
+     * `overlay` on the page, and the `relay`, `helix diagnostics`, on or off or
+     * at an address of its own.
+     */
+    sinks?: Partial<Configuration['sinks']>;
 }
 /** The shipped defaults. */
 export declare const DEFAULTS: {
@@ -48,7 +54,18 @@ export declare const DEFAULTS: {
         readonly runtime: true;
         readonly usage: true;
     };
+    readonly sinks: {
+        readonly overlay: true;
+        readonly relay: false;
+    };
 };
+/**
+ * A local host: `localhost`, `127.0.0.1`, `[::1]`, `*.localhost`, and `*.test`.
+ * A page with no declared environment runs only on one, and the relay is only
+ * ever at one, as `helix diagnostics` takes runs only from one: a relay at
+ * another address would be a second way to send, with no key and no `send`.
+ */
+export declare const LOCAL: RegExp;
 /** Throws on a setting that names nothing, or a value it cannot take. */
 export declare const checkConfig: (config: Config | undefined, layer: Exclude<Layer, 'shipped'>) => void;
 /** The settings in effect, from the defaults, the file, and the call. */

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 }),