@fusion.dev/helix-diagnostics 0.136.0 → 0.138.0

package/README.md

@@ -43,21 +43,36 @@ diagnostic cannot drift from what is true.
 
 ## What a report holds
 
+A report is one run, in one shape for every sink, versioned by `schema`:
+
+- **`run`**: a new `id`, when it began (`at`), how long it took, where it ran
+  (`environment`, as you declare it), and the `page`, as a pattern by default:
+  `/orders/1042` reads `/orders/:id`.
+- **`project`**: the name and tags your configuration gives. The key is never
+  written into a report.
+- **`versions`**: the collector's and the rules', the Helix versions loaded on
+  the page (two means two copies), and the version each manifest describes.
 - **`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.
+- **`findings`**: each with its kind, a severity, the place that set the
+  severity, the tag and its family, a `category` (`styling`, `markup`,
+  `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.
 - **`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`.
+  hooks your stylesheets use, with the values the hooks are set to. 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`.
+- **`configuration`**: the settings the run was made under, each override in
+  effect, and how many findings each override turned off, by kind.
+- **`withheld`**: the categories your configuration turned off for sending,
+  and which place turned each off.
 
 ## What the console shows
 
@@ -80,37 +95,100 @@ 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 |
 
-## Change a severity
+**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.
 
-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:
+**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
+
+Every setting can be given in three places, and a later place wins, field by
+field: the defaults this package ships, your project's file, and the call.
+The page cannot read files, so import your file and pass it as `file`:
 
 ```js
-import overrides from './helix-diagnostics.json' with { type: 'json' }
+import project from './helix-diagnostics.json' with { type: 'json' }
 
 diagnose({
-  file: overrides,
-  rules: {
-    'dead-hook': { severity: 'warn', tags: ['helix-card'] },
-    'unforwarded-part': 'off',
-  },
+  environment: 'development',
+  file: project,
+  rules: { 'unforwarded-part': 'off' },
   tiers,
 })
 ```
 
-An override for a kind that does not exist throws, and names the closest kind.
+```json
+{
+  "project": { "name": "storefront", "tags": ["web"] },
+  "rules": { "dead-hook": { "severity": "warn", "tags": ["helix-card"] } },
+  "console": { "findings": "warn", "usage": "off" },
+  "send": { "performance": false },
+  "detail": { "evidence": "full", "hookValues": true, "pages": "patterns" },
+  "environments": { "development": true, "ci": true, "production": false }
+}
+```
+
+| Setting | Takes | Default |
+| --- | --- | --- |
+| `rules.<kind>` | `error`, `warn`, `info`, `off`, or `{ severity, tags }` | see Finding kinds |
+| `console.findings` | `error`, `warn`, `info`, or `off`: the lowest severity printed | `info` |
+| `console.coverage` | `info` or `off` | `info` |
+| `console.usage` | `debug` or `off` | `debug` |
+| `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` |
+| `detail.pages` | `patterns`, `full` (the path, never the query), or `none` | `patterns` |
+| `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.
 
 Development only. It walks every stylesheet in the page, and it sends nothing
 anywhere.
 
+## 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
+```
+
+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
+
+`@fusion.dev/helix-core` lists its version on the page as it loads, and every
+manifest built from 0.137 names the package and version it describes. Where
+both sides say, a manifest from another version is one `manifest-skew`
+finding in place of all others. Where either is silent, the check falls back
+to a part rendering that the manifest does not list.
+
 [Documentation](https://fusion.dev/helix)
 
 MIT

package/dist/analyze.d.ts

@@ -16,7 +16,7 @@
  * 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 { Raw } from './report.js';
 /** Every `helix-*` tag a selector mentions, in source order. */
@@ -33,7 +33,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.
@@ -68,3 +68,20 @@ export declare const registrations: (from?: Document, known?: () => string[]) =>
  * 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[];
+/**
+ * A manifest from another version, read from the numbers where both sides
+ * have one: the version a manifest describes, against the versions of core
+ * loaded on the page. Definite where `skew` above infers, and the check
+ * `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) => Raw[];

package/dist/analyze.js

@@ -1,7 +1,7 @@
 import { nearest } from './manifest.js';
 export const targets = (selector) => {
     const found = new Set();
-    for (const match of selector.matchAll(/\bhelix-[a-z0-9]+(?:-[a-z0-9]+)*/g)) {
+    for (const match of selector.matchAll(/(?<![\w.#-])helix-[a-z0-9]+(?:-[a-z0-9]+)*/g)) {
         found.add(match[0]);
     }
     return [...found];
@@ -16,38 +16,159 @@ export const parts = (selector) => {
     }
     return found;
 };
-const reaches = (host, wanted, depth = 0) => {
+const matchable = (selector) => {
+    if (selector.includes(':host')) {
+        return null;
+    }
+    const plain = selector
+        .replace(/::[\w-]+(\([^)]*\))?/g, '')
+        .replace(/:(focus-visible|focus-within|hover|focus|active|visited|target)(?![\w-])/g, '')
+        .trim();
+    return plain === '' ? null : plain;
+};
+const answersAt = (node, property, answering, readers) => {
+    if (answering.has(node.localName)) {
+        return true;
+    }
+    for (const { scope, selector } of readers.get(property) ?? []) {
+        if (scope !== undefined && node.getRootNode() !== scope) {
+            continue;
+        }
+        const plain = matchable(selector);
+        try {
+            if (plain !== null && node.matches(plain)) {
+                return true;
+            }
+        }
+        catch {
+        }
+    }
+    return false;
+};
+const reachesAnswer = (host, property, answering, readers, depth = 0) => {
     if (depth > 16) {
         return false;
     }
     for (const node of [host, ...host.querySelectorAll('*')]) {
-        if (node !== host && wanted.has(node.localName)) {
+        if (answersAt(node, property, answering, readers)) {
             return true;
         }
-        const root = node.shadowRoot;
-        if (root) {
-            for (const child of root.children) {
-                if (wanted.has(child.localName) || reaches(child, wanted, depth + 1)) {
-                    return true;
-                }
+        for (const child of node.shadowRoot?.children ?? []) {
+            if (reachesAnswer(child, property, answering, readers, depth + 1)) {
+                return true;
             }
         }
     }
     return false;
 };
+const loose = (located, answerers, from, used, onPage, listedBy, readers) => {
+    const findings = [];
+    if (located.scope instanceof ShadowRoot && located.scope.host.localName.startsWith('helix-')) {
+        return findings;
+    }
+    const selector = located.rule.selectorText;
+    for (const property of Array.from(located.rule.style ?? [])) {
+        if (!property.startsWith('--') ||
+            property.startsWith('--helix-') ||
+            property.startsWith('--_')) {
+            continue;
+        }
+        const answering = answerers.get(property);
+        if (!answering) {
+            if (used.has(property)) {
+                continue;
+            }
+            const suggestion = nearest(property, answerers.keys(), HOOK_DISTANCE);
+            if (!suggestion) {
+                continue;
+            }
+            const tag = [...(listedBy.get(suggestion) ?? answerers.get(suggestion) ?? [])].sort()[0] ?? '';
+            findings.push({
+                expected: suggestion,
+                kind: 'dead-hook',
+                message: `\`${selector}\` sets \`${property}\`, which no Helix element answers and nothing on the page reads. \`${suggestion}\` is a hook \`${tag}\` answers, two edits or fewer away, and almost certainly what was meant.`,
+                origin: origin(located),
+                subject: `${selector} { ${property} }`,
+                tag,
+            });
+            continue;
+        }
+        const scope = located.scope ?? from;
+        const plain = matchable(selector);
+        if (!scope || !from?.documentElement || plain === null) {
+            continue;
+        }
+        let matched;
+        try {
+            matched = [...scope.querySelectorAll(plain)];
+        }
+        catch {
+            continue;
+        }
+        if (matched.length === 0 || !onPage(property, answering)) {
+            continue;
+        }
+        if (matched.some((host) => reachesAnswer(host, property, answering, readers))) {
+            continue;
+        }
+        const tags = [...answering].sort();
+        findings.push({
+            kind: 'dead-hook',
+            message: `\`${selector}\` sets \`${property}\`, and nothing under the ${matched.length === 1 ? 'element' : `${matched.length} elements`} it matches answers it, though something elsewhere on this page does. ${tags
+                .slice(0, 3)
+                .map((one) => `\`${one}\``)
+                .join(', ')} ${tags.length === 1 ? 'answers' : 'answer'} it. It targets the wrong element, or expects a descendant that is not there.`,
+            origin: origin(located),
+            subject: `${selector} { ${property} }`,
+            tag: tags[0] ?? '',
+        });
+    }
+    return findings;
+};
 const origin = (located) => ({
     cssText: located.rule.cssText,
     index: located.index,
     sheet: located.sheet,
 });
-export const analyze = (rules, tags, from, answered = new Map()) => {
+export const analyze = (rules, tags, from, answered = new Map(), used = new Set(), readers = new Map()) => {
     const findings = [];
+    const answeredBy = new Map();
+    const answers = (property, tag) => {
+        const set = answeredBy.get(property) ?? new Set();
+        set.add(tag);
+        answeredBy.set(property, set);
+    };
+    const listedBy = new Map();
+    for (const [tag, element] of tags) {
+        for (const property of element.hooks.keys()) {
+            answers(property, tag);
+            listedBy.set(property, new Set([...(listedBy.get(property) ?? []), tag]));
+        }
+    }
+    for (const [tag, reads] of answered) {
+        for (const property of reads) {
+            if (tags.has(tag)) {
+                answers(property, tag);
+            }
+        }
+    }
+    const present = new Map();
+    const onPage = (property, answering) => {
+        let found = present.get(property);
+        if (found === undefined) {
+            found = from?.documentElement
+                ? reachesAnswer(from.documentElement, property, answering, readers)
+                : false;
+            present.set(property, found);
+        }
+        return found;
+    };
     for (const located of rules) {
         const selector = located.rule.selectorText;
-        if (!selector?.includes('helix-')) {
+        if (!selector) {
             continue;
         }
-        for (const { names, tag } of parts(selector)) {
+        for (const { names, tag } of selector.includes('helix-') ? parts(selector) : []) {
             const element = tags.get(tag);
             if (!element) {
                 findings.push({
@@ -92,6 +213,7 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
         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));
             continue;
         }
         for (const property of Array.from(located.rule.style ?? [])) {
@@ -106,22 +228,27 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
             }
             const answerers = new Set([...tags].filter(([, element]) => element.hooks.has(property)).map(([tag]) => tag));
             const candidates = known.flatMap(([, element]) => [...(element?.hooks.keys() ?? [])]);
-            const suggestion = nearest(property, candidates);
-            if (answerers.size === 0 && !suggestion) {
+            const suggestion = nearest(property, candidates, HOOK_DISTANCE);
+            if ((answerers.size === 0 && !suggestion) || (answerers.size === 0 && used.has(property))) {
                 continue;
             }
             if (answerers.size > 0 && !suggestion) {
                 if (!from) {
                     continue;
                 }
-                let inherits = false;
-                for (const host of from.querySelectorAll(selector.replaceAll(/::part\([^)]*\)/g, ''))) {
-                    if (reaches(host, answerers)) {
-                        inherits = true;
-                        break;
-                    }
+                const plain = matchable(selector);
+                if (plain === null) {
+                    continue;
+                }
+                let matched;
+                try {
+                    matched = [...(located.scope ?? from).querySelectorAll(plain)];
                 }
-                if (inherits) {
+                catch {
+                    continue;
+                }
+                if (matched.length === 0 ||
+                    matched.some((host) => reachesAnswer(host, property, answeredBy.get(property) ?? answerers, readers))) {
                     continue;
                 }
             }
@@ -130,7 +257,7 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
                 expected: suggestion,
                 kind: 'dead-hook',
                 message: suggestion
-                    ? `\`${tag}\` does not answer \`${property}\`. It answers \`${suggestion}\`, which is one character class away and is almost certainly what was meant.`
+                    ? `\`${tag}\` does not answer \`${property}\`. It answers \`${suggestion}\`, two edits or fewer away, which is almost certainly what was meant.`
                     : `\`${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} }`,
@@ -207,3 +334,114 @@ export const skew = (tags, from) => {
     visit(from, 0);
     return findings;
 };
+export const versionSkew = (manifests, seen) => seen.length === 0
+    ? []
+    : Object.entries(manifests)
+        .filter(([, version]) => !seen.includes(version))
+        .map(([name, version]) => ({
+        kind: 'manifest-skew',
+        message: `The manifest passed in for \`${name}\` describes ${version}, and the page runs Helix ${seen.join(' and ')}. Every other finding would be judged against the wrong version, so none are reported. Pass the \`custom-elements.json\` from the installed packages.`,
+        subject: `${name}@${version}`,
+        tag: '',
+    }));
+const GLOBAL = new Set([
+    'accesskey',
+    'autocapitalize',
+    'autofocus',
+    'class',
+    'contenteditable',
+    'defer-hydration',
+    'dir',
+    'draggable',
+    'enterkeyhint',
+    'exportparts',
+    'hidden',
+    'id',
+    'inert',
+    'inputmode',
+    'is',
+    'itemid',
+    'itemprop',
+    'itemref',
+    'itemscope',
+    'itemtype',
+    'lang',
+    'nonce',
+    'part',
+    'popover',
+    'role',
+    'slot',
+    'spellcheck',
+    'style',
+    'tabindex',
+    'title',
+    'translate',
+    'writingsuggestions',
+]);
+const PREFIXES = ['aria-', 'data-', 'on', '_ngcontent-', '_nghost-', 'ng-', 'v-', 'x-', ':', '@'];
+const HOOK_DISTANCE = 2;
+export const markup = (tags, 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,
+                        };
+                    }
+                    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 });
+                        }
+                    }
+                }
+            }
+            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.d.ts

@@ -0,0 +1,18 @@
+import type { Report, Severity } from './report.js';
+/** What the CI sink writes, and what fails the job. */
+export interface CiOptions {
+    /** Where the runs are written, as JSON. */
+    file: string;
+    /** The lowest severity that fails the job, or `never`. `error` by default. */
+    failOn?: Severity | 'never';
+}
+/**
+ * Writes the runs, and says what failed.
+ *
+ * Returns the exit code the job should end with and the summary to print;
+ * the caller prints and exits, so a script can add its own lines first.
+ */
+export declare const ciSink: (runs: Report[], { file, failOn }: CiOptions) => {
+    code: 0 | 1;
+    summary: string;
+};

package/dist/ci.js

@@ -0,0 +1,30 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const RANK = { error: 3, info: 1, warn: 2 };
+const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+export const ciSink = (runs, { file, failOn = 'error' }) => {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ runs, schema: 1 }, null, 2)}\n`);
+    const faults = new Map();
+    for (const run of runs) {
+        for (const finding of run.findings) {
+            const fault = faults.get(finding.fingerprint) ?? { finding, pages: new Set() };
+            fault.pages.add(run.run.page ?? '(no page)');
+            faults.set(finding.fingerprint, fault);
+        }
+    }
+    const all = [...faults.values()];
+    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 lines = [
+        `helix diagnostics: ${counted(runs.length, 'run')}, ${counted(of('error'), 'error')}, ${counted(of('warn'), 'warning')}, ${of('info')} info` +
+            (unread > 0 ? `, ${counted(unread, 'unreadable stylesheet')}` : '') +
+            `. Written to ${file}.`,
+    ];
+    for (const { finding, pages } of failing) {
+        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` : ''}`);
+    }
+    return { code: failing.length > 0 ? 1 : 0, summary: lines.join('\n') };
+};

package/dist/collect.d.ts

@@ -20,6 +20,11 @@ import type { Coverage } from './report.js';
 export interface Located {
     index: number;
     rule: CSSStyleRule;
+    /**
+     * Where the rule's selector matches: the document for a page's own sheet,
+     * and the shadow root of the first host to adopt it for a component's.
+     */
+    scope?: Document | ShadowRoot | undefined;
     sheet: string;
 }
 /**
@@ -40,6 +45,17 @@ export interface Located {
  * the whole truth.
  */
 export type Answered = Map<string, Set<string>>;
+/**
+ * The rules outside Helix's components that read each custom property with
+ * `var()`, by selector and the root they apply in. An element one of them
+ * matches answers the property as surely as a Helix tag does: Helix's own
+ * base sheet reads every button hook for a plain `[data-button]` link, and an
+ * example reads `--chart-series-1` in its own `::part()` rules.
+ */
+export type Readers = Map<string, Array<{
+    scope: Document | ShadowRoot | undefined;
+    selector: string;
+}>>;
 /**
  * Every readable rule in the page, and what was missed getting them.
  *
@@ -54,5 +70,7 @@ export type Answered = Map<string, Set<string>>;
 export declare const collect: (from?: Document) => {
     answered: Answered;
     coverage: Coverage;
+    readers: Readers;
     rules: Located[];
+    used: Set<string>;
 };