@fusion.dev/helix-diagnostics 0.138.0 → 0.140.0

package/README.md

@@ -8,38 +8,147 @@ 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 })
 ```
 
-`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.
+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.
+- **Hears what the library reports as it runs**, such as a selectable table
+  with no `row-key`, and lists each event in the run, the badge, and the relay.
+  Core still prints each one as it happens, with the stack it happened in. Set
+  `core: { warnings: false }` to have diagnostics print them in its group
+  instead.
+- **Measures what the components cost, where you ask**: each tag's first
+  updates, layout shift, and long tasks. See [Performance](#performance).
+- **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`, `core`, `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 } })
+```
 
-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.
+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 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 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
 
@@ -61,6 +170,13 @@ A report is one run, in one shape for every sink, versioned by `schema`:
   `integrity`, or `guideline`), an `owner` (`consumer`, or `helix` for a fault
   in the library), a `fingerprint` that stays the same from one run to the next
   for the same fault, and the rule's own text as evidence.
+- **`performance`**: what the components cost, by tag, where you asked for it.
+  See [Performance](#performance).
+- **`runtime`**: what the library reported going wrong as it ran on the page,
+  from its first load. One entry per distinct event, with its `kind`, its
+  `tag`, the sentence that says what to do, how many times it was reported,
+  and whether core printed it. A `fingerprint` stays the same from one run to
+  the next, with the numbers in the sentence left out.
 - **`usage`**: the Helix elements on the page by tag, the axes set on them
   (`emphasis`, `material`, `separation`, and `tone`), the named slots filled,
   the elements Helix renders inside other Helix elements, and the parts and
@@ -86,9 +202,11 @@ works on it:
 | A finding at `error` | `console.error` |
 | A finding at `warn` | `console.warn` |
 | A finding at `info` | `console.info` |
+| A runtime event core left to diagnostics | `console.warn`, or `console.error` for a failure |
 | Stylesheets that could not be read | `console.warn` |
 | Coverage, and findings turned off | `console.info` |
 | Usage | `console.debug`, hidden at the default level |
+| Performance, where you asked for it | `console.info`, when the measures change |
 
 ## Finding kinds
 
@@ -114,6 +232,58 @@ for another route.
 attributes, `aria-*`, `data-*`, and the prefixes frameworks write are never
 findings. The markup Helix renders inside its own components is Helix's.
 
+## Runtime events
+
+Helix reports these itself as it runs, through one channel in
+`@fusion.dev/helix-core`. Each is printed in the console as it happens, and
+diagnostics counts it by kind and tag. None fails a CI job.
+
+| Kind | Means |
+| --- | --- |
+| `duplicate-registration` | Two copies of Helix are on the page. Also the finding of the same name |
+| `fullscreen-refused` | The browser refused fullscreen, usually in a frame without `allow="fullscreen"` |
+| `max-past-fold` | An avatar group's `max` is past the number its fold is written for |
+| `min-out-of-range` | A rating's `min` is not a score between 0 and its `max` |
+| `misplaced-handler` | A React `on` prop names an event that another element dispatches |
+| `missing-layout` | The three.js graph driver could not load `d3-force-3d` |
+| `missing-row-key` | A selectable data table has no `row-key`, so it knows each row by its place |
+| `missing-stencil-parts` | A graph stencil names parts its shape does not have |
+| `missing-trigger` | A tooltip's `for` names no element in its own tree |
+| `negative-value` | An area chart was given a negative number, which it draws as none |
+| `not-a-graph` | `connectGraph` was given an element that is not a graph frame |
+| `picture-in-picture-refused` | The browser refused picture in picture |
+| `removed-callback` | A React prop is a callback that was removed and never ran from JSX |
+| `solid-handler-syntax` | A React prop uses Solid's `on:` syntax |
+| `stencil-regions-unused` | A graph stencil's regions could not be used |
+| `stencil-without-inside` | A graph stencil has no inside to place the notes in |
+| `too-many-rows` | A data table is drawing more rows at once than it stays responsive to |
+| `two-default-operators` | A filter field marks more than one operator as its default |
+| `unknown-event` | A React `on` prop names an event that no element dispatches |
+| `unlinked-trigger` | A tooltip's trigger does not name it in `aria-describedby` |
+| `unsettled-window` | A virtualized list's box has no height of its own |
+| `untold-trigger` | A slotted trigger is a plain element, which cannot carry `aria-expanded` |
+| `wrapped-trigger` | A tooltip wraps its trigger, so its text reaches no screen reader |
+
+## Performance
+
+Diagnostics measures what the components cost only where you ask for it. Set
+`console: { performance: 'info' }` to print the measures in DevTools, or
+`send: { performance: true }` to keep them in each run, for your app, the
+relay, and the CI file. For each tag rendered on the page, it measures:
+
+- **First updates**: each element's own first update, from `willUpdate` to
+  `updated`, as a count, a median, a 95th percentile, and the slowest. Time an
+  element spends waiting behind other elements is not counted.
+- **Layout shift**: the shift its elements moved, summed as the browser scores
+  it. A shift that follows a press or a keystroke is left out.
+- **Long tasks**: how many tasks of 50 ms or more one of its first updates ran
+  in.
+
+Core times each first update only while diagnostics is measuring, so a page
+that has not asked pays one property read per element. Layout shift and long
+tasks are measured in Chromium only. Elsewhere `measured` says so, and their
+numbers are left out.
+
 ## Configure it
 
 Every setting can be given in three places, and a later place wins, field by
@@ -148,6 +318,11 @@ 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` |
+| `console.runtime` | `warn` or `off`: the runtime events core left to diagnostics | `warn` |
+| `console.performance` | `info` or `off`: what the components cost, which is measured where this is on | `off` |
+| `core.warnings` | `true` or `false`: whether core prints each runtime event as it happens | `true` |
+| `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 +330,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/ci.js

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { shownRuntime } from './runtime.js';
 const RANK = { error: 3, info: 1, warn: 2 };
 const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
 export const ciSink = (runs, { file, failOn = 'error' }) => {
@@ -17,8 +18,17 @@ export const ciSink = (runs, { file, failOn = 'error' }) => {
     const of = (severity) => all.filter(({ finding }) => finding.severity === severity).length;
     const failing = failOn === 'never' ? [] : all.filter(({ finding }) => RANK[finding.severity] >= RANK[failOn]);
     const unread = runs.reduce((total, run) => total + run.coverage.unreadable.length, 0);
+    const events = new Map();
+    for (const run of runs) {
+        for (const entry of shownRuntime(run.runtime ?? [])) {
+            const event = events.get(entry.fingerprint) ?? { entry, pages: new Set() };
+            event.pages.add(run.run.page ?? '(no page)');
+            events.set(entry.fingerprint, event);
+        }
+    }
     const lines = [
         `helix diagnostics: ${counted(runs.length, 'run')}, ${counted(of('error'), 'error')}, ${counted(of('warn'), 'warning')}, ${of('info')} info` +
+            (events.size > 0 ? `, ${events.size} runtime` : '') +
             (unread > 0 ? `, ${counted(unread, 'unreadable stylesheet')}` : '') +
             `. Written to ${file}.`,
     ];
@@ -26,5 +36,9 @@ export const ciSink = (runs, { file, failOn = 'error' }) => {
         const where = [...pages].sort();
         lines.push(`  ${finding.severity} ${finding.kind}: ${finding.subject}`, `    ${finding.message}`, `    on ${where.slice(0, 5).join(', ')}${where.length > 5 ? `, and ${where.length - 5} more` : ''}`);
     }
+    for (const { entry, pages } of events.values()) {
+        const where = [...pages].sort();
+        lines.push(`  runtime ${entry.kind}${entry.tag ? ` <${entry.tag}>` : ''}`, `    ${entry.message}`, `    on ${where.slice(0, 5).join(', ')}${where.length > 5 ? `, and ${where.length - 5} more` : ''}`);
+    }
     return { code: failing.length > 0 ? 1 : 0, summary: lines.join('\n') };
 };

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;