@fusion.dev/helix-diagnostics 0.135.0 → 0.137.0

package/README.md

@@ -9,28 +9,154 @@ 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
+
+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 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 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
+
+`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 |
+
+## 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 project from './helix-diagnostics.json' with { type: 'json' }
+
+diagnose({
+  environment: 'development',
+  file: project,
+  rules: { 'unforwarded-part': 'off' },
+  tiers,
+})
+```
+
+```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
 
-Development only. It walks stylesheets in the page and makes no network calls,
-ever.
+`@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)
 

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,27 @@ 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[];
+/**
+ * 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

@@ -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,46 @@ 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;
+};
+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

@@ -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,17 @@
  * 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';
-/** Writes a report and hands it back, so a caller can chain a second sink. */
-export declare const report: (result: Report, to?: Console) => Report;
+/** 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.
+ *
+ * **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

@@ -1,30 +1,69 @@
-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'}`;
+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;
-    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}`);
-    }
-    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;
-    }
-    to.log(`  ${findings.length} finding${findings.length === 1 ? '' : 's'}:`);
-    for (const finding of findings) {
-        for (const text of line(finding)) {
-            to.log(text);
+    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: ${counts.join(', ')}`;
+    if (errors + warnings > 0 || missed > 0) {
+        to.group(heading);
+    }
+    else {
+        to.groupCollapsed(heading);
+    }
+    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'));
+    }
+    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));
+            }
         }
     }
+    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 ')}` : ''));
+    }
+    to.groupEnd();
     return result;
 };