@fusion.dev/helix-diagnostics 0.136.0 → 0.137.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
 
@@ -86,31 +101,63 @@ works on it:
 | `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
+## Configure it
 
-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:
+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.
 
+## 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

@@ -68,3 +68,10 @@ 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[];

package/dist/analyze.js

@@ -207,3 +207,13 @@ 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: '',
+    }));

package/dist/config.d.ts

@@ -0,0 +1,71 @@
+import { type Category, type Configuration, type Layer, type Report } from './report.js';
+import { type Rules } from './rules.js';
+/** Everything a project can set. Every field is optional; see `DEFAULTS`. */
+export interface Config {
+    /** The lowest level each category prints at in the console, or `off`. */
+    console?: Partial<Configuration['console']>;
+    /** How much detail goes with what is sent. */
+    detail?: Partial<Configuration['detail']>;
+    /** Where sending happens. Production takes `{ sample }`, from 0 to 1. */
+    environments?: Partial<Configuration['environments']>;
+    /**
+     * The project: its key, which opts it in to sending, and its own name and
+     * labels. `tags` are free, and `fusion` marks Fusion's own projects.
+     */
+    project?: {
+        key?: string;
+        name?: string;
+        tags?: string[];
+    };
+    /** Severities by kind; see `Rules`. */
+    rules?: Rules;
+    /** Each category, sent or withheld. Nothing is sent without a key. */
+    send?: Partial<Record<Category, boolean>>;
+}
+/** The shipped defaults. */
+export declare const DEFAULTS: {
+    readonly console: {
+        readonly coverage: 'info';
+        readonly findings: 'info';
+        readonly usage: 'debug';
+    };
+    readonly detail: {
+        readonly evidence: 'full';
+        readonly hookValues: true;
+        readonly pages: 'patterns';
+    };
+    readonly environments: {
+        readonly ci: true;
+        readonly development: true;
+        readonly production: false;
+    };
+    readonly send: {
+        readonly assist: true;
+        readonly configuration: true;
+        readonly coverage: true;
+        readonly findings: true;
+        readonly performance: false;
+        readonly runtime: true;
+        readonly usage: true;
+    };
+};
+/** Throws on a setting that names nothing, or a value it cannot take. */
+export declare const checkConfig: (config: Config | undefined, layer: Exclude<Layer, 'shipped'>) => void;
+/** The settings in effect, from the defaults, the file, and the call. */
+export interface Resolved {
+    configuration: Omit<Configuration, 'overrides' | 'silenced'>;
+    project: Report['project'];
+    /** Each category's sending, and which place decided it. */
+    send: Record<Category, {
+        decidedBy: Layer;
+        on: boolean;
+    }>;
+}
+/** The three places, merged, with a later one winning field by field. */
+export declare const resolveConfig: (file: Config | undefined, call: Config | undefined) => Resolved;
+/**
+ * A page's path as a pattern: each segment that names one record, a number,
+ * a UUID, or a long run of hex or mixed letters and digits, becomes `:id`.
+ * `/orders/1042/items/9f8e7d6c5b4a` reads `/orders/:id/items/:id`.
+ */
+export declare const pagePattern: (path: string) => string;

package/dist/config.js

@@ -0,0 +1,126 @@
+import { nearest } from './manifest.js';
+import { CATEGORIES } from './report.js';
+import { checkRules } from './rules.js';
+export const DEFAULTS = {
+    console: { coverage: 'info', findings: 'info', usage: 'debug' },
+    detail: { evidence: 'full', hookValues: true, pages: 'patterns' },
+    environments: { ci: true, development: true, production: false },
+    send: {
+        assist: true,
+        configuration: true,
+        coverage: true,
+        findings: true,
+        performance: false,
+        runtime: true,
+        usage: true,
+    },
+};
+const ALLOWED = {
+    console: {
+        coverage: ['info', 'off'],
+        findings: ['error', 'warn', 'info', 'off'],
+        usage: ['debug', 'off'],
+    },
+    detail: {
+        evidence: ['full', 'selector', 'none'],
+        hookValues: [true, false],
+        pages: ['patterns', 'full', 'none'],
+    },
+    environments: { ci: [true, false], development: [true, false], production: 'sample' },
+    project: { key: 'string', name: 'string', tags: 'tags' },
+    send: Object.fromEntries(CATEGORIES.map((category) => [category, [true, false]])),
+};
+const shown = (value) => typeof value === 'string' ? `\`${value}\`` : String(value);
+export const checkConfig = (config, layer) => {
+    if (config === undefined) {
+        return;
+    }
+    if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+        throw new Error(`The ${layer} is not a configuration object.`);
+    }
+    for (const [section, value] of Object.entries(config)) {
+        if (section === 'rules') {
+            checkRules(value, layer);
+            continue;
+        }
+        const allowed = ALLOWED[section];
+        if (!allowed) {
+            const close = nearest(section, [...Object.keys(ALLOWED), 'rules']);
+            throw new Error(`The ${layer} sets \`${section}\`, which is no setting.` +
+                (close ? ` The closest is \`${close}\`.` : ''));
+        }
+        for (const [name, one] of Object.entries(value)) {
+            const takes = allowed[name];
+            if (takes === undefined) {
+                const close = nearest(name, Object.keys(allowed));
+                throw new Error(`The ${layer} sets \`${section}.${name}\`, which is no setting.` +
+                    (close ? ` The closest is \`${section}.${close}\`.` : ''));
+            }
+            const fits = takes === 'string'
+                ? typeof one === 'string'
+                : takes === 'tags'
+                    ? Array.isArray(one) && one.every((tag) => typeof tag === 'string')
+                    : takes === 'sample'
+                        ? one === false ||
+                            (typeof one === 'object' &&
+                                one !== null &&
+                                typeof one.sample === 'number' &&
+                                one.sample >= 0 &&
+                                one.sample <= 1)
+                        : takes.includes(one);
+            if (!fits) {
+                const expected = takes === 'string'
+                    ? 'a string'
+                    : takes === 'tags'
+                        ? 'a list of strings'
+                        : takes === 'sample'
+                            ? '`false`, or `{ sample }` from 0 to 1'
+                            : takes.map(shown).join(', ');
+                throw new Error(`The ${layer} sets \`${section}.${name}\` to \`${JSON.stringify(one)}\`. It takes ${expected}.`);
+            }
+        }
+    }
+};
+export const resolveConfig = (file, call) => {
+    checkConfig(file, 'file');
+    checkConfig(call, 'argument');
+    const merged = (section, base) => ({
+        ...base,
+        ...(file?.[section] ?? {}),
+        ...(call?.[section] ?? {}),
+    });
+    const send = Object.fromEntries(CATEGORIES.map((category) => {
+        const fromCall = call?.send?.[category];
+        const fromFile = file?.send?.[category];
+        return [
+            category,
+            fromCall !== undefined
+                ? { decidedBy: 'argument', on: fromCall }
+                : fromFile !== undefined
+                    ? { decidedBy: 'file', on: fromFile }
+                    : { decidedBy: 'shipped', on: DEFAULTS.send[category] },
+        ];
+    }));
+    const project = { ...(file?.project ?? {}), ...(call?.project ?? {}) };
+    return {
+        configuration: {
+            console: merged('console', { ...DEFAULTS.console }),
+            detail: merged('detail', { ...DEFAULTS.detail }),
+            environments: merged('environments', { ...DEFAULTS.environments }),
+        },
+        project: {
+            ...(project.name === undefined ? {} : { name: project.name }),
+            tags: project.tags ?? [],
+        },
+        send,
+    };
+};
+export const pagePattern = (path) => path
+    .split('/')
+    .map((segment) => /^\d+$/.test(segment) ||
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(segment) ||
+    /^[0-9a-f]{8,}$/i.test(segment) ||
+    (segment.length >= 12 && /\d/.test(segment) && /^[A-Za-z0-9_-]+$/.test(segment))
+    ? ':id'
+    : segment)
+    .join('/');

package/dist/console.d.ts

@@ -27,5 +27,12 @@
 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. */
+/**
+ * Writes a report and hands it back, so a caller can chain a second sink.
+ *
+ * **Each category prints as the project's `console` setting says**: findings
+ * at or above a severity, coverage and usage on or off. The heading counts
+ * every finding whatever is printed under it, and the ones the rules turned
+ * off, so a quiet console never reads as a clean page.
+ */
 export declare const report: (result: Report, to?: ConsoleSink) => Report;

package/dist/console.js

@@ -7,41 +7,63 @@ const entry = (finding) => {
     return lines.join('\n');
 };
 const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+const RANK = { error: 3, info: 1, warn: 2 };
 export const report = (result, to = console) => {
-    const { coverage, findings } = result;
+    const { configuration, coverage, findings } = result;
+    const levels = configuration.console;
     const bySeverity = (severity) => findings.filter((finding) => finding.severity === severity).length;
     const errors = bySeverity('error');
     const warnings = bySeverity('warn');
+    const off = configuration.silenced.reduce((total, one) => total + one.count, 0);
     const missed = coverage.sheets - coverage.read;
-    const heading = findings.length === 0
+    const counts = [
+        counted(errors, 'error'),
+        counted(warnings, 'warning'),
+        `${bySeverity('info')} info`,
+        ...(off > 0 ? [`${off} turned off`] : []),
+    ];
+    const heading = findings.length === 0 && off === 0
         ? 'helix diagnostics: no findings'
-        : `helix diagnostics: ${counted(errors, 'error')}, ${counted(warnings, 'warning')}, ${bySeverity('info')} info`;
+        : `helix diagnostics: ${counts.join(', ')}`;
     if (errors + warnings > 0 || missed > 0) {
         to.group(heading);
     }
     else {
         to.groupCollapsed(heading);
     }
-    to.info(`read ${coverage.read} of ${counted(coverage.sheets, 'stylesheet')} across ${counted(coverage.roots, 'shadow root')}`);
+    if (levels.coverage !== 'off') {
+        to.info(`read ${coverage.read} of ${counted(coverage.sheets, 'stylesheet')} across ${counted(coverage.roots, 'shadow root')}` +
+            (result.run.page ? ` on ${result.run.page}` : ''));
+    }
     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`);
+    if (off > 0 && levels.coverage !== 'off') {
+        to.info(configuration.silenced
+            .map((one) => `${counted(one.count, one.kind)} turned off by the ${one.layer}`)
+            .join('\n'));
+    }
+    if (levels.findings !== 'off') {
+        const floor = RANK[levels.findings];
+        for (const finding of findings) {
+            if (RANK[finding.severity] >= floor) {
+                to[finding.severity](entry(finding));
+            }
+        }
     }
-    for (const finding of findings) {
-        to[finding.severity](entry(finding));
+    if (levels.usage !== 'off') {
+        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;
+        const versions = result.versions.helix;
+        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` : '') +
+            (versions.length > 0 ? `; Helix ${versions.join(' and ')}` : ''));
     }
-    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/identity.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What a finding is about, who fixes it, and which finding it is from one run
+ * to the next.
+ *
+ * **The fingerprint is what turns findings into issues.** Without it, a
+ * dashboard can count findings per run and cannot say whether the one in this
+ * run is the one from last week, fixed, or back again.
+ */
+import type { Published } from './manifest.js';
+import type { Identified, Raw } from './report.js';
+/**
+ * A selector with what a build changes taken out, so the same rule in the
+ * next build reads the same.
+ *
+ * **Hashed class names**, which CSS Modules write and every bundler hashes its
+ * own way:
+ *
+ * - Next.js: `trace-graph-module__lFhy0q__traceFrame`, to `trace-graph-module__traceFrame`.
+ * - webpack's default: `card__title___3xYz1`, to `card__title`.
+ * - Vite's default: `_title_1a2b3_7`, to `_title`.
+ *
+ * webpack's is taken out first: its `___` would otherwise read as the end of
+ * a Next.js hash. And spacing, which a minifier rewrites.
+ */
+export declare const normalize: (subject: string) => string;
+/**
+ * A finding's identity across runs: its kind, its tag, and its normalized
+ * subject. **The stylesheet is left out**, since a bundler puts a content
+ * hash in a file's name, so the same mistake in two stylesheets is one issue
+ * seen twice, which is how a reader thinks of it.
+ */
+export declare const fingerprintOf: (finding: Pick<Raw, 'kind' | 'subject' | 'tag'>) => string;
+/** A finding with its category, owner, family, and fingerprint. */
+export declare const identify: (finding: Raw, tags: Map<string, Published>) => Identified;

package/dist/identity.js

@@ -0,0 +1,42 @@
+const CATEGORY = {
+    'dead-hook': 'styling',
+    'dead-part': 'styling',
+    'duplicate-registration': 'integrity',
+    'manifest-skew': 'integrity',
+    'unforwarded-part': 'styling',
+    'unknown-tag': 'integrity',
+};
+const OWNER = {
+    'dead-hook': 'consumer',
+    'dead-part': 'consumer',
+    'duplicate-registration': 'consumer',
+    'manifest-skew': 'consumer',
+    'unforwarded-part': 'helix',
+    'unknown-tag': 'consumer',
+};
+export const normalize = (subject) => subject
+    .replace(/___[A-Za-z0-9_-]{5}\b/g, '')
+    .replace(/__[A-Za-z0-9_-]{6}__/g, '__')
+    .replace(/\b(_[A-Za-z][A-Za-z0-9-]*)_[a-z0-9]{5}_\d+\b/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+const hash = (text) => {
+    let one = 0xdeadbeef;
+    let two = 0x41c6ce57;
+    for (let at = 0; at < text.length; at += 1) {
+        const code = text.charCodeAt(at);
+        one = Math.imul(one ^ code, 2654435761);
+        two = Math.imul(two ^ code, 1597334677);
+    }
+    one = Math.imul(one ^ (one >>> 16), 2246822507) ^ Math.imul(two ^ (two >>> 13), 3266489909);
+    two = Math.imul(two ^ (two >>> 16), 2246822507) ^ Math.imul(one ^ (one >>> 13), 3266489909);
+    return (4294967296 * (2097151 & two) + (one >>> 0)).toString(16).padStart(14, '0');
+};
+export const fingerprintOf = (finding) => hash(`${finding.kind}\u0000${finding.tag}\u0000${normalize(finding.subject)}`);
+export const identify = (finding, tags) => ({
+    ...finding,
+    category: CATEGORY[finding.kind],
+    family: tags.get(finding.tag)?.family,
+    fingerprint: fingerprintOf(finding),
+    owner: OWNER[finding.kind],
+});

package/dist/index.d.ts

@@ -28,19 +28,25 @@
  * stylesheet in the page and has no business in a production bundle.
  */
 export { collect } from './collect.js';
+export { type Config, DEFAULTS, pagePattern } from './config.js';
 export { report } from './console.js';
+export { fingerprintOf, normalize } from './identity.js';
 export type { ManifestSource, Published, Tier } from './manifest.js';
 export { index, nearest } from './manifest.js';
-export type { Coverage, Finding, Kind, Layer, Origin, Report, Severity, Unreadable, Usage, } from './report.js';
-export { KINDS } from './report.js';
+export type { Category, Configuration, Coverage, Environment, Finding, FindingCategory, Kind, Layer, Origin, Owner, Report, Severity, Unreadable, Usage, } from './report.js';
+export { CATEGORIES, KINDS } from './report.js';
 export { type Override, type Rules, SHIPPED_RULES } from './rules.js';
 export { type Watcher, watch } from './usage.js';
+export { VERSION } from './version.js';
+import { type Config } from './config.js';
 import type { Tier } from './manifest.js';
-import type { Report } from './report.js';
-import { type Rules } from './rules.js';
+import type { Environment, Report } from './report.js';
 import { type Watcher } from './usage.js';
-/** What to look at, and what to compare it against. */
-export interface Options {
+/**
+ * What to look at, what to compare it against, and the settings for this
+ * call, which win over the project's file field by field.
+ */
+export interface Options extends Config {
     /**
      * `duplicateRegistrations` from `@fusion.dev/helix-core`, when it is installed.
      *
@@ -53,10 +59,16 @@ export interface Options {
      */
     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.
+     * Where this run happens, as the project declares it. **Never inferred**:
+     * a bundler's `development` condition misfires both ways, and a run whose
+     * environment nobody declared is never sent.
      */
-    file?: Rules | undefined;
+    environment?: Environment | undefined;
+    /**
+     * The project's own file, `helix-diagnostics.json`, parsed. The build reads
+     * the file, since the page cannot: import the JSON and pass it here.
+     */
+    file?: Config | undefined;
     /**
      * The document to scan. Defaults to the ambient one.
      *
@@ -65,14 +77,11 @@ export interface Options {
      */
     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'] } } })
-     * ```
+     * The page's path, for a router that knows its own pattern, such as
+     * `/products/[id]`. Otherwise read from the location and made a pattern, as
+     * `detail.pages` says.
      */
-    rules?: Rules | undefined;
+    page?: string | undefined;
     /**
      * The manifests to check against, one per installed tier.
      *
@@ -88,7 +97,7 @@ export interface Options {
     watcher?: Watcher | undefined;
 }
 /**
- * One pass over the page.
+ * One run over the page.
  *
  * **It returns coverage and findings together and offers no way to have one
  * without the other.** A collector that cannot read cross-origin sheets reports
@@ -100,6 +109,7 @@ export interface Options {
  * 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`.
+ * so in place of every other: by version where both sides carry one, and
+ * otherwise by a part the manifest does not list rendering in the page.
  */
-export declare const diagnose: ({ duplicates, file, from, rules, tiers, watcher }: Options) => Report;
+export declare const diagnose: (options: Options) => Report;

package/dist/index.js

@@ -1,38 +1,81 @@
 export { collect } from './collect.js';
+export { DEFAULTS, pagePattern } from './config.js';
 export { report } from './console.js';
+export { fingerprintOf, normalize } from './identity.js';
 export { index, nearest } from './manifest.js';
-export { KINDS } from './report.js';
+export { CATEGORIES, KINDS } from './report.js';
 export { SHIPPED_RULES } from './rules.js';
 export { watch } from './usage.js';
-import { analyze, registrations, skew } from './analyze.js';
+export { VERSION } from './version.js';
+import { analyze, registrations, skew, versionSkew } from './analyze.js';
 import { collect } from './collect.js';
-import { index } from './manifest.js';
-import { applyRules, checkRules } from './rules.js';
-import { listed, styled, walk } from './usage.js';
-export const diagnose = ({ duplicates, file, from, rules, tiers, watcher }) => {
+import { pagePattern, resolveConfig } from './config.js';
+import { identify } from './identity.js';
+import { index, versionsOf } from './manifest.js';
+import { applyRules, overridesOf } from './rules.js';
+import { listed, loadedVersions, styled, walk } from './usage.js';
+import { VERSION } from './version.js';
+const runId = () => globalThis.crypto?.randomUUID?.() ??
+    `${Date.now().toString(16)}-${Math.random().toString(16).slice(2)}`;
+export const diagnose = (options) => {
+    const started = performance.now();
+    const at = new Date().toISOString();
+    const { duplicates, environment, file, from, page, tiers, watcher, ...call } = options;
     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 resolved = resolveConfig(file, call);
+    const { detail } = resolved.configuration;
     const document_ = from ?? globalThis.document;
     const { answered, coverage, rules: located } = collect(document_);
     const tags = index(tiers);
-    const skewed = applyRules(skew(tags, document_), file, rules);
+    const counted = watcher ? watcher.counts() : walk(document_);
+    const seen = loadedVersions();
+    const manifests = versionsOf(tiers);
+    const byVersion = versionSkew(manifests, seen);
+    const known = seen.length > 0 && Object.keys(manifests).length > 0;
+    const skewed = applyRules((byVersion.length > 0 ? byVersion : known ? [] : skew(tags, document_)).map((one) => identify(one, tags)), file?.rules, call.rules);
     const judged = skewed.findings.length > 0
-        ? { findings: [], silenced: { argument: 0, file: 0 } }
-        : applyRules([...analyze(located, tags, document_, answered), ...registrations(document_, duplicates)], file, rules);
+        ? { findings: [], silenced: [] }
+        : applyRules([
+            ...analyze(located, tags, document_, answered),
+            ...registrations(document_, duplicates),
+        ].map((one) => identify(one, tags)), file?.rules, call.rules);
+    const path = page ?? globalThis.location?.pathname;
+    const shownPage = path === undefined || detail.pages === 'none'
+        ? undefined
+        : detail.pages === 'patterns'
+            ? pagePattern(path)
+            : path;
     return {
+        configuration: {
+            ...resolved.configuration,
+            overrides: overridesOf(file?.rules, call.rules),
+            silenced: [...skewed.silenced, ...judged.silenced],
+        },
         coverage,
         findings: [...skewed.findings, ...judged.findings],
-        silenced: {
-            argument: skewed.silenced.argument + judged.silenced.argument,
-            file: skewed.silenced.file + judged.silenced.file,
+        project: resolved.project,
+        run: {
+            at,
+            duration: Math.round(performance.now() - started),
+            id: runId(),
+            source: 'page',
+            ...(environment === undefined ? {} : { environment }),
+            ...(shownPage === undefined ? {} : { page: shownPage }),
         },
+        schema: 1,
         usage: {
-            ...listed(watcher ? watcher.counts() : walk(document_), tags),
-            ...styled(located, tags, answered),
+            ...listed(counted, tags),
+            ...styled(located, tags, answered, detail.hookValues),
             counted: watcher ? 'watched' : 'walked',
         },
+        versions: { collector: VERSION, helix: seen, manifests, rules: VERSION },
+        withheld: Object.entries(resolved.send)
+            .filter(([, sent]) => !sent.on)
+            .map(([category, sent]) => ({
+            category: category,
+            decidedBy: sent.decidedBy,
+        })),
     };
 };

package/dist/manifest.d.ts

@@ -16,7 +16,18 @@
  */
 /** The subset of the manifest schema this reads. Nothing else is touched. */
 export interface ManifestSource {
+    /**
+     * The package and version the manifest describes, which `helix manifest
+     * build` writes from the package's `package.json`. Absent from a manifest
+     * built before 0.137.
+     */
+    helix?: {
+        package?: string;
+        version?: string;
+    };
     modules?: Array<{
+        /** Where the module is, which names the family: `src/button/root/button-root.ts`. */
+        path?: string;
         declarations?: Array<{
             cssParts?: Array<{
                 name: string;
@@ -41,6 +52,8 @@ export interface Tier {
  * scope, and `analyze.ts` needs both in the same file.
  */
 export interface Published {
+    /** The family, from the module's path: `button` for `src/button/root/button-root.ts`. */
+    family?: string | undefined;
     hooks: Map<string, Set<string>>;
     parts: Map<string, Set<string>>;
 }
@@ -52,6 +65,8 @@ export interface Published {
  * styled one did not forward it", and that sentence needs the names.
  */
 export declare const index: (tiers: Tier[]) => Map<string, Published>;
+/** The version each manifest describes, by package, where it says. */
+export declare const versionsOf: (tiers: Tier[]) => Record<string, string>;
 /**
  * The published name closest to a wrong one, or nothing when none is close.
  *

package/dist/manifest.js

@@ -2,6 +2,7 @@ export const index = (tiers) => {
     const tags = new Map();
     for (const tier of tiers) {
         for (const module of tier.manifest.modules ?? []) {
+            const family = /^src\/([^/]+)\//.exec(module.path ?? '')?.[1];
             for (const declaration of module.declarations ?? []) {
                 const tag = declaration.tagName;
                 if (!tag) {
@@ -9,7 +10,7 @@ export const index = (tiers) => {
                 }
                 let element = tags.get(tag);
                 if (!element) {
-                    element = { hooks: new Map(), parts: new Map() };
+                    element = { family, hooks: new Map(), parts: new Map() };
                     tags.set(tag, element);
                 }
                 for (const [field, into] of [
@@ -27,6 +28,16 @@ export const index = (tiers) => {
     }
     return tags;
 };
+export const versionsOf = (tiers) => {
+    const versions = {};
+    for (const tier of tiers) {
+        const version = tier.manifest.helix?.version;
+        if (version) {
+            versions[tier.manifest.helix?.package ?? tier.name] = version;
+        }
+    }
+    return versions;
+};
 export const nearest = (wrong, candidates) => {
     let best;
     let distance = Math.floor(wrong.length / 3);

package/dist/report.d.ts

@@ -38,6 +38,12 @@ export interface Origin {
  * rather than a finding.
  */
 export interface Finding {
+    /**
+     * What the fault is about: `styling` for parts and hooks, `markup` for
+     * attributes and slots, `integrity` for the page and the library
+     * disagreeing, `guideline` for advice. A dashboard groups by it.
+     */
+    category: FindingCategory;
     /**
      * What the collector believes the author meant, when it can tell.
      *
@@ -48,12 +54,25 @@ export interface Finding {
      * catch.
      */
     expected?: string | undefined;
+    /** The family the tag belongs to, from the manifest's module path. */
+    family?: string | undefined;
+    /**
+     * The finding's identity across runs: the same fault in the next run has
+     * the same fingerprint, which is what makes fixed and regressed computable.
+     * See `fingerprintOf`.
+     */
+    fingerprint: string;
     /** Machine-readable fault class, stable across versions. */
     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;
+    /**
+     * Who fixes it: `consumer`, the page's authors, or `helix`, the library,
+     * as for a part the styled tier never forwarded.
+     */
+    owner: Owner;
     /** How serious it is, after the shipped rules and any overrides. */
     severity: Severity;
     /**
@@ -75,8 +94,23 @@ export type Kind = (typeof KINDS)[number];
 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'>;
+/** What a fault is about. */
+export type FindingCategory = 'guideline' | 'integrity' | 'markup' | 'styling';
+/** Who fixes a fault. */
+export type Owner = 'consumer' | 'helix';
+/** A finding as a check first writes it. */
+export type Raw = Omit<Finding, 'category' | 'decidedBy' | 'family' | 'fingerprint' | 'owner' | 'severity'>;
+/** A finding with its identity, before the rules have given it a severity. */
+export type Identified = Omit<Finding, 'decidedBy' | 'severity'>;
+/**
+ * The kinds of telemetry a run can hold, each its own shape. A project turns
+ * each on or off for sending; see `Config.send`.
+ */
+export declare const CATEGORIES: readonly ['assist', 'configuration', 'coverage', 'findings', 'performance', 'runtime', 'usage'];
+/** A kind of telemetry. */
+export type Category = (typeof CATEGORIES)[number];
+/** Where a run was declared to happen. Undeclared is never sent. */
+export type Environment = 'ci' | 'development' | 'production';
 /** A sheet the collector could not read, and the reason. */
 export interface Unreadable {
     reason: 'cross-origin' | 'detached' | 'threw';
@@ -128,6 +162,13 @@ export interface Usage {
     counted: 'walked' | 'watched';
     /** Each hook the page's stylesheets set, by tag, counted per declaration. */
     hooks: Record<string, Record<string, number>>;
+    /**
+     * The values each hook is set to, by tag, hook, and value, where the
+     * project allows it (`detail.hookValues`). A hook set to one value across
+     * projects is a token Helix should have shipped. Values over 200
+     * characters are cut there.
+     */
+    hookValues: Record<string, 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. */
@@ -141,18 +182,99 @@ export interface Usage {
      */
     unlisted: Record<string, number>;
 }
-/** The whole result. Coverage and findings, never one without the other. */
+/** The settings a run was made under, and what they turned off. */
+export interface Configuration {
+    /** The lowest level each category prints at in the console, or `off`. */
+    console: {
+        coverage: 'info' | 'off';
+        findings: Severity | 'off';
+        usage: 'debug' | 'off';
+    };
+    /** How much detail goes with what is sent. */
+    detail: {
+        evidence: 'full' | 'none' | 'selector';
+        hookValues: boolean;
+        pages: 'full' | 'none' | 'patterns';
+    };
+    /** Where sending happens, and production's sample rate. */
+    environments: {
+        ci: boolean;
+        development: boolean;
+        production: false | {
+            sample: number;
+        };
+    };
+    /** Each override in effect, from the file or the call. */
+    overrides: Array<{
+        kind: Kind;
+        layer: Exclude<Layer, 'shipped'>;
+        severity: Severity | 'off';
+        tags?: string[];
+    }>;
+    /**
+     * How many findings each override turned off, by kind and layer. A finding
+     * turned off is still a fault, and a report that hid the count would read
+     * as cleaner than the page is.
+     */
+    silenced: Array<{
+        count: number;
+        kind: Kind;
+        layer: Exclude<Layer, 'shipped'>;
+    }>;
+}
+/**
+ * One run: what was found, what is used, how much could be seen, and the
+ * settings it was made under, with everything a dashboard needs to place it.
+ *
+ * **The same shape from every source and to every sink**, versioned by
+ * `schema`, so a run written by CI today is read by the dashboard next year.
+ */
 export interface Report {
+    /** The shape's version. Raised when a field changes meaning or goes. */
+    schema: 1;
+    configuration: Configuration;
     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.
+     * The project's own name and labels, as its configuration gives them. The
+     * key is never written into a report.
      */
-    silenced: {
-        argument: number;
-        file: number;
+    project: {
+        name?: string;
+        tags: string[];
+    };
+    run: {
+        /** When the run began, as an ISO 8601 time. */
+        at: string;
+        /** How long the run took, in milliseconds. */
+        duration: number;
+        /** Where it was declared to run. Absent where nobody declared it. */
+        environment?: Environment;
+        /** A new identity per run, so a run sent twice is stored once. */
+        id: string;
+        /** The page, as `detail.pages` allows: a pattern, a path, or absent. */
+        page?: string;
+        /** Where the run was made: in the page, or from the code. */
+        source: 'code' | 'page';
     };
     usage: Usage;
+    versions: {
+        /** This package's version, which collected the run. */
+        collector: string;
+        /** The Helix versions loaded on the page, one per copy of core: two means two copies. */
+        helix: string[];
+        /** The version each manifest passed in describes, by package. */
+        manifests: Record<string, string>;
+        /** The shipped rules' version, which is the collector's. */
+        rules: string;
+    };
+    /**
+     * The categories the project turned off for sending, and which place
+     * turned each off, so an empty category reads as withheld and never as
+     * nothing there.
+     */
+    withheld: Array<{
+        category: Category;
+        decidedBy: Layer;
+    }>;
 }

package/dist/report.js

@@ -6,3 +6,12 @@ export const KINDS = [
     'unforwarded-part',
     'unknown-tag',
 ];
+export const CATEGORIES = [
+    'assist',
+    'configuration',
+    'coverage',
+    'findings',
+    'performance',
+    'runtime',
+    'usage',
+];

package/dist/rules.d.ts

@@ -1,4 +1,4 @@
-import { type Finding, type Kind, type Layer, type Raw, type Severity } from './report.js';
+import { type Configuration, type Finding, type Identified, type Kind, type Layer, 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`. */
@@ -20,15 +20,15 @@ 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 findings with their severities, and how many each override turned off,
+ * by kind and layer.
  *
  * 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) => {
+export declare const applyRules: (findings: Identified[], file: Rules | undefined, argument: Rules | undefined) => {
     findings: Finding[];
-    silenced: {
-        argument: number;
-        file: number;
-    };
+    silenced: Configuration['silenced'];
 };
+/** Every override in effect, flattened, for the report's configuration. */
+export declare const overridesOf: (file: Rules | undefined, argument: Rules | undefined) => Configuration['overrides'];

package/dist/rules.js

@@ -1,5 +1,5 @@
 import { nearest } from './manifest.js';
-import { KINDS } from './report.js';
+import { KINDS, } from './report.js';
 export const SHIPPED_RULES = {
     'dead-hook': 'error',
     'dead-part': 'error',
@@ -41,7 +41,7 @@ const said = (rules, finding) => {
     return typeof plain === 'string' ? plain : undefined;
 };
 export const applyRules = (findings, file, argument) => {
-    const silenced = { argument: 0, file: 0 };
+    const off = new Map();
     const kept = [];
     for (const finding of findings) {
         let severity = SHIPPED_RULES[finding.kind];
@@ -57,10 +57,20 @@ export const applyRules = (findings, file, argument) => {
             }
         }
         if (severity === 'off') {
-            silenced[decidedBy] += 1;
+            const layer = decidedBy;
+            const key = `${finding.kind} ${layer}`;
+            const entry = off.get(key) ?? { count: 0, kind: finding.kind, layer };
+            entry.count += 1;
+            off.set(key, entry);
             continue;
         }
         kept.push({ ...finding, decidedBy, severity });
     }
-    return { findings: kept, silenced };
+    return { findings: kept, silenced: [...off.values()] };
 };
+export const overridesOf = (file, argument) => [
+    ['file', file],
+    ['argument', argument],
+].flatMap(([layer, rules]) => Object.entries(rules ?? {}).flatMap(([kind, value]) => (Array.isArray(value) ? value : [value]).map((one) => typeof one === 'string'
+    ? { kind: kind, layer, severity: one }
+    : { kind: kind, layer, severity: one.severity, tags: one.tags })));

package/dist/usage.d.ts

@@ -3,6 +3,12 @@ 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 Helix versions loaded on the page: every copy of core adds its own to
+ * a list under a registered symbol as it loads. Empty for a core older than
+ * 0.137, which lists nothing.
+ */
+export declare const loadedVersions: () => string[];
 /** The elements in the page now, counted once each. */
 export declare const walk: (from: Document) => Counted;
 /**
@@ -15,7 +21,7 @@ export declare const listed: (counted: Counted, tags: Map<string, Published>) =>
 /** 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'>;
+    counts(): Counted;
     /** Stops counting, and gives the slot back to whatever held it before. */
     stop(): void;
 }
@@ -40,5 +46,5 @@ export declare const watch: (from?: Document) => Watcher;
  * 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 declare const styled: (rules: Located[], tags: Map<string, Published>, answered: Answered, values?: boolean) => Pick<Usage, 'hookValues' | 'hooks' | 'parts'>;
 export {};

package/dist/usage.js

@@ -13,6 +13,10 @@ const under = (into, key, make) => {
     return found;
 };
 const empty = () => ({ axes: {}, composed: {}, slots: {}, tags: {} });
+export const loadedVersions = () => {
+    const listed = globalThis[Symbol.for('fusion.dev/helix/versions')];
+    return Array.isArray(listed) ? listed.filter((one) => typeof one === 'string').sort() : [];
+};
 const tally = (counted, element) => {
     const tag = element.localName;
     if (!tag.startsWith('helix-')) {
@@ -104,8 +108,12 @@ export const watch = (from = document) => {
         },
     };
 };
-export const styled = (rules, tags, answered) => {
-    const counted = { hooks: {}, parts: {} };
+export const styled = (rules, tags, answered, values = true) => {
+    const counted = {
+        hooks: {},
+        hookValues: {},
+        parts: {},
+    };
     for (const located of rules) {
         const selector = located.rule.selectorText;
         if (!selector?.includes('helix-')) {
@@ -123,6 +131,14 @@ export const styled = (rules, tags, answered) => {
                 if (property.startsWith('--') &&
                     (tags.get(tag)?.hooks.has(property) || answered.get(tag)?.has(property))) {
                     bump(under(counted.hooks, tag, () => ({})), property);
+                    if (values) {
+                        const value = (located.rule.style?.getPropertyValue?.(property) ?? '')
+                            .trim()
+                            .slice(0, 200);
+                        if (value !== '') {
+                            bump(under(under(counted.hookValues, tag, () => ({})), property, () => ({})), value);
+                        }
+                    }
                 }
             }
         }

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The version of the package this file ships in.
+ *
+ * **Written by `fusion/scripts/version.mjs`** wherever it writes the package's
+ * `package.json`, and stamped back into the repository beside it after a
+ * release, so the two never disagree; a spec beside this holds them to it.
+ * Nothing else in the running code knows which release it is.
+ */
+export declare const VERSION = "0.137.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.137.0';

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.136.0",
+  "version": "0.137.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.136.0",
+    "@fusion.dev/helix-testing": "0.137.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",