@fusion.dev/helix-diagnostics 0.135.0 → 0.137.0

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

@@ -20,23 +20,33 @@
  * report(diagnose({ tiers: [{ manifest: styled, name: '@fusion.dev/helix' }] }))
  * ```
  *
- * **Zero network calls, at this layer, ever.** The privacy policy this project
- * published says the site sends nothing, and a diagnostics package that phones
- * home from a consumer's page would make us the third party we told our own
- * readers we were not. Findings go where the caller puts them.
+ * **Nothing here sends anything.** `diagnose` returns a report and `report`
+ * prints it. Where else a report goes is a sink's decision, and every sink
+ * that leaves the page is one the caller adds.
  *
  * **Development only.** Import it from a dev-only entry: it walks every
  * stylesheet in the page and has no business in a production bundle.
  */
 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, Origin, Report, Unreadable } 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';
-/** What to look at, and what to compare it against. */
-export interface Options {
+import type { Environment, Report } from './report.js';
+import { type Watcher } from './usage.js';
+/**
+ * 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.
      *
@@ -48,6 +58,17 @@ export interface Options {
      * from outside and cannot name the losing class.
      */
     duplicates?: () => string[];
+    /**
+     * 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.
+     */
+    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.
      *
@@ -55,6 +76,12 @@ export interface Options {
      * an iframe it owns can scan that too.
      */
     from?: Document;
+    /**
+     * 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.
+     */
+    page?: string | undefined;
     /**
      * The manifests to check against, one per installed tier.
      *
@@ -63,9 +90,14 @@ export interface Options {
      * invisible to either manifest alone.
      */
     tiers: Tier[];
+    /**
+     * A watcher from `watch()`, so usage counts every element that rendered
+     * since it began. Without one, usage counts the elements in the page now.
+     */
+    watcher?: Watcher | undefined;
 }
 /**
- * One pass over the page.
+ * 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
@@ -75,5 +107,9 @@ export interface Options {
  *
  * Cheap enough to call on a route change. There is no observer and no polling
  * loop: sheets that arrive later are found by calling it again.
+ *
+ * **A manifest from another version is refused**, with one finding that says
+ * so in place of every other: 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, from, tiers }: Options) => Report;
+export declare const diagnose: (options: Options) => Report;

package/dist/index.js

@@ -1,21 +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';
-import { analyze, registrations } from './analyze.js';
+export { CATEGORIES, KINDS } from './report.js';
+export { SHIPPED_RULES } from './rules.js';
+export { watch } from './usage.js';
+export { VERSION } from './version.js';
+import { analyze, registrations, skew, versionSkew } from './analyze.js';
 import { collect } from './collect.js';
-import { index } from './manifest.js';
-export const diagnose = ({ duplicates, from, tiers }) => {
+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.');
     }
+    const resolved = resolveConfig(file, call);
+    const { detail } = resolved.configuration;
     const document_ = from ?? globalThis.document;
-    const { answered, coverage, rules } = collect(document_);
+    const { answered, coverage, rules: located } = collect(document_);
     const tags = index(tiers);
+    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: [] }
+        : 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: [
-            ...analyze(rules, tags, document_, answered),
-            ...registrations(document_, duplicates),
-        ],
+        findings: [...skewed.findings, ...judged.findings],
+        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(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,15 +54,63 @@ 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: 'dead-hook' | 'dead-part' | 'duplicate-registration' | 'unforwarded-part' | 'unknown-tag';
+    kind: Kind;
     /** One sentence, addressed to whoever wrote the CSS. */
     message: string;
     /** Where it was read. Absent only for faults that are not in a stylesheet. */
     origin?: Origin;
+    /**
+     * 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;
+    /**
+     * Which layer set `severity`: the rules this package ships, the project's
+     * file, or the argument to `diagnose`. With two layers able to override,
+     * a severity alone cannot say where it came from.
+     */
+    decidedBy: Layer;
     /** The selector the fault sits in, or the tag for a runtime fault. */
     subject: string;
+    /** The Helix tag the finding is about, which a scoped override matches on. */
+    tag: string;
 }
+/** Every fault class, stable across versions. */
+export declare const KINDS: readonly ['dead-hook', 'dead-part', 'duplicate-registration', 'manifest-skew', 'unforwarded-part', 'unknown-tag'];
+/** A fault class. */
+export type Kind = (typeof KINDS)[number];
+/** How serious a finding is. */
+export type Severity = 'error' | 'info' | 'warn';
+/** Where a finding's severity was decided. */
+export type Layer = 'argument' | 'file' | 'shipped';
+/** 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';
@@ -81,8 +135,146 @@ export interface Coverage {
     /** Every sheet that could not be read, with its reason. */
     unreadable: Unreadable[];
 }
-/** The whole result. Coverage and findings, never one without the other. */
+/**
+ * What a page uses of Helix, counted by tag.
+ *
+ * Plain objects of counts, so a sink can write the report as JSON and read it
+ * back unchanged.
+ */
+export interface Usage {
+    /**
+     * Each axis set, by tag, axis, and value: `emphasis`, `material`,
+     * `separation`, and `tone`. An axis left unset is not counted.
+     */
+    axes: Record<string, Record<string, Record<string, number>>>;
+    /**
+     * The Helix elements other Helix elements render inside their own shadow
+     * roots, such as the select a pagination size draws. Kept apart from
+     * `tags`, which counts what the page put there.
+     */
+    composed: Record<string, number>;
+    /**
+     * How the elements were counted. `watched`: every element that rendered
+     * since `watch()` began, including the ones that have gone, such as a
+     * closed dialog. `walked`: the elements in the page at the moment of the
+     * run, which misses those.
+     */
+    counted: 'walked' | 'watched';
+    /** Each hook the page's stylesheets set, by tag, counted per declaration. */
+    hooks: Record<string, Record<string, number>>;
+    /**
+     * 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. */
+    slots: Record<string, Record<string, number>>;
+    /** Each Helix element the page put there, by tag. */
+    tags: Record<string, number>;
+    /**
+     * Elements named `helix-*` that no manifest passed in lists, by tag: a
+     * page's own element under the prefix, or a family whose manifest was not
+     * passed. Kept out of the other counts, which are Helix's.
+     */
+    unlisted: Record<string, number>;
+}
+/** The 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[];
+    /**
+     * The project's own name and labels, as its configuration gives them. The
+     * key is never written into a report.
+     */
+    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

@@ -1 +1,17 @@
-export {};
+export const KINDS = [
+    'dead-hook',
+    'dead-part',
+    'duplicate-registration',
+    'manifest-skew',
+    'unforwarded-part',
+    'unknown-tag',
+];
+export const CATEGORIES = [
+    'assist',
+    'configuration',
+    'coverage',
+    'findings',
+    'performance',
+    'runtime',
+    'usage',
+];

package/dist/rules.d.ts

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