@fusion.dev/helix-diagnostics 0.137.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 { 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, 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 { 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
 
@@ -95,11 +197,24 @@ works on it:
 | Kind | Severity | Means |
 | --- | --- | --- |
 | `dead-part` | error | A `::part()` names a part the element does not publish |
-| `dead-hook` | error | A custom property is set where nothing answers it |
+| `dead-hook` | error | A hook is set where nothing answers it, or a name close to a hook is set that nothing reads |
+| `unknown-attribute` | error | A Helix element carries an attribute it does not take |
+| `invalid-value` | error | An attribute with a closed set of values carries one outside it, so the element falls back to its default |
 | `unforwarded-part` | warn | The headless tier publishes the part and the styled tier does not forward it, which is a gap in Helix |
 | `unknown-tag` | error | A rule names a tag no manifest lists |
 | `duplicate-registration` | error | Two copies of Helix are on the page |
-| `manifest-skew` | error | An element renders a part its manifest does not list, so the manifest is from another version. It replaces every other finding, since each would be judged against the wrong version. Turned off, the page is judged as usual |
+| `manifest-skew` | error | The manifest is from another version than the page runs. It replaces every other finding, since each would be judged against the wrong version. Turned off, the page is judged as usual |
+
+**Hooks are checked wherever they are set**: on a Helix tag, a class, `:root`,
+or any other selector. A hook on a selector naming no Helix tag is judged only
+on what the page holds now. It is a finding when the selector matches elements
+and none of them is, or holds, an element that answers it, while one that does
+is on the page. A selector matching nothing yet is left alone, since it may be
+for another route.
+
+**Attributes are checked on the elements the page wrote.** The global HTML
+attributes, `aria-*`, `data-*`, and the prefixes frameworks write are never
+findings. The markup Helix renders inside its own components is Helix's.
 
 ## Configure it
 
@@ -135,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` |
@@ -142,13 +259,32 @@ 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.
+
+**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
+
+`@fusion.dev/helix-diagnostics/ci` gathers the runs of a CI job into one JSON
+file, in the shape every sink shares, and says whether the job should fail:
+
+```js
+import { ciSink } from '@fusion.dev/helix-diagnostics/ci'
+
+// `runs` are the reports `diagnose` returned in each page your job opened.
+const { code, summary } = ciSink(runs, { file: 'reports/helix-diagnostics.json' })
+console.log(summary)
+process.exitCode = code
+```
 
-Development only. It walks every stylesheet in the page, and it sends nothing
-anywhere.
+A fault found on many pages is one line, with the pages it was on. `error`
+findings fail the job by default; pass `failOn: 'warn'` to fail on warnings
+too, or `'never'` to report without failing.
 
 ## Versions
 

package/dist/analyze.d.ts

@@ -16,8 +16,9 @@
  * consumer's own `--my-app-gap` out of the findings without a list of
  * exemptions, and what lets a finding say which tag it is wrong for.
  */
-import type { Answered, Located } from './collect.js';
+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.
  *
@@ -33,7 +44,7 @@ export declare const parts: (selector: string) => Array<{
  * unforwarded part is phrased: the part exists, another tier publishes it, and
  * the one being styled did not forward it.
  */
-export declare const analyze: (rules: Located[], tags: Map<string, Published>, from?: Document, answered?: Answered) => Raw[];
+export declare const analyze: (rules: Located[], tags: Map<string, Published>, from?: Document, answered?: Answered, used?: Set<string>, readers?: Readers) => Raw[];
 /**
  * Two copies of Helix on one page, which is not a CSS fault and is the most
  * expensive one on the list.
@@ -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
@@ -75,3 +86,13 @@ export declare const skew: (tags: Map<string, Published>, from: Document) => Raw
  * `diagnose` makes first.
  */
 export declare const versionSkew: (manifests: Record<string, string>, seen: string[]) => Raw[];
+/**
+ * The attributes on the page's Helix elements that do nothing: a name the
+ * element does not take, and a value outside the ones a closed set allows.
+ * Both are valid HTML and silent, since the element falls back to its default.
+ *
+ * **Only what the page wrote.** An element Helix renders inside another is
+ * 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, page?: Page) => Raw[];