@fusion.dev/helix-diagnostics 0.137.0 → 0.138.0

package/README.md

@@ -95,11 +95,24 @@ works on it:
 | Kind | Severity | Means |
 | --- | --- | --- |
 | `dead-part` | error | A `::part()` names a part the element does not publish |
-| `dead-hook` | error | A custom property is set where nothing answers it |
+| `dead-hook` | error | A hook is set where nothing answers it, or a name close to a hook is set that nothing reads |
+| `unknown-attribute` | error | A Helix element carries an attribute it does not take |
+| `invalid-value` | error | An attribute with a closed set of values carries one outside it, so the element falls back to its default |
 | `unforwarded-part` | warn | The headless tier publishes the part and the styled tier does not forward it, which is a gap in Helix |
 | `unknown-tag` | error | A rule names a tag no manifest lists |
 | `duplicate-registration` | error | Two copies of Helix are on the page |
-| `manifest-skew` | error | An element renders a part its manifest does not list, so the manifest is from another version. It replaces every other finding, since each would be judged against the wrong version. Turned off, the page is judged as usual |
+| `manifest-skew` | error | The manifest is from another version than the page runs. It replaces every other finding, since each would be judged against the wrong version. Turned off, the page is judged as usual |
+
+**Hooks are checked wherever they are set**: on a Helix tag, a class, `:root`,
+or any other selector. A hook on a selector naming no Helix tag is judged only
+on what the page holds now. It is a finding when the selector matches elements
+and none of them is, or holds, an element that answers it, while one that does
+is on the page. A selector matching nothing yet is left alone, since it may be
+for another route.
+
+**Attributes are checked on the elements the page wrote.** The global HTML
+attributes, `aria-*`, `data-*`, and the prefixes frameworks write are never
+findings. The markup Helix renders inside its own components is Helix's.
 
 ## Configure it
 
@@ -150,6 +163,24 @@ throws, and names the closest that does.
 Development only. It walks every stylesheet in the page, and it sends nothing
 anywhere.
 
+## In CI
+
+`@fusion.dev/helix-diagnostics/ci` gathers the runs of a CI job into one JSON
+file, in the shape every sink shares, and says whether the job should fail:
+
+```js
+import { ciSink } from '@fusion.dev/helix-diagnostics/ci'
+
+// `runs` are the reports `diagnose` returned in each page your job opened.
+const { code, summary } = ciSink(runs, { file: 'reports/helix-diagnostics.json' })
+console.log(summary)
+process.exitCode = code
+```
+
+A fault found on many pages is one line, with the pages it was on. `error`
+findings fail the job by default; pass `failOn: 'warn'` to fail on warnings
+too, or `'never'` to report without failing.
+
 ## Versions
 
 `@fusion.dev/helix-core` lists its version on the page as it loads, and every

package/dist/analyze.d.ts

@@ -16,7 +16,7 @@
  * consumer's own `--my-app-gap` out of the findings without a list of
  * exemptions, and what lets a finding say which tag it is wrong for.
  */
-import type { Answered, Located } from './collect.js';
+import type { Answered, Located, Readers } from './collect.js';
 import { type Published } from './manifest.js';
 import type { Raw } from './report.js';
 /** Every `helix-*` tag a selector mentions, in source order. */
@@ -33,7 +33,7 @@ export declare const parts: (selector: string) => Array<{
  * unforwarded part is phrased: the part exists, another tier publishes it, and
  * the one being styled did not forward it.
  */
-export declare const analyze: (rules: Located[], tags: Map<string, Published>, from?: Document, answered?: Answered) => Raw[];
+export declare const analyze: (rules: Located[], tags: Map<string, Published>, from?: Document, answered?: Answered, used?: Set<string>, readers?: Readers) => Raw[];
 /**
  * Two copies of Helix on one page, which is not a CSS fault and is the most
  * expensive one on the list.
@@ -75,3 +75,13 @@ export declare const skew: (tags: Map<string, Published>, from: Document) => Raw
  * `diagnose` makes first.
  */
 export declare const versionSkew: (manifests: Record<string, string>, seen: string[]) => Raw[];
+/**
+ * The attributes on the page's Helix elements that do nothing: a name the
+ * element does not take, and a value outside the ones a closed set allows.
+ * Both are valid HTML and silent, since the element falls back to its default.
+ *
+ * **Only what the page wrote.** An element Helix renders inside another is
+ * Helix's own markup. One finding per tag, attribute, and value, however many
+ * elements carry it.
+ */
+export declare const markup: (tags: Map<string, Published>, from: Document) => Raw[];

package/dist/analyze.js

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

package/dist/ci.d.ts

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

package/dist/ci.js

@@ -0,0 +1,30 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const RANK = { error: 3, info: 1, warn: 2 };
+const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+export const ciSink = (runs, { file, failOn = 'error' }) => {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ runs, schema: 1 }, null, 2)}\n`);
+    const faults = new Map();
+    for (const run of runs) {
+        for (const finding of run.findings) {
+            const fault = faults.get(finding.fingerprint) ?? { finding, pages: new Set() };
+            fault.pages.add(run.run.page ?? '(no page)');
+            faults.set(finding.fingerprint, fault);
+        }
+    }
+    const all = [...faults.values()];
+    const of = (severity) => all.filter(({ finding }) => finding.severity === severity).length;
+    const failing = failOn === 'never' ? [] : all.filter(({ finding }) => RANK[finding.severity] >= RANK[failOn]);
+    const unread = runs.reduce((total, run) => total + run.coverage.unreadable.length, 0);
+    const lines = [
+        `helix diagnostics: ${counted(runs.length, 'run')}, ${counted(of('error'), 'error')}, ${counted(of('warn'), 'warning')}, ${of('info')} info` +
+            (unread > 0 ? `, ${counted(unread, 'unreadable stylesheet')}` : '') +
+            `. Written to ${file}.`,
+    ];
+    for (const { finding, pages } of failing) {
+        const where = [...pages].sort();
+        lines.push(`  ${finding.severity} ${finding.kind}: ${finding.subject}`, `    ${finding.message}`, `    on ${where.slice(0, 5).join(', ')}${where.length > 5 ? `, and ${where.length - 5} more` : ''}`);
+    }
+    return { code: failing.length > 0 ? 1 : 0, summary: lines.join('\n') };
+};

package/dist/collect.d.ts

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

package/dist/collect.js

@@ -23,7 +23,7 @@ const rules = (list, sheet, into, depth = 0, reads) => {
         if ('selectorText' in rule) {
             into.push({ index, rule: rule, sheet });
             if (reads) {
-                for (const match of (rule.cssText ?? '').matchAll(/var\(\s*(--[a-zA-Z0-9-]+)/g)) {
+                for (const match of (rule.cssText ?? '').matchAll(/var\(\s*(--[\w-]+)/g)) {
                     if (match[1]) {
                         reads.add(match[1]);
                     }
@@ -80,20 +80,38 @@ export const collect = (from = document) => {
     const seen = new Set();
     const labels = new Map();
     const answered = new Map();
+    const used = new Set();
+    const readers = new Map();
     let readable = 0;
     const take = (sheet, host) => {
         if (!sheet || seen.has(sheet)) {
             return;
         }
         seen.add(sheet);
-        let reads;
+        let reads = used;
         if (host) {
             reads = answered.get(host.localName) ?? new Set();
             answered.set(host.localName, reads);
         }
+        const before = located.length;
         if (read(sheet, located, unreadable, labels, 0, host, reads)) {
             readable += 1;
         }
+        const scope = host ? (host.shadowRoot ?? undefined) : from;
+        const ours = !host?.localName.startsWith('helix-');
+        for (let at = before; at < located.length; at += 1) {
+            const one = located[at];
+            one.scope = scope;
+            if (ours && one.rule.selectorText) {
+                for (const match of (one.rule.cssText ?? '').matchAll(/var\(\s*(--[\w-]+)/g)) {
+                    const property = match[1];
+                    readers.set(property, [
+                        ...(readers.get(property) ?? []),
+                        { scope, selector: one.rule.selectorText },
+                    ]);
+                }
+            }
+        }
     };
     for (const sheet of Array.from(from.styleSheets)) {
         take(sheet);
@@ -114,9 +132,18 @@ export const collect = (from = document) => {
             take(owner.sheet, root.host);
         }
     }
+    for (const [tag, reads] of answered) {
+        if (!tag.startsWith('helix-')) {
+            for (const property of reads) {
+                used.add(property);
+            }
+        }
+    }
     return {
         answered,
         coverage: { read: readable, roots: shadows.length, sheets: seen.size, unreadable },
+        readers,
         rules: located,
+        used,
     };
 };

package/dist/identity.js

@@ -2,16 +2,20 @@ const CATEGORY = {
     'dead-hook': 'styling',
     'dead-part': 'styling',
     'duplicate-registration': 'integrity',
+    'invalid-value': 'markup',
     'manifest-skew': 'integrity',
     'unforwarded-part': 'styling',
+    'unknown-attribute': 'markup',
     'unknown-tag': 'integrity',
 };
 const OWNER = {
     'dead-hook': 'consumer',
     'dead-part': 'consumer',
     'duplicate-registration': 'consumer',
+    'invalid-value': 'consumer',
     'manifest-skew': 'consumer',
     'unforwarded-part': 'helix',
+    'unknown-attribute': 'consumer',
     'unknown-tag': 'consumer',
 };
 export const normalize = (subject) => subject

package/dist/index.js

@@ -7,7 +7,7 @@ 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 { analyze, markup, registrations, skew, versionSkew } from './analyze.js';
 import { collect } from './collect.js';
 import { pagePattern, resolveConfig } from './config.js';
 import { identify } from './identity.js';
@@ -27,7 +27,7 @@ export const diagnose = (options) => {
     const resolved = resolveConfig(file, call);
     const { detail } = resolved.configuration;
     const document_ = from ?? globalThis.document;
-    const { answered, coverage, rules: located } = collect(document_);
+    const { answered, coverage, readers, rules: located, used } = collect(document_);
     const tags = index(tiers);
     const counted = watcher ? watcher.counts() : walk(document_);
     const seen = loadedVersions();
@@ -38,7 +38,8 @@ export const diagnose = (options) => {
     const judged = skewed.findings.length > 0
         ? { findings: [], silenced: [] }
         : applyRules([
-            ...analyze(located, tags, document_, answered),
+            ...analyze(located, tags, document_, answered, used, readers),
+            ...markup(tags, document_),
             ...registrations(document_, duplicates),
         ].map((one) => identify(one, tags)), file?.rules, call.rules);
     const path = page ?? globalThis.location?.pathname;

package/dist/manifest.d.ts

@@ -29,6 +29,18 @@ export interface ManifestSource {
         /** 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;
             }>;
@@ -52,9 +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>>;
 }
 /**
@@ -80,4 +103,4 @@ export declare const versionsOf: (tiers: Tier[]) => Record<string, string>;
  * `--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

@@ -10,9 +10,24 @@ export const index = (tiers) => {
                 }
                 let element = tags.get(tag);
                 if (!element) {
-                    element = { family, 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],
@@ -28,6 +43,17 @@ export const index = (tiers) => {
     }
     return tags;
 };
+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) {
@@ -38,9 +64,9 @@ export const versionsOf = (tiers) => {
     }
     return versions;
 };
-export const nearest = (wrong, candidates) => {
+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

@@ -87,7 +87,7 @@ 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. */

package/dist/report.js

@@ -2,8 +2,10 @@ export const KINDS = [
     'dead-hook',
     'dead-part',
     'duplicate-registration',
+    'invalid-value',
     'manifest-skew',
     'unforwarded-part',
+    'unknown-attribute',
     'unknown-tag',
 ];
 export const CATEGORIES = [

package/dist/rules.js

@@ -4,8 +4,10 @@ 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']);

package/dist/usage.js

@@ -114,32 +114,49 @@ export const styled = (rules, tags, answered, values = true) => {
         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);
-                    if (values) {
-                        const value = (located.rule.style?.getPropertyValue?.(property) ?? '')
-                            .trim()
-                            .slice(0, 200);
-                        if (value !== '') {
-                            bump(under(under(counted.hookValues, tag, () => ({})), property, () => ({})), value);
-                        }
+        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

@@ -6,4 +6,4 @@
  * 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";
+export declare const VERSION = "0.138.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.137.0';
+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.137.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.137.0",
+    "@fusion.dev/helix-testing": "0.138.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",