@fusion.dev/helix-diagnostics 0.136.0 → 0.138.0

package/dist/manifest.d.ts

@@ -16,8 +16,31 @@
  */
 /** 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<{
+            attributes?: Array<{
+                name: string;
+                type?: {
+                    text?: string;
+                };
+            }>;
+            members?: Array<{
+                kind?: string;
+                name: string;
+                readonly?: boolean;
+                static?: boolean;
+            }>;
             cssParts?: Array<{
                 name: string;
             }>;
@@ -41,7 +64,20 @@ export interface Tier {
  * scope, and `analyze.ts` needs both in the same file.
  */
 export interface Published {
+    /**
+     * Each attribute the tag takes, with the values it allows where its type
+     * is a union of string literals, and `null` where it takes any value.
+     */
+    attributes: Map<string, Set<string> | null>;
+    /** The family, from the module's path: `button` for `src/button/root/button-root.ts`. */
+    family?: string | undefined;
     hooks: Map<string, Set<string>>;
+    /**
+     * The attributes the element writes on itself: one named for a read-only
+     * member, as `helix-notifications` writes `unread`. Output, so never a
+     * finding when the page shows it.
+     */
+    written: Set<string>;
     parts: Map<string, Set<string>>;
 }
 /**
@@ -52,6 +88,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.
  *
@@ -65,4 +103,4 @@ export declare const index: (tiers: Tier[]) => Map<string, Published>;
  * `--button-background-color` however close they sort, and a confident wrong
  * suggestion costs more than none.
  */
-export declare const nearest: (wrong: string, candidates: Iterable<string>) => string | undefined;
+export declare const nearest: (wrong: string, candidates: Iterable<string>, ceiling?: number) => string | undefined;

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,9 +10,24 @@ export const index = (tiers) => {
                 }
                 let element = tags.get(tag);
                 if (!element) {
-                    element = { hooks: new Map(), parts: new Map() };
+                    element = {
+                        attributes: new Map(),
+                        family,
+                        hooks: new Map(),
+                        parts: new Map(),
+                        written: new Set(),
+                    };
                     tags.set(tag, element);
                 }
+                for (const member of declaration.members ?? []) {
+                    if (member.readonly && !member.static && member.kind === 'field') {
+                        element.written.add(member.name);
+                        element.written.add(member.name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`));
+                    }
+                }
+                for (const attribute of declaration.attributes ?? []) {
+                    element.attributes.set(attribute.name, allowed(attribute.type?.text));
+                }
                 for (const [field, into] of [
                     [declaration.cssParts, element.parts],
                     [declaration.cssProperties, element.hooks],
@@ -27,9 +43,30 @@ export const index = (tiers) => {
     }
     return tags;
 };
-export const nearest = (wrong, candidates) => {
+const allowed = (type) => {
+    if (!type) {
+        return null;
+    }
+    const literals = [...type.matchAll(/'([^']*)'/g)].map((match) => match[1]);
+    const rest = type
+        .replace(/'[^']*'/g, '')
+        .replace(/\b(undefined|null)\b/g, '')
+        .replace(/[|\s]/g, '');
+    return literals.length > 0 && rest === '' ? new Set(literals) : null;
+};
+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, ceiling = Math.floor(wrong.length / 3)) => {
     let best;
-    let distance = Math.floor(wrong.length / 3);
+    let distance = Math.min(ceiling, Math.floor(wrong.length / 3));
     for (const candidate of candidates) {
         const found = within(wrong, candidate, distance);
         if (found !== undefined && found < distance + 1) {

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;
     /**
@@ -68,15 +87,30 @@ export interface Finding {
     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'];
+export declare const KINDS: readonly ['dead-hook', 'dead-part', 'duplicate-registration', 'invalid-value', 'manifest-skew', 'unforwarded-part', 'unknown-attribute', 'unknown-tag'];
 /** A fault class. */
 export type Kind = (typeof KINDS)[number];
 /** How serious a finding is. */
 export type Severity = 'error' | 'info' | 'warn';
 /** Where a finding's severity was decided. */
 export type Layer = 'argument' | 'file' | 'shipped';
-/** A finding before the rules have given it a severity. */
-export type Raw = Omit<Finding, 'decidedBy' | 'severity'>;
+/** 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

@@ -2,7 +2,18 @@ export const KINDS = [
     'dead-hook',
     'dead-part',
     'duplicate-registration',
+    'invalid-value',
     'manifest-skew',
     'unforwarded-part',
+    'unknown-attribute',
     '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,11 +1,13 @@
 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',
     'duplicate-registration': 'error',
+    'invalid-value': 'error',
     'manifest-skew': 'error',
     'unforwarded-part': 'warn',
+    'unknown-attribute': 'error',
     'unknown-tag': 'error',
 };
 const SEVERITIES = new Set(['error', 'info', 'off', 'warn']);
@@ -41,7 +43,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 +59,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,26 +108,55 @@ 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: {},
+    };
+    const listing = new Map();
+    for (const [tag, element] of tags) {
+        for (const property of element.hooks.keys()) {
+            listing.set(property, [...(listing.get(property) ?? []), tag]);
+        }
+    }
+    const count = (located, tag, property) => {
+        bump(under(counted.hooks, tag, () => ({})), property);
+        if (!values) {
+            return;
+        }
+        const value = (located.rule.style?.getPropertyValue?.(property) ?? '').trim().slice(0, 200);
+        if (value !== '') {
+            bump(under(under(counted.hookValues, tag, () => ({})), property, () => ({})), value);
+        }
+    };
     for (const located of rules) {
         const selector = located.rule.selectorText;
-        if (!selector?.includes('helix-')) {
+        if (!selector) {
             continue;
         }
-        for (const { names, tag } of parts(selector)) {
+        for (const { names, tag } of selector.includes('helix-') ? parts(selector) : []) {
             for (const name of names) {
                 if (tags.get(tag)?.parts.has(name)) {
                     bump(under(counted.parts, tag, () => ({})), name);
                 }
             }
         }
-        for (const tag of targets(selector)) {
-            for (const property of Array.from(located.rule.style ?? [])) {
-                if (property.startsWith('--') &&
-                    (tags.get(tag)?.hooks.has(property) || answered.get(tag)?.has(property))) {
-                    bump(under(counted.hooks, tag, () => ({})), property);
+        const named = targets(selector).filter((tag) => tags.has(tag));
+        for (const property of Array.from(located.rule.style ?? [])) {
+            if (!property.startsWith('--')) {
+                continue;
+            }
+            if (named.length > 0) {
+                for (const tag of named) {
+                    if (tags.get(tag)?.hooks.has(property) || answered.get(tag)?.has(property)) {
+                        count(located, tag, property);
+                    }
                 }
+                continue;
+            }
+            for (const tag of listing.get(property) ?? []) {
+                count(located, tag, property);
             }
         }
     }

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.138.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.138.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.138.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./ci": {
+      "types": "./dist/ci.d.ts",
+      "default": "./dist/ci.js"
     }
   },
   "files": [
@@ -29,7 +33,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.136.0",
+    "@fusion.dev/helix-testing": "0.138.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",