@fusion.dev/helix-diagnostics 0.186.1 → 0.188.0

package/README.md

@@ -174,6 +174,23 @@ runs in, or the file `--config <path>` names, and refuses a setting that names
 nothing, as the page does. It exits 1 on a finding at `error`, and 3 where the
 project installs no Helix lint data. `--json` prints the run.
 
+## Run it on a page, from the command line
+
+`helix diagnostics --once <url>` opens the page headless, runs this package's
+diagnostics in it once the page holds still, prints each finding and what the
+library logged as it ran, and exits. Nothing is added to your app: the
+command serves the installed package on the page's own origin. Repeat
+`--once` for each page.
+
+```sh
+npx helix diagnostics --once http://localhost:5173/ --once http://localhost:5173/settings
+```
+
+It needs `@fusion.dev/helix-cli` and Playwright installed beside this package.
+It exits 1 on a finding at `error`, and 3 where a page could not be opened.
+`--out` writes the runs to the CI file, and `--json` prints one document a
+page. An agent gets the same runs from the MCP tool `helix_check_page`.
+
 ## Run it once, directly
 
 `diagnose()` is one run, which `initDiagnostics()` makes for you. Call it
@@ -269,7 +286,13 @@ works on it:
 | `unknown-slot` | error | A child names a slot its Helix element does not have, so it is not drawn. Found by `helix scan`, from the templates |
 | `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 |
+| `unknown-tag` | error | A rule or an element names a tag no manifest lists |
+| `unknown-event` | error | A React `on` prop on a Helix element names an event the element does not dispatch, so the handler never runs. Found by `helix scan`, from the templates |
+| `unimported-tag` | warn | An element is written and nothing in the project imports the entry that registers it, so the browser draws an unknown element. Found by `helix scan`, from the imports |
+| `disabled-attribute` | error | A rule styles a form control's `[disabled]`, which a control disabled by a `<fieldset disabled>` does not carry. Write `:disabled`. Found by `helix scan` |
+| `primitive-token` | error | A rule reads a `--_helix-` primitive, which is internal to `@fusion.dev/helix-styles`. Found by `helix scan` |
+| `unknown-token` | error | A rule reads or sets a `--helix-` name the token set does not have, so it falls back silently. Found by `helix scan` |
+| `unreflected-attribute` | warn | A rule selects a Helix element by an attribute it takes and never writes back, so it matches only markup a server wrote and nothing after a client navigation |
 | `duplicate-registration` | error | Two copies of Helix are on the page |
 | `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 |
 

package/dist/analyze.d.ts

@@ -54,8 +54,8 @@ export declare const analyze: (rules: Located[], tags: Map<string, Published>, f
  * 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.
+ * this reads `duplicateRegistrations()` and does not re-derive it, so the fact
+ * comes from where the fault starts.
  *
  * 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

package/dist/analyze.js

@@ -1,5 +1,5 @@
 import { nearest } from './manifest.js';
-import { pageOf } from './page.js';
+import { OVERLAY, pageOf } from './page.js';
 export const targets = (selector) => {
     const found = new Set();
     for (const match of selector.matchAll(/(?<![\w.#-])helix-[a-z0-9]+(?:-[a-z0-9]+)*/g)) {
@@ -153,6 +153,67 @@ const loose = (located, answerers, from, used, onPage, listedBy, readers, sugges
     }
     return findings;
 };
+const ALWAYS_WRITTEN = new Set([
+    'class',
+    'dir',
+    'hidden',
+    'id',
+    'lang',
+    'part',
+    'role',
+    'slot',
+    'style',
+    'tabindex',
+    'title',
+]);
+const SELECTS = /([^\s>+~,()]*)\[\s*([a-zA-Z][\w-]*)\s*[~^|$*]?=?[^\]]*\]/g;
+const unreflected = (selector, located, tags, from) => {
+    if (!from || !selector.includes('[')) {
+        return [];
+    }
+    const found = [];
+    const seen = new Set();
+    for (const [, compound = '', attribute = ''] of selector.matchAll(SELECTS)) {
+        if (ALWAYS_WRITTEN.has(attribute) ||
+            attribute.startsWith('aria-') ||
+            attribute.startsWith('data-') ||
+            seen.has(attribute)) {
+            continue;
+        }
+        const base = compound.replace(/\[[^\]]*\]/g, '').replace(/::?[\w-]+(\([^)]*\))?/g, '');
+        if (!base) {
+            continue;
+        }
+        let reached;
+        try {
+            reached = [...from.querySelectorAll(base)];
+        }
+        catch {
+            continue;
+        }
+        const tag = reached
+            .map((element) => element.localName)
+            .find((name) => {
+            const published = tags.get(name);
+            return (published?.reflected !== undefined &&
+                published.attributes.has(attribute) &&
+                !published.reflected.has(attribute) &&
+                !published.written.has(attribute));
+        });
+        if (!tag) {
+            continue;
+        }
+        seen.add(attribute);
+        found.push({
+            kind: 'unreflected-attribute',
+            message: `\`${selector}\` selects \`${tag}\` by \`${attribute}\`, which the element takes and never writes back to itself, so the rule matches only markup a server wrote: after a client navigation the property is set and the attribute is absent. Select a class or an attribute the element reflects, or set \`${attribute}\` as an attribute.`,
+            origin: origin(located),
+            subject: `${selector} [${attribute}]`,
+            tag,
+        });
+    }
+    return found;
+};
 const origin = (located) => ({
     cssText: located.rule.cssText,
     index: located.index,
@@ -197,6 +258,7 @@ export const analyze = (rules, tags, from, answered = new Map(), used = new Set(
         if (!selector) {
             continue;
         }
+        findings.push(...unreflected(selector, located, tags, from));
         for (const { names, tag } of selector.includes('helix-') ? parts(selector) : []) {
             const element = tags.get(tag);
             if (!element) {
@@ -402,12 +464,43 @@ const GLOBAL = new Set([
 ]);
 const PREFIXES = ['aria-', 'data-', 'on', '_ngcontent-', '_nghost-', 'ng-', 'v-', 'x-', ':', '@'];
 const HOOK_DISTANCE = 2;
+const unknownTag = (tags, tag) => {
+    if (!tag.startsWith('helix-') || tag === OVERLAY) {
+        return undefined;
+    }
+    const bare = nearest(tag.slice('helix-'.length), [...tags.keys()]
+        .filter((name) => name.startsWith('helix-'))
+        .map((name) => name.slice('helix-'.length)));
+    const suggestion = bare === undefined ? undefined : `helix-${bare}`;
+    return {
+        expected: suggestion,
+        kind: 'unknown-tag',
+        message: suggestion
+            ? `\`${tag}\` is in no manifest passed to the collector, so the browser draws it as an unknown element. The closest tag is \`${suggestion}\`.`
+            : `\`${tag}\` is in no manifest passed to the collector, so the browser draws it as an unknown element. Check the spelling, or load the package that publishes the tag.`,
+        subject: `<${tag}>`,
+        tag,
+    };
+};
 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 (!(composed || published) && tags.size > 0) {
+            const raw = unknownTag(tags, element.localName);
+            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 (published) {
             for (const { name, value } of Array.from(element.attributes)) {
                 if (GLOBAL.has(name) ||

package/dist/collect.d.ts

@@ -36,8 +36,8 @@ export interface Located {
  * 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.
+ * nothing. Two correct declarations in a site's stylesheet 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

package/dist/identity.js

@@ -1,24 +1,36 @@
 const CATEGORY = {
     'dead-hook': 'styling',
     'dead-part': 'styling',
+    'disabled-attribute': 'styling',
     'duplicate-registration': 'integrity',
     'invalid-value': 'markup',
     'manifest-skew': 'integrity',
+    'primitive-token': 'styling',
     'unforwarded-part': 'styling',
+    'unimported-tag': 'integrity',
     'unknown-attribute': 'markup',
+    'unknown-event': 'markup',
     'unknown-slot': 'markup',
     'unknown-tag': 'integrity',
+    'unknown-token': 'styling',
+    'unreflected-attribute': 'styling',
 };
 const OWNER = {
     'dead-hook': 'consumer',
     'dead-part': 'consumer',
+    'disabled-attribute': 'consumer',
     'duplicate-registration': 'consumer',
     'invalid-value': 'consumer',
     'manifest-skew': 'consumer',
+    'primitive-token': 'consumer',
     'unforwarded-part': 'helix',
+    'unimported-tag': 'consumer',
     'unknown-attribute': 'consumer',
+    'unknown-event': 'consumer',
     'unknown-slot': 'consumer',
     'unknown-tag': 'consumer',
+    'unknown-token': 'consumer',
+    'unreflected-attribute': 'consumer',
 };
 export const normalize = (subject) => subject
     .replace(/___[A-Za-z0-9_-]{5}\b/g, '')

package/dist/manifest.d.ts

@@ -36,9 +36,11 @@ export interface ManifestSource {
                 };
             }>;
             members?: Array<{
+                attribute?: string;
                 kind?: string;
                 name: string;
                 readonly?: boolean;
+                reflects?: boolean;
                 static?: boolean;
             }>;
             cssParts?: Array<{
@@ -85,6 +87,12 @@ export interface LintTag {
      * lint data written before 0.165, which a reader takes as unknown.
      */
     slots?: string[];
+    /**
+     * The attributes a property writes back to the element when it is set, so a
+     * selector on one matches however the property was set. Absent from lint data
+     * written before this field, which a reader takes as unknown.
+     */
+    reflected?: string[];
     /** The attributes the element writes on itself: one named for a read-only member. */
     written: string[];
 }
@@ -118,6 +126,11 @@ export interface Published {
     /** 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 a property writes back when it is set. Absent where a tier's
+     * lint data predates the field, which says nothing either way.
+     */
+    reflected?: Set<string> | undefined;
     /**
      * The attributes the element writes on itself: one named for a read-only
      * member, as `helix-notifications` writes `unread`. Output, so never a

package/dist/manifest.js

@@ -12,11 +12,15 @@ export const lintOf = (manifest, name) => {
                 family,
                 hooks: [],
                 parts: [],
+                reflected: [],
                 slots: [],
                 written: [],
             };
             tags[tag] = entry;
             for (const member of declaration.members ?? []) {
+                if (member.reflects && member.attribute) {
+                    entry.reflected?.push(member.attribute);
+                }
                 if (member.readonly && !member.static && member.kind === 'field') {
                     entry.written.push(member.name, member.name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`));
                 }
@@ -35,6 +39,7 @@ export const lintOf = (manifest, name) => {
         entry.parts = [...new Set(entry.parts)];
         entry.hooks = [...new Set(entry.hooks)];
         entry.slots = [...new Set(entry.slots)];
+        entry.reflected = [...new Set(entry.reflected)];
     }
     return {
         package: manifest.helix?.package ?? name,
@@ -62,6 +67,12 @@ export const index = (tiers) => {
             for (const name of entry.written) {
                 element.written.add(name);
             }
+            if (entry.reflected) {
+                element.reflected ??= new Set();
+                for (const name of entry.reflected) {
+                    element.reflected.add(name);
+                }
+            }
             for (const [name, values] of Object.entries(entry.attributes)) {
                 element.attributes.set(name, values ? new Set(values) : null);
             }

package/dist/report.d.ts

@@ -5,7 +5,7 @@
  * **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
+ * `fusion x 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.
@@ -97,7 +97,7 @@ export interface Finding {
     tag: string;
 }
 /** Every fault class, stable across versions. */
-export declare const KINDS: readonly ['dead-hook', 'dead-part', 'duplicate-registration', 'invalid-value', 'manifest-skew', 'unforwarded-part', 'unknown-attribute', 'unknown-slot', 'unknown-tag'];
+export declare const KINDS: readonly ['dead-hook', 'dead-part', 'disabled-attribute', 'duplicate-registration', 'invalid-value', 'manifest-skew', 'primitive-token', 'unforwarded-part', 'unimported-tag', 'unknown-attribute', 'unknown-event', 'unknown-slot', 'unknown-tag', 'unknown-token', 'unreflected-attribute'];
 /** A fault class. */
 export type Kind = (typeof KINDS)[number];
 /** How serious a finding is. */

package/dist/report.js

@@ -1,13 +1,19 @@
 export const KINDS = [
     'dead-hook',
     'dead-part',
+    'disabled-attribute',
     'duplicate-registration',
     'invalid-value',
     'manifest-skew',
+    'primitive-token',
     'unforwarded-part',
+    'unimported-tag',
     'unknown-attribute',
+    'unknown-event',
     'unknown-slot',
     'unknown-tag',
+    'unknown-token',
+    'unreflected-attribute',
 ];
 export const CATEGORIES = [
     'assist',

package/dist/rules.js

@@ -3,13 +3,19 @@ import { KINDS, } from './report.js';
 export const SHIPPED_RULES = {
     'dead-hook': 'error',
     'dead-part': 'error',
+    'disabled-attribute': 'error',
     'duplicate-registration': 'error',
     'invalid-value': 'error',
     'manifest-skew': 'error',
+    'primitive-token': 'error',
     'unforwarded-part': 'warn',
+    'unimported-tag': 'warn',
     'unknown-attribute': 'error',
+    'unknown-event': 'error',
     'unknown-slot': 'error',
     'unknown-tag': 'error',
+    'unknown-token': 'error',
+    'unreflected-attribute': 'warn',
 };
 const SEVERITIES = new Set(['error', 'info', 'off', 'warn']);
 export const checkRules = (rules, layer) => {

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.186.1";
+export declare const VERSION = "0.188.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.186.1';
+export const VERSION = '0.188.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.186.1",
+  "version": "0.188.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -33,7 +33,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.186.1",
+    "@fusion.dev/helix-testing": "0.188.0",
     "@types/bun": "^1.4.2"
   },
   "homepage": "https://fusion.dev",