@fusion.dev/helix-diagnostics 0.2.0 → 0.4.0

package/dist/analyze.js

@@ -1,5 +1,4 @@
 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)) {
@@ -7,7 +6,6 @@ const targets = (selector) => {
     }
     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)) {
@@ -18,20 +16,6 @@ const parts = (selector) => {
     }
     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;
@@ -56,13 +40,6 @@ const origin = (located) => ({
     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) {
@@ -86,9 +63,6 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
                 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({
@@ -112,9 +86,6 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
                 });
             }
         }
-        /* 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) {
@@ -127,28 +98,15 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
             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;
@@ -178,23 +136,6 @@ export const analyze = (rules, tags, from, answered = new Map()) => {
     }
     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
- * `AGENTS.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;

package/dist/collect.js

@@ -1,12 +1,3 @@
-/**
- * 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;
@@ -20,22 +11,11 @@ const name = (sheet, seen, host) => {
     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;
@@ -49,8 +29,6 @@ const rules = (list, sheet, into, depth = 0, reads) => {
                     }
                 }
             }
-            /* 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);
@@ -68,14 +46,10 @@ const rules = (list, sheet, into, depth = 0, 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) {
@@ -88,15 +62,6 @@ const read = (sheet, into, unreadable, labels, depth = 0, host, reads) => {
     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;
@@ -109,17 +74,6 @@ const roots = (from, found, depth = 0) => {
         }
     }
 };
-/**
- * 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 = [];
@@ -156,11 +110,6 @@ export const collect = (from = document) => {
         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);
         }

package/dist/console.js

@@ -6,7 +6,6 @@ const line = (finding) => {
     }
     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;

package/dist/index.js

@@ -1,51 +1,9 @@
-/**
- * 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. 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.');

package/dist/manifest.js

@@ -1,26 +1,3 @@
-/**
- * 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) {
@@ -50,19 +27,6 @@ export const index = (tiers) => {
     }
     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);
@@ -75,7 +39,6 @@ export const nearest = (wrong, candidates) => {
     }
     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;

package/dist/report.js

@@ -1,13 +1 @@
-/**
- * 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.
- * `fusion prose`'s `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

@@ -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.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -23,13 +23,13 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.types.json",
     "test": "bun test src",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.2.0",
+    "@fusion.dev/helix-testing": "0.4.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",