@fusion.dev/helix-diagnostics 0.0.0-dev

package/dist/analyze.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The faults, derived from the rules and the manifest and nothing else.
+ *
+ * **Every rule here is set membership against the manifest, never a naming
+ * pattern**, and that is the design decision the whole file turns on. The
+ * obvious rule for a misnamed hook is "a `--<family>-*` property whose family
+ * does not match the element it is set on", and in this library that rule is
+ * wrong 27 times: `helix-breadcrumb` answers `--breadcrumbs-*` because the
+ * family is plural, and every chart shares a `--chart-*` namespace across nine
+ * tags. A pattern rule would open with 27 false findings in the library's own
+ * repository, and `#238` is the row that says what that costs: a check that
+ * cries wolf trains its only reader to ignore it.
+ *
+ * **Scope comes from the selector rather than the name.** A property is only
+ * examined when the rule it sits in targets a Helix tag, which is what keeps a
+ * 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 Published } from './manifest.js';
+import type { Finding } from './report.js';
+/**
+ * The findings in one page's rules.
+ *
+ * `tiers` is the tier names in the order they were passed, which is how an
+ * unforwarded part is phrased: the part exists, another tier publishes it, and
+ * the one being styled did not forward it.
+ */
+export declare const analyze: (rules: Located[], tags: Map<string, Published>, from?: Document, answered?: Answered) => Finding[];
+/**
+ * Two copies of Helix on one page, which is not a CSS fault and is the most
+ * expensive one on the list.
+ *
+ * **Helix already detects this, and detecting it again here would be worse.**
+ * `@fusion.dev/helix-core`'s `customElement` decorator sees the second registration as
+ * it happens, with both class objects in hand, which is a position nothing
+ * later can improve on: by the time a page can be scanned, the losing class is
+ * unreachable and all that is left is an identity mismatch to infer from. So
+ * this reads `duplicateRegistrations()` rather than re-deriving it, which is
+ * `CLAUDE.md`'s rule about where a fix lives applied to a detector.
+ *
+ * The identity check stays as a fallback, for the copy that never went through
+ * Helix's own decorator: a fork, a hand-written `customElements.define`, or a
+ * version old enough to predate the warning. That case reports what it can see,
+ * which is that a live element is not an instance of its own registered class.
+ */
+export declare const registrations: (from?: Document, known?: () => string[]) => Finding[];

package/dist/analyze.js

@@ -0,0 +1,230 @@
+import { nearest } from './manifest.js';
+/** Every `helix-*` tag a selector mentions, in source order. */
+const targets = (selector) => {
+    const found = new Set();
+    for (const match of selector.matchAll(/\bhelix-[a-z0-9]+(?:-[a-z0-9]+)*/g)) {
+        found.add(match[0]);
+    }
+    return [...found];
+};
+/** Every `::part(a b)` in a selector, with the tag it hangs off. */
+const parts = (selector) => {
+    const found = [];
+    for (const match of selector.matchAll(/(helix-[a-z0-9-]+)((?:[^\s>+~,]*))::part\(\s*([^)]*?)\s*\)/g)) {
+        const names = (match[3] ?? '').split(/\s+/).filter(Boolean);
+        if (match[1] && names.length > 0) {
+            found.push({ names, tag: match[1] });
+        }
+    }
+    return found;
+};
+/**
+ * Whether any of `wanted` sits inside `host`, shadow roots included.
+ *
+ * **This is the check a static tool cannot make, and skipping it is a three
+ * percent false-positive rate.** Measured on this repository: `landing.module.css`
+ * sets `--icon-button-radius` and `--icon-button-size` on `helix-copy-button`,
+ * which answers neither, and both work, because a copy button *renders* an icon
+ * button and custom properties inherit through a shadow boundary. A rule that
+ * reads the manifest alone calls those two dead. Six findings out of 197
+ * declarations examined, every one wrong, in the library's own repository.
+ *
+ * A collector running in the page can simply look. That is the whole argument
+ * for the collector being in the page rather than in a linter.
+ */
+const reaches = (host, wanted, depth = 0) => {
+    if (depth > 16) {
+        return false;
+    }
+    for (const node of [host, ...host.querySelectorAll('*')]) {
+        if (node !== host && wanted.has(node.localName)) {
+            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;
+                }
+            }
+        }
+    }
+    return false;
+};
+const origin = (located) => ({
+    cssText: located.rule.cssText,
+    index: located.index,
+    sheet: located.sheet,
+});
+/**
+ * The findings in one page's rules.
+ *
+ * `tiers` is the tier names in the order they were passed, which is how an
+ * unforwarded part is phrased: the part exists, another tier publishes it, and
+ * the one being styled did not forward it.
+ */
+export const analyze = (rules, tags, from, answered = new Map()) => {
+    const findings = [];
+    for (const located of rules) {
+        const selector = located.rule.selectorText;
+        if (!selector?.includes('helix-')) {
+            continue;
+        }
+        for (const { names, tag } of parts(selector)) {
+            const element = tags.get(tag);
+            if (!element) {
+                findings.push({
+                    kind: 'unknown-tag',
+                    message: `\`${tag}\` is in no manifest passed to the collector. Either the tag is misspelled, or the manifest is from a different version of Helix than the page.`,
+                    origin: origin(located),
+                    subject: tag,
+                });
+                continue;
+            }
+            for (const part of names) {
+                const publishers = element.parts.get(part);
+                if (publishers) {
+                    continue;
+                }
+                /* A part the *other* tier publishes is not a typo, it is a part that
+                   was never forwarded, and the two need different sentences: one is
+                   the author's mistake and the other is ours. */
+                const elsewhere = [...tags].find(([other, entry]) => other !== tag && entry.parts.has(part));
+                if (elsewhere) {
+                    findings.push({
+                        expected: part,
+                        kind: 'unforwarded-part',
+                        message: `\`${tag}\` does not publish \`${part}\`, though \`${elsewhere[0]}\` does. The rule matches nothing until the part is forwarded, which is a gap in Helix rather than in this CSS.`,
+                        origin: origin(located),
+                        subject: `${tag}::part(${part})`,
+                    });
+                    continue;
+                }
+                const suggestion = nearest(part, element.parts.keys());
+                findings.push({
+                    expected: suggestion,
+                    kind: 'dead-part',
+                    message: suggestion
+                        ? `\`${tag}\` publishes no part named \`${part}\`. The closest it does publish is \`${suggestion}\`.`
+                        : `\`${tag}\` publishes no part named \`${part}\`, so this rule matches nothing. Published: ${[...element.parts.keys()].sort().join(', ') || 'none'}.`,
+                    origin: origin(located),
+                    subject: `${tag}::part(${part})`,
+                });
+            }
+        }
+        /* A property set on a selector naming several Helix tags is wrong only if
+           it is unknown to all of them: `helix-button, helix-link { --gap: 0 }` is
+           fine when either answers it. */
+        const mentioned = targets(selector).map((tag) => [tag, tags.get(tag)]);
+        const known = mentioned.filter(([, element]) => element);
+        if (known.length === 0) {
+            continue;
+        }
+        for (const property of Array.from(located.rule.style ?? [])) {
+            if (!property.startsWith('--')) {
+                continue;
+            }
+            if (known.some(([, element]) => element?.hooks.has(property))) {
+                continue;
+            }
+            /* The manifest is a floor, not the whole truth. A tag whose own shadow
+               styles read the property answers it whatever `cem` recorded, which is
+               how `helix-copy-button` answers `--icon-button-size` while declaring no
+               hooks at all: it sets `styles = [HelixIconButton.styles, styles]` and
+               borrows the stylesheet outright, a relationship no manifest field has a
+               name for. */
+            if (known.some(([tag]) => answered.get(tag)?.has(property))) {
+                continue;
+            }
+            /* Unknown to every tag in the selector, and unknown to Helix entirely, is
+               a property of the consumer's own that happens to be set here. Only a
+               name Helix does have somewhere is evidence of a mistake. */
+            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) {
+                continue;
+            }
+            /* Set on an ancestor of something that *does* answer it, this is
+               deliberate: the property inherits through the shadow boundary and
+               reaches the nested component. Only a page can settle that, so a run
+               without one declines to guess. */
+            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;
+                    }
+                }
+                if (inherits) {
+                    continue;
+                }
+            }
+            const tag = known[0]?.[0] ?? 'the element';
+            findings.push({
+                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}\`, 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} }`,
+            });
+        }
+    }
+    return findings;
+};
+/**
+ * Two copies of Helix on one page, which is not a CSS fault and is the most
+ * expensive one on the list.
+ *
+ * **Helix already detects this, and detecting it again here would be worse.**
+ * `@fusion.dev/helix-core`'s `customElement` decorator sees the second registration as
+ * it happens, with both class objects in hand, which is a position nothing
+ * later can improve on: by the time a page can be scanned, the losing class is
+ * unreachable and all that is left is an identity mismatch to infer from. So
+ * this reads `duplicateRegistrations()` rather than re-deriving it, which is
+ * `CLAUDE.md`'s rule about where a fix lives applied to a detector.
+ *
+ * The identity check stays as a fallback, for the copy that never went through
+ * Helix's own decorator: a fork, a hand-written `customElements.define`, or a
+ * version old enough to predate the warning. That case reports what it can see,
+ * which is that a live element is not an instance of its own registered class.
+ */
+export const registrations = (from = document, known = () => []) => {
+    const findings = [];
+    const registry = globalThis.customElements;
+    const said = new Set();
+    const duplicate = (tag, how) => {
+        if (said.has(tag)) {
+            return;
+        }
+        said.add(tag);
+        findings.push({
+            kind: 'duplicate-registration',
+            message: `\`${tag}\` is registered twice by different classes, so this page holds two copies of Helix (${how}). The first registration keeps the tag: every element of that name is built from it whatever the second copy exports, which makes \`instanceof\` against the second copy false and leaves its fixes out of the DOM. Deduplicate the dependency.`,
+            subject: tag,
+        });
+    };
+    for (const tag of known()) {
+        duplicate(tag, 'reported by the decorator at the moment it happened');
+    }
+    if (!registry) {
+        return findings;
+    }
+    for (const element of from.querySelectorAll('*')) {
+        const tag = element.localName;
+        if (!tag.startsWith('helix-') || said.has(tag)) {
+            continue;
+        }
+        const registered = registry.get(tag);
+        if (registered && !(element instanceof registered)) {
+            duplicate(tag, 'a live element is not an instance of its own registered class');
+        }
+    }
+    return findings;
+};

package/dist/collect.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Every stylesheet rule the page will actually apply, and an honest account of
+ * the ones that could not be read.
+ *
+ * **`document.styleSheets` is not the input.** Component CSS lives in adopted
+ * stylesheets inside shadow roots, which appear in that list nowhere at all, so
+ * a collector reading only it would report clean while blind to the half of the
+ * page it exists to check. Four sources are walked: the document's sheets, the
+ * document's adopted sheets, and both of those again for every shadow root
+ * reachable from the document.
+ *
+ * **Cross-origin sheets throw rather than return nothing**, which is the one
+ * failure mode that has to be caught rather than avoided: `.cssRules` on a sheet
+ * from another origin raises `SecurityError`, and a `try` around the access is
+ * 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 { Coverage } from './report.js';
+/** One rule, with where it came from. */
+export interface Located {
+    index: number;
+    rule: CSSStyleRule;
+    sheet: string;
+}
+/**
+ * Every custom property a tag's own shadow styles read, by tag.
+ *
+ * **This is what the manifest cannot tell you.** `helix-copy-button` declares no
+ * hooks at all and answers `--icon-button-size` and `--icon-button-radius`,
+ * because its class sets `styles = [HelixIconButton.styles, styles].flat()`:
+ * it borrows another component's stylesheet outright. That is not inheritance,
+ * not a mixin and not a part, so no manifest field describes it and `cem` records
+ * nothing. Two correct declarations in this repository's own `landing.module.css`
+ * were called dead on the strength of that silence.
+ *
+ * A `var(--x)` inside the element's own shadow styles is direct evidence that
+ * the element reads the property, which is a stronger claim than the manifest
+ * makes and is available only to something running in the page. So it is
+ * collected on the way past and the manifest is treated as a floor rather than
+ * the whole truth.
+ */
+export type Answered = Map<string, Set<string>>;
+/**
+ * Every readable rule in the page, and what was missed getting them.
+ *
+ * **Sheets are counted by identity, and the reason is Lit.** A Lit class holds
+ * one `CSSStyleSheet` and every instance of it adopts that same object, so a
+ * page with two hundred Helix elements presents the same twenty sheets over and
+ * over. Counted naively that is `sheets: 400`, a coverage denominator that
+ * describes the page's element count rather than its stylesheets, and four
+ * 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) => {
+    answered: Answered;
+    coverage: Coverage;
+    rules: Located[];
+};

package/dist/collect.js

@@ -0,0 +1,173 @@
+/**
+ * A sheet with no `href` still needs a name a reader can act on.
+ *
+ * **The ordinal is load-bearing, not decoration.** A Lit element adopts several
+ * sheets, its own and every base class's, and all of them are "adopted by
+ * `<helix-button>`": without a number, a finding's receipt names a place that
+ * matches three sheets and the reader has to guess which. Counted per label so
+ * the first of a kind is unnumbered and reads naturally.
+ */
+const name = (sheet, seen, host) => {
+    if (sheet.href) {
+        return sheet.href;
+    }
+    const base = host
+        ? `adopted by <${host.localName}>`
+        : sheet.ownerNode instanceof globalThis.Element
+            ? `<${sheet.ownerNode.localName}> in the document`
+            : 'adopted by the document';
+    const count = (seen.get(base) ?? 0) + 1;
+    seen.set(base, count);
+    return count === 1 ? base : `${base} (${count})`;
+};
+/**
+ * The rules of one sheet, flattened through `@media` and `@supports`.
+ *
+ * A dead `::part()` inside a media query is dead at that width, which is still
+ * dead. Grouping rules are descended into rather than skipped, and `@import` is
+ * followed through `styleSheet` because an imported sheet is a sheet.
+ */
+const rules = (list, sheet, into, depth = 0, reads) => {
+    if (depth > 8) {
+        return;
+    }
+    for (let index = 0; index < list.length; index += 1) {
+        /* Indexed rather than `list.item(index)`. Both are standard and only one is
+           universally implemented: happy-dom's `CSSRuleList` is array-like with no
+           `item`, so a collector calling it throws under the DOM the specs run in
+           and works in a browser, which is the worst of both. */
+        const rule = list[index];
+        if (!rule) {
+            continue;
+        }
+        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)) {
+                    if (match[1]) {
+                        reads.add(match[1]);
+                    }
+                }
+            }
+            /* A nested rule is a rule. CSS nesting puts `&::part(x)` inside the rule
+               for the host, and the part name is just as wrong there. */
+            const nested = rule.cssRules;
+            if (nested) {
+                rules(nested, sheet, into, depth + 1, reads);
+            }
+            continue;
+        }
+        const grouped = rule.cssRules;
+        if (grouped) {
+            rules(grouped, sheet, into, depth + 1, reads);
+            continue;
+        }
+        const imported = rule.styleSheet;
+        if (imported) {
+            read(imported, into, [], new Map(), depth + 1, undefined, reads);
+        }
+    }
+};
+/** One sheet, or the reason it could not be read. */
+const read = (sheet, into, unreadable, labels, depth = 0, host, reads) => {
+    const label = name(sheet, labels, host);
+    let list;
+    try {
+        /* Reading the property is what throws, so it is read before anything else
+           is done with it. `cssRules` on a cross-origin sheet raises SecurityError,
+           and there is no flag to ask instead. */
+        list = sheet.cssRules;
+    }
+    catch (error) {
+        unreadable.push({
+            reason: error instanceof DOMException && error.name === 'SecurityError' ? 'cross-origin' : 'threw',
+            sheet: label,
+        });
+        return false;
+    }
+    rules(list, label, into, depth, reads);
+    return true;
+};
+/**
+ * Every shadow root reachable from a node, depth first.
+ *
+ * **`querySelectorAll('*')` does not cross a shadow boundary**, so this recurses
+ * per root rather than querying once. A closed root is invisible here and is
+ * counted nowhere, which is the correct silence: the collector cannot know it
+ * exists, and inventing a number for what it cannot see is the dishonesty the
+ * coverage field is there to prevent. Every Helix root is open.
+ */
+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);
+        }
+    }
+};
+/**
+ * Every readable rule in the page, and what was missed getting them.
+ *
+ * **Sheets are counted by identity, and the reason is Lit.** A Lit class holds
+ * one `CSSStyleSheet` and every instance of it adopts that same object, so a
+ * page with two hundred Helix elements presents the same twenty sheets over and
+ * over. Counted naively that is `sheets: 400`, a coverage denominator that
+ * describes the page's element count rather than its stylesheets, and four
+ * hundred passes over rules already read. A `Set` keyed on the sheet object
+ * fixes the number and the cost together.
+ */
+export const collect = (from = document) => {
+    const located = [];
+    const unreadable = [];
+    const seen = new Set();
+    const labels = new Map();
+    const answered = new Map();
+    let readable = 0;
+    const take = (sheet, host) => {
+        if (!sheet || seen.has(sheet)) {
+            return;
+        }
+        seen.add(sheet);
+        let reads;
+        if (host) {
+            reads = answered.get(host.localName) ?? new Set();
+            answered.set(host.localName, reads);
+        }
+        if (read(sheet, located, unreadable, labels, 0, host, reads)) {
+            readable += 1;
+        }
+    };
+    for (const sheet of Array.from(from.styleSheets)) {
+        take(sheet);
+    }
+    for (const sheet of from.adoptedStyleSheets ?? []) {
+        take(sheet);
+    }
+    const shadows = [];
+    roots(from, shadows);
+    for (const root of shadows) {
+        for (const sheet of Array.from(root.styleSheets ?? [])) {
+            take(sheet, root.host);
+        }
+        for (const sheet of root.adoptedStyleSheets ?? []) {
+            take(sheet, root.host);
+        }
+        /* `ShadowRoot.styleSheets` covers a `<style>` inside the root in a browser
+           and is absent from happy-dom entirely, so the elements are asked
+           directly as well. Identity dedup is what makes asking twice free, and
+           without this path every spec covering a root's own `<style>` would be a
+           spec that cannot fail. */
+        for (const owner of root.querySelectorAll('style, link')) {
+            take(owner.sheet, root.host);
+        }
+    }
+    return {
+        answered,
+        coverage: { read: readable, roots: shadows.length, sheets: seen.size, unreadable },
+        rules: located,
+    };
+};

package/dist/console.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The default sink: the console, and coverage before anything else.
+ *
+ * **Coverage is printed on a clean run too.** "No findings" from a collector
+ * that read three sheets of nineteen is not a pass, and the only way to stop
+ * that being read as one is to put the denominator next to the numerator every
+ * single time.
+ *
+ * A sink and not a policy. It writes and returns; a CI sink writing JSON and an
+ * OTLP exporter are the same `Report` consumed differently, which is what keeps
+ * all three agreeing by construction rather than by our diligence.
+ */
+import type { Report } from './report.js';
+/** Writes a report and hands it back, so a caller can chain a second sink. */
+export declare const report: (result: Report, to?: Console) => Report;

package/dist/console.js

@@ -0,0 +1,31 @@
+const line = (finding) => {
+    const out = [`  ${finding.kind}: ${finding.subject}`, `    ${finding.message}`];
+    if (finding.origin) {
+        out.push(`    in ${finding.origin.sheet}, rule ${finding.origin.index}`);
+        out.push(`    ${finding.origin.cssText}`);
+    }
+    return out;
+};
+/** Writes a report and hands it back, so a caller can chain a second sink. */
+export const report = (result, to = console) => {
+    const { coverage, findings } = result;
+    const missed = coverage.sheets - coverage.read;
+    to.log(`helix diagnostics: read ${coverage.read} of ${coverage.sheets} stylesheets across ${coverage.roots} shadow roots` +
+        (missed > 0 ? `, ${missed} unreadable` : ''));
+    for (const sheet of coverage.unreadable) {
+        to.log(`  unreadable (${sheet.reason}): ${sheet.sheet}`);
+    }
+    if (findings.length === 0) {
+        to.log(missed > 0
+            ? '  no findings in what could be read. The unreadable sheets above were not checked.'
+            : '  no findings.');
+        return result;
+    }
+    to.log(`  ${findings.length} finding${findings.length === 1 ? '' : 's'}:`);
+    for (const finding of findings) {
+        for (const text of line(finding)) {
+            to.log(text);
+        }
+    }
+    return result;
+};

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Everything a consumer gets wrong in Helix is valid CSS.
+ *
+ * It compiles, it ships, it produces no error, and it is detectable only against
+ * the manifest. A `::part()` naming a part nothing publishes styles nothing. A
+ * hook named for the wrong family inherits into the subtree and does nothing
+ * where it was written. Two copies of the library on one page make `instanceof`
+ * quietly false. None of it warns.
+ *
+ * The library's own repository found six classes of this in one week, written by
+ * the people who wrote the library, and the one that mattered most passed every
+ * one of sixty checks: a part rendering visibly with no rule, black on the
+ * headless tier, caught four days late by a screenshot. A third party gets none
+ * of those checks. This is what they get instead.
+ *
+ * ```ts
+ * import { diagnose, report } from '@fusion.dev/helix-diagnostics'
+ * import styled from '@fusion.dev/helix/custom-elements.json'
+ *
+ * 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.
+ *
+ * **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 { report } from './console.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';
+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 {
+    /**
+     * `duplicateRegistrations` from `@fusion.dev/helix-core`, when it is installed.
+     *
+     * **Passed in rather than imported**, so this package does not depend on the
+     * library it diagnoses. A diagnostics release would otherwise have to follow
+     * every core release, and a consumer on an older core could not run a newer
+     * collector at all. Omitted, the duplicate check falls back to comparing a
+     * live element against its own registered class, which finds the same fault
+     * from outside and cannot name the losing class.
+     */
+    duplicates?: () => string[];
+    /**
+     * The document to scan. Defaults to the ambient one.
+     *
+     * Present so a test can hand over a constructed document, and so a page with
+     * an iframe it owns can scan that too.
+     */
+    from?: Document;
+    /**
+     * The manifests to check against, one per installed tier.
+     *
+     * **Pass both tiers when both are installed.** A part `@fusion.dev/helix-headless`
+     * publishes and `@fusion.dev/helix` never forwarded is a real fault and is
+     * invisible to either manifest alone.
+     */
+    tiers: Tier[];
+}
+/**
+ * One pass 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
+ * the same empty array whether it read everything or nothing, and this
+ * repository has already shipped one check that was structurally incapable of
+ * failing and green for weeks because of it. An empty `findings` is only
+ * meaningful beside the `coverage` that says what was looked at.
+ *
+ * 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.
+ */
+export declare const diagnose: ({ duplicates, from, tiers }: Options) => Report;

package/dist/index.js

@@ -0,0 +1,64 @@
+/**
+ * Everything a consumer gets wrong in Helix is valid CSS.
+ *
+ * It compiles, it ships, it produces no error, and it is detectable only against
+ * the manifest. A `::part()` naming a part nothing publishes styles nothing. A
+ * hook named for the wrong family inherits into the subtree and does nothing
+ * where it was written. Two copies of the library on one page make `instanceof`
+ * quietly false. None of it warns.
+ *
+ * The library's own repository found six classes of this in one week, written by
+ * the people who wrote the library, and the one that mattered most passed every
+ * one of sixty checks: a part rendering visibly with no rule, black on the
+ * headless tier, caught four days late by a screenshot. A third party gets none
+ * of those checks. This is what they get instead.
+ *
+ * ```ts
+ * import { diagnose, report } from '@fusion.dev/helix-diagnostics'
+ * import styled from '@fusion.dev/helix/custom-elements.json'
+ *
+ * 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.
+ *
+ * **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 { report } from './console.js';
+export { index, nearest } from './manifest.js';
+import { analyze, registrations } from './analyze.js';
+import { collect } from './collect.js';
+import { index } from './manifest.js';
+/**
+ * One pass 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
+ * the same empty array whether it read everything or nothing, and this
+ * repository has already shipped one check that was structurally incapable of
+ * failing and green for weeks because of it. An empty `findings` is only
+ * meaningful beside the `coverage` that says what was looked at.
+ *
+ * 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.
+ */
+export const diagnose = ({ duplicates, from, tiers }) => {
+    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 document_ = from ?? globalThis.document;
+    const { answered, coverage, rules } = collect(document_);
+    const tags = index(tiers);
+    return {
+        coverage,
+        findings: [
+            ...analyze(rules, tags, document_, answered),
+            ...registrations(document_, duplicates),
+        ],
+    };
+};

package/dist/manifest.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A custom-elements manifest, indexed for lookup.
+ *
+ * The manifest is the only thing that knows which parts a tag publishes and
+ * which hooks it answers, and it is already a dependency of anyone consuming
+ * Helix: `package.json` points at it through `customElements`, and every editor
+ * integration reads it. So the collector takes it as input rather than shipping
+ * a copy, which is also what keeps a diagnostics release from having to follow
+ * a library release.
+ *
+ * **Both tiers are passed together when both are installed.** A part that
+ * `@fusion.dev/helix-headless` publishes and `@fusion.dev/helix` does not forward is a
+ * real fault (148 of them across 19 families, found by hand), and it is only
+ * visible when the two manifests are compared. Which manifest an entry came
+ * from is therefore tracked rather than merged away.
+ */
+/** The subset of the manifest schema this reads. Nothing else is touched. */
+export interface ManifestSource {
+    modules?: Array<{
+        declarations?: Array<{
+            cssParts?: Array<{
+                name: string;
+            }>;
+            cssProperties?: Array<{
+                name: string;
+            }>;
+            tagName?: string;
+        }>;
+    }>;
+}
+/** One manifest, and which tier shipped it. */
+export interface Tier {
+    manifest: ManifestSource;
+    /** Package name, used verbatim in a finding's message. */
+    name: string;
+}
+/**
+ * What one tag publishes, per tier.
+ *
+ * Not `Element`, which it was: that shadows the DOM's own `Element` wherever
+ * both are in scope, and `analyze.ts` needs both in the same file.
+ */
+export interface Published {
+    hooks: Map<string, Set<string>>;
+    parts: Map<string, Set<string>>;
+}
+/**
+ * Every tag across every tier, with the tiers that publish each part and hook.
+ *
+ * A `Set` of tier names rather than a boolean because the useful finding is not
+ * "this part does not exist" but "this part exists on the headless tier and the
+ * styled one did not forward it", and that sentence needs the names.
+ */
+export declare const index: (tiers: Tier[]) => Map<string, Published>;
+/**
+ * The published name closest to a wrong one, or nothing when none is close.
+ *
+ * **A suggestion is the difference between a finding and a chore.**
+ * `--breadcrumb-hover-color` is wrong because the family is `breadcrumbs`, and
+ * a reader told only that the hook is unknown has to go and read the manifest;
+ * told that `--breadcrumbs-hover-color` exists, they are done.
+ *
+ * Levenshtein with a ceiling of a third of the name's length. The ceiling is
+ * what stops a suggestion from being noise: `--button-x` is not a typo for
+ * `--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;

package/dist/manifest.js

@@ -0,0 +1,93 @@
+/**
+ * A custom-elements manifest, indexed for lookup.
+ *
+ * The manifest is the only thing that knows which parts a tag publishes and
+ * which hooks it answers, and it is already a dependency of anyone consuming
+ * Helix: `package.json` points at it through `customElements`, and every editor
+ * integration reads it. So the collector takes it as input rather than shipping
+ * a copy, which is also what keeps a diagnostics release from having to follow
+ * a library release.
+ *
+ * **Both tiers are passed together when both are installed.** A part that
+ * `@fusion.dev/helix-headless` publishes and `@fusion.dev/helix` does not forward is a
+ * real fault (148 of them across 19 families, found by hand), and it is only
+ * visible when the two manifests are compared. Which manifest an entry came
+ * from is therefore tracked rather than merged away.
+ */
+/**
+ * Every tag across every tier, with the tiers that publish each part and hook.
+ *
+ * A `Set` of tier names rather than a boolean because the useful finding is not
+ * "this part does not exist" but "this part exists on the headless tier and the
+ * styled one did not forward it", and that sentence needs the names.
+ */
+export const index = (tiers) => {
+    const tags = new Map();
+    for (const tier of tiers) {
+        for (const module of tier.manifest.modules ?? []) {
+            for (const declaration of module.declarations ?? []) {
+                const tag = declaration.tagName;
+                if (!tag) {
+                    continue;
+                }
+                let element = tags.get(tag);
+                if (!element) {
+                    element = { hooks: new Map(), parts: new Map() };
+                    tags.set(tag, element);
+                }
+                for (const [field, into] of [
+                    [declaration.cssParts, element.parts],
+                    [declaration.cssProperties, element.hooks],
+                ]) {
+                    for (const entry of field ?? []) {
+                        const publishers = into.get(entry.name) ?? new Set();
+                        publishers.add(tier.name);
+                        into.set(entry.name, publishers);
+                    }
+                }
+            }
+        }
+    }
+    return tags;
+};
+/**
+ * The published name closest to a wrong one, or nothing when none is close.
+ *
+ * **A suggestion is the difference between a finding and a chore.**
+ * `--breadcrumb-hover-color` is wrong because the family is `breadcrumbs`, and
+ * a reader told only that the hook is unknown has to go and read the manifest;
+ * told that `--breadcrumbs-hover-color` exists, they are done.
+ *
+ * Levenshtein with a ceiling of a third of the name's length. The ceiling is
+ * what stops a suggestion from being noise: `--button-x` is not a typo for
+ * `--button-background-color` however close they sort, and a confident wrong
+ * suggestion costs more than none.
+ */
+export const nearest = (wrong, candidates) => {
+    let best;
+    let distance = Math.floor(wrong.length / 3);
+    for (const candidate of candidates) {
+        const found = within(wrong, candidate, distance);
+        if (found !== undefined && found < distance + 1) {
+            best = candidate;
+            distance = found;
+        }
+    }
+    return best;
+};
+/** Levenshtein distance, or `undefined` once it is certainly over the ceiling. */
+const within = (from, to, ceiling) => {
+    if (Math.abs(from.length - to.length) > ceiling) {
+        return undefined;
+    }
+    let previous = Array.from({ length: to.length + 1 }, (_, column) => column);
+    for (let row = 1; row <= from.length; row += 1) {
+        const current = [row];
+        for (let column = 1; column <= to.length; column += 1) {
+            current[column] = Math.min((previous[column] ?? 0) + 1, (current[column - 1] ?? 0) + 1, (previous[column - 1] ?? 0) + (from[row - 1] === to[column - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    const total = previous[to.length];
+    return total !== undefined && total <= ceiling ? total : undefined;
+};

package/dist/report.d.ts

@@ -0,0 +1,88 @@
+/**
+ * What a diagnostic run returns, and why coverage is not a field beside the
+ * findings.
+ *
+ * **A bare pass is a lie this collector is structurally capable of telling.**
+ * Cross-origin stylesheets throw on `.cssRules`, and a run that could not read
+ * half its input reports the same empty array as a run that read all of it.
+ * `check:dialect` shipped in exactly that condition for weeks: green, and
+ * incapable of being anything else. So `Report` has no `findings` that can be
+ * destructured away from the `coverage` that qualifies them, and the console
+ * sink prints coverage first whether or not anything was found.
+ */
+/** Where a rule was read from, so a reader can go and look at it. */
+export interface Origin {
+    /**
+     * The rule's own text, which is the receipt.
+     *
+     * **There is no line number and there cannot be one.** CSSOM exposes
+     * `cssText` and an index within the sheet; the byte offset in the authored
+     * file is not in the object model at any level. `24-diagnostics.md` asks for a
+     * line, and this is the honest substitute: the text of the rule is what a
+     * reader searches for, and it survives minification and bundling in a way a
+     * line number would not.
+     */
+    cssText: string;
+    /** Position within the sheet's own rule list, for a sheet with repeats. */
+    index: number;
+    /** The sheet's `href`, or a description of why it has none. */
+    sheet: string;
+}
+/**
+ * One thing that is wrong, with everything needed to disagree with it.
+ *
+ * **No finding without a receipt.** A rules engine makes a wrong finding cheap
+ * to add, and a check that cries wolf trains its only reader to ignore it. The
+ * `origin` and `expected` fields are what let a reader settle it in five
+ * seconds, and a finding that cannot produce them is a bug in the collector
+ * rather than a finding.
+ */
+export interface Finding {
+    /**
+     * What the collector believes the author meant, when it can tell.
+     *
+     * `| undefined` rather than the bare optional, because
+     * `exactOptionalPropertyTypes` is on and `nearest()` returns `undefined` when
+     * nothing is close enough to suggest. Writing the key as absent-or-string and
+     * then assigning `undefined` to it is the exact thing that setting exists to
+     * catch.
+     */
+    expected?: string | undefined;
+    /** Machine-readable fault class, stable across versions. */
+    kind: 'dead-hook' | 'dead-part' | 'duplicate-registration' | 'unforwarded-part' | 'unknown-tag';
+    /** 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;
+    /** The selector the fault sits in, or the tag for a runtime fault. */
+    subject: string;
+}
+/** A sheet the collector could not read, and the reason. */
+export interface Unreadable {
+    reason: 'cross-origin' | 'detached' | 'threw';
+    sheet: string;
+}
+/**
+ * How much of the page the run actually saw.
+ *
+ * `roots` counts shadow roots traversed rather than elements visited, because
+ * that is the number that moves when a component hides its styles: Helix roots
+ * are all open (Lit's default, and nothing in the library overrides `mode`), so
+ * their adopted stylesheets are readable, and a third-party closed root is a
+ * hole this reports rather than steps over.
+ */
+export interface Coverage {
+    /** Sheets whose rules were read end to end. */
+    read: number;
+    /** Shadow roots entered, including nested ones. */
+    roots: number;
+    /** Sheets found, readable or not. */
+    sheets: number;
+    /** Every sheet that could not be read, with its reason. */
+    unreadable: Unreadable[];
+}
+/** The whole result. Coverage and findings, never one without the other. */
+export interface Report {
+    coverage: Coverage;
+    findings: Finding[];
+}

package/dist/report.js

@@ -0,0 +1,13 @@
+/**
+ * What a diagnostic run returns, and why coverage is not a field beside the
+ * findings.
+ *
+ * **A bare pass is a lie this collector is structurally capable of telling.**
+ * Cross-origin stylesheets throw on `.cssRules`, and a run that could not read
+ * half its input reports the same empty array as a run that read all of it.
+ * `check:dialect` shipped in exactly that condition for weeks: green, and
+ * incapable of being anything else. So `Report` has no `findings` that can be
+ * destructured away from the `coverage` that qualifies them, and the console
+ * sink prints coverage first whether or not anything was found.
+ */
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "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.0.0-dev",
+  "license": "MIT",
+  "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
+  "repository": {
+    "directory": "helix/diagnostics",
+    "type": "git",
+    "url": "git+https://github.com/project-fusion/fusion.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test src"
+  },
+  "bugs": "https://github.com/project-fusion/fusion/issues",
+  "devDependencies": {
+    "@fusion.dev/helix-testing": "0.0.0-dev",
+    "@types/bun": "^1.3.0"
+  },
+  "homepage": "https://fusion.dev",
+  "keywords": [
+    "web-components",
+    "custom-elements",
+    "css",
+    "diagnostics",
+    "helix"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  }
+}