@fusion.dev/helix-diagnostics 0.137.0 → 0.139.0

package/dist/analyze.js

@@ -1,7 +1,8 @@
 import { nearest } from './manifest.js';
+import { pageOf } from './page.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 +17,164 @@ export const parts = (selector) => {
     }
     return found;
 };
-const reaches = (host, wanted, depth = 0) => {
+export 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, suggested) => {
+    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;
+            }
+            let suggestion = suggested.get(property);
+            if (!suggested.has(property)) {
+                suggestion = nearest(property, answerers.keys(), HOOK_DISTANCE);
+                suggested.set(property, suggestion);
+            }
+            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 suggested = new Map();
+    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 +219,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, suggested));
             continue;
         }
         for (const property of Array.from(located.rule.style ?? [])) {
@@ -106,22 +234,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 +263,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} }`,
@@ -140,7 +273,7 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
     }
     return findings;
 };
-export const registrations = (from = document, known = () => []) => {
+export const registrations = (from = document, known = () => [], page = pageOf(from)) => {
     const findings = [];
     const registry = globalThis.customElements;
     const said = new Set();
@@ -162,7 +295,7 @@ export const registrations = (from = document, known = () => []) => {
     if (!registry) {
         return findings;
     }
-    for (const element of from.querySelectorAll('*')) {
+    for (const element of page.elements) {
         const tag = element.localName;
         if (!tag.startsWith('helix-') || said.has(tag)) {
             continue;
@@ -174,37 +307,30 @@ export const registrations = (from = document, known = () => []) => {
     }
     return findings;
 };
-export const skew = (tags, from) => {
+export const skew = (tags, from, page = pageOf(from)) => {
     const findings = [];
     const said = new Set();
-    const visit = (root, depth) => {
-        if (depth > 32) {
-            return;
+    for (const element of page.elements) {
+        const shadow = element.shadowRoot;
+        if (!shadow) {
+            continue;
         }
-        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,
-                    });
-                }
+        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
@@ -217,3 +343,95 @@ 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, page = pageOf(from)) => {
+    const found = new Map();
+    for (const element of page.elements) {
+        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 });
+                    }
+                }
+            }
+        }
+    }
+    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

@@ -15,11 +15,17 @@
  * the only way to know. Each one becomes a `Coverage.unreadable` entry, so the
  * hole is in the output rather than in the reader's assumptions.
  */
+import { type Page } from './page.js';
 import type { Coverage } from './report.js';
 /** One rule, with where it came from. */
 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 +46,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.
  *
@@ -51,8 +68,10 @@ export type Answered = Map<string, Set<string>>;
  * hundred passes over rules already read. A `Set` keyed on the sheet object
  * fixes the number and the cost together.
  */
-export declare const collect: (from?: Document) => {
+export declare const collect: (from?: Document, page?: Page) => {
     answered: Answered;
     coverage: Coverage;
+    readers: Readers;
     rules: Located[];
+    used: Set<string>;
 };

package/dist/collect.js

@@ -1,3 +1,4 @@
+import { OVERLAY, pageOf } from './page.js';
 const name = (sheet, seen, host) => {
     if (sheet.href) {
         return sheet.href;
@@ -23,7 +24,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]);
                     }
@@ -62,38 +63,44 @@ const read = (sheet, into, unreadable, labels, depth = 0, host, reads) => {
     rules(list, label, into, depth, reads);
     return true;
 };
-const roots = (from, found, depth = 0) => {
-    if (depth > 32) {
-        return;
-    }
-    for (const element of from.querySelectorAll('*')) {
-        const root = element.shadowRoot;
-        if (root) {
-            found.push(root);
-            roots(root, found, depth + 1);
-        }
-    }
-};
-export const collect = (from = document) => {
+export const collect = (from = document, page = pageOf(from)) => {
     const located = [];
     const unreadable = [];
     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);
@@ -101,8 +108,7 @@ export const collect = (from = document) => {
     for (const sheet of from.adoptedStyleSheets ?? []) {
         take(sheet);
     }
-    const shadows = [];
-    roots(from, shadows);
+    const shadows = page.roots.filter((root) => root.host.localName !== OVERLAY);
     for (const root of shadows) {
         for (const sheet of Array.from(root.styleSheets ?? [])) {
             take(sheet, root.host);
@@ -114,9 +120,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/config.d.ts

@@ -21,6 +21,12 @@ export interface Config {
     rules?: Rules;
     /** Each category, sent or withheld. Nothing is sent without a key. */
     send?: Partial<Record<Category, boolean>>;
+    /**
+     * Where `initDiagnostics()` hands each run, beside the console: the
+     * `overlay` on the page, and the `relay`, `helix diagnostics`, on or off or
+     * at an address of its own.
+     */
+    sinks?: Partial<Configuration['sinks']>;
 }
 /** The shipped defaults. */
 export declare const DEFAULTS: {
@@ -48,7 +54,18 @@ export declare const DEFAULTS: {
         readonly runtime: true;
         readonly usage: true;
     };
+    readonly sinks: {
+        readonly overlay: true;
+        readonly relay: false;
+    };
 };
+/**
+ * A local host: `localhost`, `127.0.0.1`, `[::1]`, `*.localhost`, and `*.test`.
+ * A page with no declared environment runs only on one, and the relay is only
+ * ever at one, as `helix diagnostics` takes runs only from one: a relay at
+ * another address would be a second way to send, with no key and no `send`.
+ */
+export declare const LOCAL: RegExp;
 /** 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. */