@fusion.dev/helix-diagnostics 0.135.0 → 0.136.0

package/README.md

@@ -9,28 +9,107 @@ npm install --save-dev @fusion.dev/helix-diagnostics
 ```
 
 ```js
-import { diagnose, report } from '@fusion.dev/helix-diagnostics'
+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' }
 
-report(diagnose({ tiers: [headless] }))
+// 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,
+  }),
+)
 ```
 
-`diagnose` needs at least one manifest and says so rather than defaulting: with
-none, every part name is unknown and every finding would be noise. `report` is
-the console sink; the `Report` it returns is the same object, so you can send it
-somewhere else instead.
+`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.
 
 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.
 
-**Coverage is half the return value, not a footnote.** A cross-origin stylesheet
-throws on `.cssRules`, so a run that read three sheets of nineteen returns the
-same empty findings array as one that read all nineteen. Read `coverage` before
-you believe `findings`.
+## What a report holds
+
+- **`coverage`**: how many stylesheets and shadow roots were read, and which
+  sheets could not be. A cross-origin stylesheet throws on `.cssRules`, so a run
+  that read three sheets of nineteen returns the same empty findings as one that
+  read all nineteen. Read `coverage` before you believe `findings`.
+- **`findings`**: each with its kind, a severity, the layer that set the
+  severity, the tag, and the rule's own text as evidence.
+- **`silenced`**: how many findings each override layer turned off.
+- **`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
+  hooks your stylesheets use. With a watcher it counts every element that
+  rendered since `watch()` began, including ones since removed, such as a
+  closed dialog. Without one it counts the elements on the page at the moment
+  of the run. Elements named `helix-*` that no manifest lists, such as your
+  own, are counted apart as `unlisted`.
+
+## What the console shows
+
+`report` writes one group per run, headed by the counts. It opens when there
+is something to act on, and collapses to one line when the run is clean. Each
+kind of entry goes to its own console method, so the browser's level filter
+works on it:
+
+| Entry | Console method |
+| --- | --- |
+| A finding at `error` | `console.error` |
+| A finding at `warn` | `console.warn` |
+| A finding at `info` | `console.info` |
+| Stylesheets that could not be read | `console.warn` |
+| Coverage, and findings turned off | `console.info` |
+| Usage | `console.debug`, hidden at the default level |
+
+## Finding kinds
+
+| 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 |
+| `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 |
+
+## Change a severity
+
+Pass your project's file, parsed, as `file`, and overrides for one run as
+`rules`. The `rules` argument wins over the file, and each finding says which
+one set its severity. An override is a severity (`error`, `warn`, or `info`),
+`off`, or either for some tags only:
+
+```js
+import overrides from './helix-diagnostics.json' with { type: 'json' }
+
+diagnose({
+  file: overrides,
+  rules: {
+    'dead-hook': { severity: 'warn', tags: ['helix-card'] },
+    'unforwarded-part': 'off',
+  },
+  tiers,
+})
+```
+
+An override for a kind that does not exist throws, and names the closest kind.
 
-Development only. It walks stylesheets in the page and makes no network calls,
-ever.
+Development only. It walks every stylesheet in the page, and it sends nothing
+anywhere.
 
 [Documentation](https://fusion.dev/helix)
 

package/dist/analyze.d.ts

@@ -18,7 +18,14 @@
  */
 import type { Answered, Located } from './collect.js';
 import { type Published } from './manifest.js';
-import type { Finding } from './report.js';
+import type { Raw } from './report.js';
+/** Every `helix-*` tag a selector mentions, in source order. */
+export declare const targets: (selector: string) => string[];
+/** Every `::part(a b)` in a selector, with the tag it hangs off. */
+export declare const parts: (selector: string) => Array<{
+    names: string[];
+    tag: string;
+}>;
 /**
  * The findings in one page's rules.
  *
@@ -26,7 +33,7 @@ import type { Finding } from './report.js';
  * 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) => Finding[];
+export declare const analyze: (rules: Located[], tags: Map<string, Published>, from?: Document, answered?: Answered) => Raw[];
 /**
  * Two copies of Helix on one page, which is not a CSS fault and is the most
  * expensive one on the list.
@@ -44,4 +51,20 @@ 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[]) => Finding[];
+export declare const registrations: (from?: Document, known?: () => string[]) => 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.
+ *
+ * **Read from what the elements render, because nothing records a version.**
+ * Neither the manifest nor the running code carries one. What a matching
+ * manifest guarantees is that every part an element renders is listed, since
+ * both are built from the same source, so a rendered part the manifest lacks
+ * means the two were built from different source. The reverse proves nothing:
+ * an element renders some parts only in some states.
+ *
+ * **One finding replaces all the others** (see `diagnose`). A part renamed
+ * 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[];

package/dist/analyze.js

@@ -1,12 +1,12 @@
 import { nearest } from './manifest.js';
-const targets = (selector) => {
+export const targets = (selector) => {
     const found = new Set();
     for (const match of selector.matchAll(/\bhelix-[a-z0-9]+(?:-[a-z0-9]+)*/g)) {
         found.add(match[0]);
     }
     return [...found];
 };
-const parts = (selector) => {
+export const parts = (selector) => {
     const found = [];
     for (const match of selector.matchAll(/(helix-[a-z0-9-]+)((?:[^\s>+~,]*))::part\(\s*([^)]*?)\s*\)/g)) {
         const names = (match[3] ?? '').split(/\s+/).filter(Boolean);
@@ -55,6 +55,7 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
                     message: `\`${tag}\` is in no manifest passed to the collector. Either the tag is misspelled, or the manifest is from a different version of Helix than the page.`,
                     origin: origin(located),
                     subject: tag,
+                    tag,
                 });
                 continue;
             }
@@ -71,6 +72,7 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
                         message: `\`${tag}\` does not publish \`${part}\`, though \`${elsewhere[0]}\` does. The rule matches nothing until the part is forwarded, which is a gap in Helix rather than in this CSS.`,
                         origin: origin(located),
                         subject: `${tag}::part(${part})`,
+                        tag,
                     });
                     continue;
                 }
@@ -83,6 +85,7 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
                         : `\`${tag}\` publishes no part named \`${part}\`, so this rule matches nothing. Published: ${[...element.parts.keys()].sort().join(', ') || 'none'}.`,
                     origin: origin(located),
                     subject: `${tag}::part(${part})`,
+                    tag,
                 });
             }
         }
@@ -131,6 +134,7 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
                     : `\`${tag}\` does not answer \`${property}\`, and nothing under it that does was found in the page. ${[...answerers].sort().slice(0, 3).join(', ')} answer it, so this either targets the wrong element or expects a descendant that is not there.`,
                 origin: origin(located),
                 subject: `${selector} { ${property} }`,
+                tag,
             });
         }
     }
@@ -149,6 +153,7 @@ export const registrations = (from = document, known = () => []) => {
             kind: 'duplicate-registration',
             message: `\`${tag}\` is registered twice by different classes, so this page holds two copies of Helix (${how}). The first registration keeps the tag: every element of that name is built from it whatever the second copy exports, which makes \`instanceof\` against the second copy false and leaves its fixes out of the DOM. Deduplicate the dependency.`,
             subject: tag,
+            tag,
         });
     };
     for (const tag of known()) {
@@ -169,3 +174,36 @@ export const registrations = (from = document, known = () => []) => {
     }
     return findings;
 };
+export const skew = (tags, from) => {
+    const findings = [];
+    const said = new Set();
+    const visit = (root, depth) => {
+        if (depth > 32) {
+            return;
+        }
+        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,
+                    });
+                }
+            }
+            visit(shadow, depth + 1);
+        }
+    };
+    visit(from, 0);
+    return findings;
+};

package/dist/console.d.ts

@@ -1,5 +1,20 @@
 /**
- * The default sink: the console, and coverage before anything else.
+ * The default sink: the console, at the level each entry deserves.
+ *
+ * **Each kind of entry has its own console level**, so the browser's level
+ * filter and a test runner's capture treat each as what it is:
+ *
+ * | Entry | Level | Why |
+ * | --- | --- | --- |
+ * | A finding at `error` | `console.error` | The CSS does nothing where it was written |
+ * | A finding at `warn` | `console.warn` | Worth fixing, and the page works |
+ * | A finding at `info` | `console.info` | Advice |
+ * | Unreadable stylesheets | `console.warn` | The run could not see part of the page |
+ * | Coverage, overrides, a clean run | `console.info` | What the run looked at |
+ * | Usage | `console.debug` | For whoever studies usage, hidden at the default level |
+ *
+ * **All of it in one group**, headed by the counts, so a page with other logs
+ * keeps a run together and a clean run collapses to one line.
  *
  * **Coverage is printed on a clean run too.** "No findings" from a collector
  * that read three sheets of nineteen is not a pass, and the only way to stop
@@ -7,9 +22,10 @@
  * single time.
  *
  * A sink and not a policy. It writes and returns; a CI sink writing JSON and an
- * OTLP exporter are the same `Report` consumed differently, which is what keeps
- * all three agreeing by construction rather than by our diligence.
+ * OTLP exporter are the same `Report` consumed differently.
  */
 import type { Report } from './report.js';
+/** The console methods this sink calls. A test hands in its own. */
+export type ConsoleSink = Pick<Console, 'debug' | 'error' | 'group' | 'groupCollapsed' | 'groupEnd' | 'info' | 'warn'>;
 /** Writes a report and hands it back, so a caller can chain a second sink. */
-export declare const report: (result: Report, to?: Console) => Report;
+export declare const report: (result: Report, to?: ConsoleSink) => Report;

package/dist/console.js

@@ -1,30 +1,47 @@
-const line = (finding) => {
-    const out = [`  ${finding.kind}: ${finding.subject}`, `    ${finding.message}`];
+const entry = (finding) => {
+    const by = finding.decidedBy === 'shipped' ? '' : ` (${finding.severity}, set by the ${finding.decidedBy})`;
+    const lines = [`${finding.kind}${by}: ${finding.subject}`, finding.message];
     if (finding.origin) {
-        out.push(`    in ${finding.origin.sheet}, rule ${finding.origin.index}`);
-        out.push(`    ${finding.origin.cssText}`);
+        lines.push(`in ${finding.origin.sheet}, rule ${finding.origin.index}`, finding.origin.cssText);
     }
-    return out;
+    return lines.join('\n');
 };
+const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
 export const report = (result, to = console) => {
     const { coverage, findings } = result;
+    const bySeverity = (severity) => findings.filter((finding) => finding.severity === severity).length;
+    const errors = bySeverity('error');
+    const warnings = bySeverity('warn');
     const missed = coverage.sheets - coverage.read;
-    to.log(`helix diagnostics: read ${coverage.read} of ${coverage.sheets} stylesheets across ${coverage.roots} shadow roots` +
-        (missed > 0 ? `, ${missed} unreadable` : ''));
-    for (const sheet of coverage.unreadable) {
-        to.log(`  unreadable (${sheet.reason}): ${sheet.sheet}`);
+    const heading = findings.length === 0
+        ? 'helix diagnostics: no findings'
+        : `helix diagnostics: ${counted(errors, 'error')}, ${counted(warnings, 'warning')}, ${bySeverity('info')} info`;
+    if (errors + warnings > 0 || missed > 0) {
+        to.group(heading);
     }
-    if (findings.length === 0) {
-        to.log(missed > 0
-            ? '  no findings in what could be read. The unreadable sheets above were not checked.'
-            : '  no findings.');
-        return result;
+    else {
+        to.groupCollapsed(heading);
+    }
+    to.info(`read ${coverage.read} of ${counted(coverage.sheets, 'stylesheet')} across ${counted(coverage.roots, 'shadow root')}`);
+    if (missed > 0) {
+        to.warn([
+            `${counted(missed, 'stylesheet')} could not be read, so ${missed === 1 ? 'it was' : 'they were'} not checked:`,
+            ...coverage.unreadable.map((sheet) => `${sheet.sheet} (${sheet.reason})`),
+        ].join('\n'));
+    }
+    const { argument, file } = result.silenced;
+    if (argument + file > 0) {
+        to.info(`${counted(argument + file, 'finding')} turned off: ${file} by the file, ${argument} by the argument`);
     }
-    to.log(`  ${findings.length} finding${findings.length === 1 ? '' : 's'}:`);
     for (const finding of findings) {
-        for (const text of line(finding)) {
-            to.log(text);
-        }
+        to[finding.severity](entry(finding));
     }
+    const { counted: how, hooks, parts, tags, unlisted } = result.usage;
+    const sum = (counts) => Object.values(counts).reduce((total, one) => total + Object.keys(one).length, 0);
+    const elements = Object.values(tags).reduce((total, one) => total + one, 0);
+    const others = Object.keys(unlisted).length;
+    to.debug(`usage (${how}): ${counted(Object.keys(tags).length, 'tag')} in ${counted(elements, 'element')}, ${counted(sum(parts), 'part')} styled, ${counted(sum(hooks), 'hook')} set` +
+        (others > 0 ? `, and ${counted(others, 'helix- tag')} no manifest lists` : ''));
+    to.groupEnd();
     return result;
 };

package/dist/index.d.ts

@@ -20,10 +20,9 @@
  * report(diagnose({ tiers: [{ manifest: styled, name: '@fusion.dev/helix' }] }))
  * ```
  *
- * **Zero network calls, at this layer, ever.** The privacy policy this project
- * published says the site sends nothing, and a diagnostics package that phones
- * home from a consumer's page would make us the third party we told our own
- * readers we were not. Findings go where the caller puts them.
+ * **Nothing here sends anything.** `diagnose` returns a report and `report`
+ * prints it. Where else a report goes is a sink's decision, and every sink
+ * that leaves the page is one the caller adds.
  *
  * **Development only.** Import it from a dev-only entry: it walks every
  * stylesheet in the page and has no business in a production bundle.
@@ -32,9 +31,14 @@ export { collect } from './collect.js';
 export { report } from './console.js';
 export type { ManifestSource, Published, Tier } from './manifest.js';
 export { index, nearest } from './manifest.js';
-export type { Coverage, Finding, Origin, Report, Unreadable } from './report.js';
+export type { Coverage, Finding, Kind, Layer, Origin, Report, Severity, Unreadable, Usage, } from './report.js';
+export { KINDS } from './report.js';
+export { type Override, type Rules, SHIPPED_RULES } from './rules.js';
+export { type Watcher, watch } from './usage.js';
 import type { Tier } from './manifest.js';
 import type { Report } from './report.js';
+import { type Rules } from './rules.js';
+import { type Watcher } from './usage.js';
 /** What to look at, and what to compare it against. */
 export interface Options {
     /**
@@ -48,6 +52,11 @@ export interface Options {
      * from outside and cannot name the losing class.
      */
     duplicates?: () => string[];
+    /**
+     * The project's own overrides, parsed from its file. The build reads the
+     * file, since the page cannot: import the JSON and pass it here.
+     */
+    file?: Rules | undefined;
     /**
      * The document to scan. Defaults to the ambient one.
      *
@@ -55,6 +64,15 @@ export interface Options {
      * an iframe it owns can scan that too.
      */
     from?: Document;
+    /**
+     * Overrides for this run, which win over `file`. Each says a severity,
+     * `off`, or either for some tags only:
+     *
+     * ```ts
+     * diagnose({ tiers, rules: { 'unforwarded-part': 'off', 'dead-hook': { severity: 'warn', tags: ['helix-card'] } } })
+     * ```
+     */
+    rules?: Rules | undefined;
     /**
      * The manifests to check against, one per installed tier.
      *
@@ -63,6 +81,11 @@ export interface Options {
      * 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 pass over the page.
@@ -75,5 +98,8 @@ export interface Options {
  *
  * 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: see `skew`.
  */
-export declare const diagnose: ({ duplicates, from, tiers }: Options) => Report;
+export declare const diagnose: ({ duplicates, file, from, rules, tiers, watcher }: Options) => Report;

package/dist/index.js

@@ -1,21 +1,38 @@
 export { collect } from './collect.js';
 export { report } from './console.js';
 export { index, nearest } from './manifest.js';
-import { analyze, registrations } from './analyze.js';
+export { KINDS } from './report.js';
+export { SHIPPED_RULES } from './rules.js';
+export { watch } from './usage.js';
+import { analyze, registrations, skew } from './analyze.js';
 import { collect } from './collect.js';
 import { index } from './manifest.js';
-export const diagnose = ({ duplicates, from, tiers }) => {
+import { applyRules, checkRules } from './rules.js';
+import { listed, styled, walk } from './usage.js';
+export const diagnose = ({ duplicates, file, from, rules, tiers, watcher }) => {
     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.');
     }
+    checkRules(file, 'file');
+    checkRules(rules, 'argument');
     const document_ = from ?? globalThis.document;
-    const { answered, coverage, rules } = collect(document_);
+    const { answered, coverage, rules: located } = collect(document_);
     const tags = index(tiers);
+    const skewed = applyRules(skew(tags, document_), file, rules);
+    const judged = skewed.findings.length > 0
+        ? { findings: [], silenced: { argument: 0, file: 0 } }
+        : applyRules([...analyze(located, tags, document_, answered), ...registrations(document_, duplicates)], file, rules);
     return {
         coverage,
-        findings: [
-            ...analyze(rules, tags, document_, answered),
-            ...registrations(document_, duplicates),
-        ],
+        findings: [...skewed.findings, ...judged.findings],
+        silenced: {
+            argument: skewed.silenced.argument + judged.silenced.argument,
+            file: skewed.silenced.file + judged.silenced.file,
+        },
+        usage: {
+            ...listed(watcher ? watcher.counts() : walk(document_), tags),
+            ...styled(located, tags, answered),
+            counted: watcher ? 'watched' : 'walked',
+        },
     };
 };

package/dist/report.d.ts

@@ -49,14 +49,34 @@ export interface Finding {
      */
     expected?: string | undefined;
     /** Machine-readable fault class, stable across versions. */
-    kind: 'dead-hook' | 'dead-part' | 'duplicate-registration' | 'unforwarded-part' | 'unknown-tag';
+    kind: Kind;
     /** One sentence, addressed to whoever wrote the CSS. */
     message: string;
     /** Where it was read. Absent only for faults that are not in a stylesheet. */
     origin?: Origin;
+    /** How serious it is, after the shipped rules and any overrides. */
+    severity: Severity;
+    /**
+     * Which layer set `severity`: the rules this package ships, the project's
+     * file, or the argument to `diagnose`. With two layers able to override,
+     * a severity alone cannot say where it came from.
+     */
+    decidedBy: Layer;
     /** The selector the fault sits in, or the tag for a runtime fault. */
     subject: string;
+    /** The Helix tag the finding is about, which a scoped override matches on. */
+    tag: string;
 }
+/** Every fault class, stable across versions. */
+export declare const KINDS: readonly ['dead-hook', 'dead-part', 'duplicate-registration', 'manifest-skew', 'unforwarded-part', 'unknown-tag'];
+/** A fault class. */
+export type Kind = (typeof KINDS)[number];
+/** How serious a finding is. */
+export type Severity = 'error' | 'info' | 'warn';
+/** Where a finding's severity was decided. */
+export type Layer = 'argument' | 'file' | 'shipped';
+/** A finding before the rules have given it a severity. */
+export type Raw = Omit<Finding, 'decidedBy' | 'severity'>;
 /** A sheet the collector could not read, and the reason. */
 export interface Unreadable {
     reason: 'cross-origin' | 'detached' | 'threw';
@@ -81,8 +101,58 @@ export interface Coverage {
     /** Every sheet that could not be read, with its reason. */
     unreadable: Unreadable[];
 }
+/**
+ * What a page uses of Helix, counted by tag.
+ *
+ * Plain objects of counts, so a sink can write the report as JSON and read it
+ * back unchanged.
+ */
+export interface Usage {
+    /**
+     * Each axis set, by tag, axis, and value: `emphasis`, `material`,
+     * `separation`, and `tone`. An axis left unset is not counted.
+     */
+    axes: Record<string, Record<string, Record<string, number>>>;
+    /**
+     * The Helix elements other Helix elements render inside their own shadow
+     * roots, such as the select a pagination size draws. Kept apart from
+     * `tags`, which counts what the page put there.
+     */
+    composed: Record<string, number>;
+    /**
+     * How the elements were counted. `watched`: every element that rendered
+     * since `watch()` began, including the ones that have gone, such as a
+     * closed dialog. `walked`: the elements in the page at the moment of the
+     * run, which misses those.
+     */
+    counted: 'walked' | 'watched';
+    /** Each hook the page's stylesheets set, by tag, counted per declaration. */
+    hooks: Record<string, Record<string, number>>;
+    /** Each part the page's stylesheets style, by tag, counted per rule. */
+    parts: Record<string, Record<string, number>>;
+    /** Each named slot filled, by tag. */
+    slots: Record<string, Record<string, number>>;
+    /** Each Helix element the page put there, by tag. */
+    tags: Record<string, number>;
+    /**
+     * Elements named `helix-*` that no manifest passed in lists, by tag: a
+     * page's own element under the prefix, or a family whose manifest was not
+     * passed. Kept out of the other counts, which are Helix's.
+     */
+    unlisted: Record<string, number>;
+}
 /** The whole result. Coverage and findings, never one without the other. */
 export interface Report {
     coverage: Coverage;
     findings: Finding[];
+    /**
+     * How many findings each override layer turned off. A finding turned off
+     * is still a fault, and a report that hid the count would read as cleaner
+     * than the page is.
+     */
+    silenced: {
+        argument: number;
+        file: number;
+    };
+    usage: Usage;
 }

package/dist/report.js

@@ -1 +1,8 @@
-export {};
+export const KINDS = [
+    'dead-hook',
+    'dead-part',
+    'duplicate-registration',
+    'manifest-skew',
+    'unforwarded-part',
+    'unknown-tag',
+];

package/dist/rules.d.ts

@@ -0,0 +1,34 @@
+import { type Finding, type Kind, type Layer, type Raw, type Severity } from './report.js';
+/** One override: a severity, `off`, or either for some tags only. */
+export type Override = Severity | 'off' | {
+    /** The severity, or `off`. */
+    severity: Severity | 'off';
+    /** The tags it applies to. Every other tag keeps the layer below. */
+    tags: string[];
+};
+/** Overrides by kind. A list holds several, each for different tags. */
+export type Rules = Partial<Record<Kind, Override | Override[]>>;
+/**
+ * The shipped severities.
+ *
+ * `unforwarded-part` is a warning because the fault is in Helix: the part
+ * exists on the other tier, and the styled tier never forwarded it.
+ * Everything else means the page's CSS does nothing where it was written, or
+ * that the manifest cannot be trusted, and is an error.
+ */
+export declare const SHIPPED_RULES: Readonly<Record<Kind, Severity>>;
+/** Throws on an override that would silently do nothing. */
+export declare const checkRules: (rules: Rules | undefined, layer: Exclude<Layer, 'shipped'>) => void;
+/**
+ * The findings with their severities, and how many each layer turned off.
+ *
+ * The shipped rule first, then the file, then the argument, each later layer
+ * replacing what it speaks to.
+ */
+export declare const applyRules: (findings: Raw[], file: Rules | undefined, argument: Rules | undefined) => {
+    findings: Finding[];
+    silenced: {
+        argument: number;
+        file: number;
+    };
+};

package/dist/rules.js

@@ -0,0 +1,66 @@
+import { nearest } from './manifest.js';
+import { KINDS } from './report.js';
+export const SHIPPED_RULES = {
+    'dead-hook': 'error',
+    'dead-part': 'error',
+    'duplicate-registration': 'error',
+    'manifest-skew': 'error',
+    'unforwarded-part': 'warn',
+    'unknown-tag': 'error',
+};
+const SEVERITIES = new Set(['error', 'info', 'off', 'warn']);
+export const checkRules = (rules, layer) => {
+    for (const [kind, value] of Object.entries(rules ?? {})) {
+        if (!KINDS.includes(kind)) {
+            const close = nearest(kind, KINDS);
+            throw new Error(`The ${layer} overrides \`${kind}\`, which is no kind of finding.` +
+                (close ? ` The closest is \`${close}\`.` : ` The kinds are ${KINDS.join(', ')}.`));
+        }
+        for (const one of Array.isArray(value) ? value : [value]) {
+            const severity = typeof one === 'string' ? one : one?.severity;
+            if (!SEVERITIES.has(severity)) {
+                throw new Error(`The ${layer} sets \`${kind}\` to \`${String(severity)}\`. A severity is error, warn, info, or off.`);
+            }
+            if (typeof one === 'object' && !(Array.isArray(one.tags) && one.tags.length > 0)) {
+                throw new Error(`The ${layer} scopes \`${kind}\` with no tags. Give the tags it applies to, or set the severity alone.`);
+            }
+        }
+    }
+};
+const said = (rules, finding) => {
+    const value = rules?.[finding.kind];
+    if (value === undefined) {
+        return undefined;
+    }
+    const list = Array.isArray(value) ? value : [value];
+    const scoped = list.find((one) => typeof one === 'object' && one.tags.includes(finding.tag));
+    if (scoped && typeof scoped === 'object') {
+        return scoped.severity;
+    }
+    const plain = list.find((one) => typeof one === 'string');
+    return typeof plain === 'string' ? plain : undefined;
+};
+export const applyRules = (findings, file, argument) => {
+    const silenced = { argument: 0, file: 0 };
+    const kept = [];
+    for (const finding of findings) {
+        let severity = SHIPPED_RULES[finding.kind];
+        let decidedBy = 'shipped';
+        for (const [layer, rules] of [
+            ['file', file],
+            ['argument', argument],
+        ]) {
+            const value = said(rules, finding);
+            if (value !== undefined) {
+                severity = value;
+                decidedBy = layer;
+            }
+        }
+        if (severity === 'off') {
+            silenced[decidedBy] += 1;
+            continue;
+        }
+        kept.push({ ...finding, decidedBy, severity });
+    }
+    return { findings: kept, silenced };
+};

package/dist/usage.d.ts

@@ -0,0 +1,44 @@
+import type { Answered, Located } from './collect.js';
+import type { Published } from './manifest.js';
+import type { Usage } from './report.js';
+/** The element counts, before the stylesheets add theirs. */
+type Counted = Pick<Usage, 'axes' | 'composed' | 'slots' | 'tags'>;
+/** The elements in the page now, counted once each. */
+export declare const walk: (from: Document) => Counted;
+/**
+ * The counts for the tags a manifest lists, and the rest apart as `unlisted`.
+ *
+ * Counted by prefix, since `watch()` runs before any manifest is at hand, and
+ * sorted here, where one is.
+ */
+export declare const listed: (counted: Counted, tags: Map<string, Published>) => Counted & Pick<Usage, 'unlisted'>;
+/** A running count of what renders, from `watch()`. */
+export interface Watcher {
+    /** The counts so far. A copy: counting goes on after it is read. */
+    counts(): Pick<Usage, 'axes' | 'composed' | 'slots' | 'tags'>;
+    /** Stops counting, and gives the slot back to whatever held it before. */
+    stop(): void;
+}
+/**
+ * Starts counting the Helix elements that render, from now on, and the ones
+ * already in the page.
+ *
+ * Hand the watcher to `diagnose`, and its report counts every element seen
+ * since, including the ones that have gone. Without one, `diagnose` counts the
+ * elements in the page at the moment it runs, and says so.
+ *
+ * **Start it early**, before the components load where you can, so the
+ * elements an early route renders and removes are counted. The ones in the
+ * page when it starts are counted by walking the page once.
+ *
+ * Two watchers on one page both count: a second one keeps the first's
+ * listener and calls it too.
+ */
+export declare const watch: (from?: Document) => Watcher;
+/**
+ * The parts and hooks a page's stylesheets reach for, where the manifest or
+ * the element's own styles say they exist. A dead one is a finding and is not
+ * counted as use.
+ */
+export declare const styled: (rules: Located[], tags: Map<string, Published>, answered: Answered) => Pick<Usage, 'hooks' | 'parts'>;
+export {};

package/dist/usage.js

@@ -0,0 +1,131 @@
+import { parts, targets } from './analyze.js';
+const SLOT = Symbol.for('fusion.dev/helix/usage');
+const AXES = ['emphasis', 'material', 'separation', 'tone'];
+const bump = (into, key, by = 1) => {
+    into[key] = (into[key] ?? 0) + by;
+};
+const under = (into, key, make) => {
+    let found = into[key];
+    if (found === undefined) {
+        found = make();
+        into[key] = found;
+    }
+    return found;
+};
+const empty = () => ({ axes: {}, composed: {}, slots: {}, tags: {} });
+const tally = (counted, element) => {
+    const tag = element.localName;
+    if (!tag.startsWith('helix-')) {
+        return;
+    }
+    const root = element.getRootNode();
+    const host = root instanceof ShadowRoot ? root.host.localName : '';
+    if (host.startsWith('helix-')) {
+        bump(counted.composed, tag);
+        return;
+    }
+    bump(counted.tags, tag);
+    for (const axis of AXES) {
+        const value = element.getAttribute(axis);
+        if (value !== null && value !== '') {
+            bump(under(under(counted.axes, tag, () => ({})), axis, () => ({})), value);
+        }
+    }
+    for (const child of element.children) {
+        const name = child.getAttribute('slot');
+        if (name) {
+            bump(under(counted.slots, tag, () => ({})), name);
+        }
+    }
+};
+const everyElement = (from, visit, depth = 0) => {
+    if (depth > 32) {
+        return;
+    }
+    for (const element of from.querySelectorAll('*')) {
+        visit(element);
+        if (element.shadowRoot) {
+            everyElement(element.shadowRoot, visit, depth + 1);
+        }
+    }
+};
+export const walk = (from) => {
+    const counted = empty();
+    everyElement(from, (element) => tally(counted, element));
+    return counted;
+};
+export const listed = (counted, tags) => {
+    const keep = (counts) => Object.fromEntries(Object.entries(counts).filter(([tag]) => tags.has(tag)));
+    const unlisted = {};
+    for (const counts of [counted.tags, counted.composed]) {
+        for (const [tag, count] of Object.entries(counts)) {
+            if (!tags.has(tag)) {
+                bump(unlisted, tag, count);
+            }
+        }
+    }
+    return {
+        axes: keep(counted.axes),
+        composed: keep(counted.composed),
+        slots: keep(counted.slots),
+        tags: keep(counted.tags),
+        unlisted,
+    };
+};
+export const watch = (from = document) => {
+    const counted = empty();
+    const seen = new WeakSet();
+    const see = (element) => {
+        if (!seen.has(element)) {
+            seen.add(element);
+            tally(counted, element);
+        }
+    };
+    const store = globalThis;
+    const before = store[SLOT];
+    let live = true;
+    const listener = (element) => {
+        if (live) {
+            see(element);
+        }
+        if (typeof before === 'function') {
+            before(element);
+        }
+    };
+    store[SLOT] = listener;
+    everyElement(from, see);
+    return {
+        counts: () => structuredClone(counted),
+        stop: () => {
+            live = false;
+            if (store[SLOT] === listener) {
+                store[SLOT] = before;
+            }
+        },
+    };
+};
+export const styled = (rules, tags, answered) => {
+    const counted = { hooks: {}, parts: {} };
+    for (const located of rules) {
+        const selector = located.rule.selectorText;
+        if (!selector?.includes('helix-')) {
+            continue;
+        }
+        for (const { names, tag } of parts(selector)) {
+            for (const name of names) {
+                if (tags.get(tag)?.parts.has(name)) {
+                    bump(under(counted.parts, tag, () => ({})), name);
+                }
+            }
+        }
+        for (const tag of targets(selector)) {
+            for (const property of Array.from(located.rule.style ?? [])) {
+                if (property.startsWith('--') &&
+                    (tags.get(tag)?.hooks.has(property) || answered.get(tag)?.has(property))) {
+                    bump(under(counted.hooks, tag, () => ({})), property);
+                }
+            }
+        }
+    }
+    return counted;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-diagnostics",
   "description": "Finds the Helix mistakes that are valid CSS: dead parts, misnamed hooks, two copies of the library.",
-  "version": "0.135.0",
+  "version": "0.136.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -29,7 +29,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.135.0",
+    "@fusion.dev/helix-testing": "0.136.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",