@fusion.dev/helix-diagnostics 0.186.0 → 0.187.0

package/README.md

@@ -269,7 +269,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.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/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.0";
+export declare const VERSION = "0.187.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.186.0';
+export const VERSION = '0.187.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.0",
+  "version": "0.187.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.0",
+    "@fusion.dev/helix-testing": "0.187.0",
     "@types/bun": "^1.4.2"
   },
   "homepage": "https://fusion.dev",