@fusion.dev/helix-diagnostics 0.206.0 → 0.207.0

package/README.md

@@ -3,6 +3,8 @@
 Finds the Helix mistakes that are valid CSS and therefore silent: a `::part()`
 naming a part nothing publishes, a custom property named for the wrong family, a
 part a composed component never forwarded, two copies of the library on one page.
+[Diagnostics](https://fusion.dev/helix/docs/diagnostics) in the Helix
+documentation walks through the setup.
 
 ```sh
 npm install --save-dev @fusion.dev/helix-diagnostics
@@ -10,14 +12,44 @@ npm install --save-dev @fusion.dev/helix-diagnostics
 
 ## Start it in your app
 
-Call `initDiagnostics()` once, at your app's entry, before the app mounts:
+Call `initDiagnostics()` once, at your app's entry, before the app mounts. To
+keep it out of what you ship, put the call in a module of its own and load that
+module in development only:
 
 ```js
+// diagnostics.js
 import { initDiagnostics } from '@fusion.dev/helix-diagnostics'
 
-initDiagnostics({ environment: import.meta.env.MODE })
+initDiagnostics({ environment: 'development' })
 ```
 
+```js
+// main.js
+if (import.meta.env.DEV) {
+  void import('./diagnostics.js')
+}
+```
+
+`vite build` replaces `import.meta.env.DEV` with `false` and drops the import
+with it, so a production page never loads diagnostics. Next.js does the same
+with `process.env.NODE_ENV === 'development'`, and Angular with `isDevMode()`.
+Every Helix template starts diagnostics this way.
+
+To sample production pages as well, call it from the entry itself and declare
+where each build runs:
+
+```js
+import { initDiagnostics } from '@fusion.dev/helix-diagnostics'
+
+initDiagnostics({
+  environment: import.meta.env.MODE,
+  environments: { production: { sample: 0.1 } },
+})
+```
+
+`environment` takes `development`, `ci`, or `production`. Any other value, such
+as a `staging` mode, is printed in the console, and nothing starts.
+
 It needs nothing from a framework, so the call is the same wherever Helix runs:
 
 - `main.ts` in Vite, Vue, Svelte, or Solid;
@@ -35,9 +67,13 @@ so React's strict mode and hot module replacement start nothing twice.
 - **Counts from the start**, every Helix element that renders, including ones
   that go, such as a closed dialog.
 - **Loads the lint data for the exact Helix version on the page**, from a public
-  npm CDN, about 18 KB compressed for each tier. Offline, or on a locked-down
-  network, pass it yourself:
+  npm CDN, one file for each tier. Offline, or on a locked-down network, pass it
+  yourself:
   `tiers: [{ lint }]` with `import lint from '@fusion.dev/helix/lint.json'`.
+  An add-on package's lint data is passed the same way, and only that way:
+  `{ lint: sandbox }` with
+  `import sandbox from '@fusion.dev/helix-sandbox/lint.json'`. Without it,
+  each of the add-on's elements is an unknown tag.
 - **Runs itself**: after the page loads, after a navigation, and after the page
   changes, once changes stop for a second, in an idle moment, and never sooner
   than two seconds after the last run, nor sooner than twenty times its
@@ -72,7 +108,7 @@ throws stops neither the others nor the console.
 
 | Option | What it is |
 | --- | --- |
-| `environment` | `development`, `ci`, or `production`, as your build says it |
+| `environment` | `development`, `ci`, or `production`, as your build says it. Any other value is printed, and nothing starts |
 | `tiers` | Lint data or manifests to check against, where you pass them yourself |
 | `cdn` | Where lint data loads from; `false` loads nothing |
 | `page` | A function returning the page's path as your router names it, such as `/products/[id]` |
@@ -119,18 +155,22 @@ The address is always on a local host.
 - **It serves your settings.** Where you pass no `file`, the page loads
   `helix-diagnostics.json` from the directory the command runs in, so you do
   not need to import it. Pass `--config <path>` for a file elsewhere. A file
-  that does not parse is not served.
+  that does not parse is not served, and the command prints why.
 - **It writes the CI file.** With `--out reports/helix-diagnostics.json`, it
   keeps the latest run of every page there, in the shape `ciSink` writes.
 - **It takes runs from pages on a local host only**: `localhost`, `127.0.0.1`,
   `[::1]`, `*.localhost`, and `*.test`. It listens on `127.0.0.1`, so nothing
   else on your network reaches it, and production pages never send to it.
+- **It exits 3 where it cannot listen**, such as on a port another process
+  holds.
 
 ## Scan your code
 
 `helix scan` reads every stylesheet, template, and module in your repository,
 judges them against the lint data of the Helix packages you installed, and
-writes one run in the shape a page writes, with `source: "code"`:
+writes one run in the shape a page writes, with `source: "code"`. It reads the
+lint data of each installed `@fusion.dev` package that publishes `./lint.json`
+and is not private, an add-on such as `@fusion.dev/helix-sandbox` among them:
 
 ```sh
 npx helix scan
@@ -164,15 +204,22 @@ npx helix scan --build dist --out reports/helix-diagnostics.json
 - **With `--build`, it weighs your bundle**: what each Helix family and
   package adds to it, from its source maps, as `performance.weight`. Turn
   source maps on in your bundler, and pass the folder it writes the browser's
-  files to, such as `dist` or `.next/static`.
+  files to, such as `dist` or `.next/static`. A bundle's map is the one the
+  comment on its last line names, or the `.map` file beside it, so a hidden
+  map is read too.
 - **With `--out`, it writes its run to the CI file**, and keeps the runs
   `helix diagnostics` wrote there. The relay keeps the scan's run the same
   way, so the two share one file, in either order.
 
 It reads `helix-diagnostics.json` from the project, then from the directory it
 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.
+nothing, as the page does. `--json` prints the run. It exits 1 on a finding at
+`error`, and 3 where it cannot run, such as where:
+
+- no installed Helix package has lint data;
+- the settings file does not parse, or holds a setting or a value the page
+  refuses;
+- the project's folder, or the `--build` folder, does not exist.
 
 ## Run it on a page, from the command line
 
@@ -187,7 +234,9 @@ npx helix diagnostics --once http://localhost:5173/ --once http://localhost:5173
 ```
 
 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.
+It judges each page against the lint data `helix scan` reads, add-on packages'
+included. It exits 1 on a finding at `error`, and 3 where a page could not be
+opened, or where this package or Helix is not installed.
 `--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`.
 
@@ -208,7 +257,8 @@ report(diagnose({ tiers: [{ lint: styled }, { lint: headless }] }))
 every part name is unknown and every finding would be noise. It takes lint data
 or a full `custom-elements.json`. Pass both tiers when both are installed, since
 a part the headless tier publishes and the styled tier never forwarded is only
-visible with both. `report` is the console sink; the `Report` it returns is the
+visible with both. Pass an add-on package's lint data beside them, such as
+`@fusion.dev/helix-sandbox/lint.json`, for its elements. `report` is the console sink; the `Report` it returns is the
 same object, so you can send it somewhere else as well.
 
 None of these faults produces an error anywhere. They are detectable only against
@@ -252,7 +302,9 @@ A report is one run, in one shape for every sink, versioned by `schema`:
   watcher it counts every element that rendered since `watch()` began,
   including ones since removed, such as a closed dialog. Without one it counts
   the elements on the page at the moment of the run. Elements named `helix-*`
-  that no manifest lists, such as your own, are counted apart as `unlisted`.
+  that no manifest lists are counted apart as `unlisted`, and each is also an
+  `unknown-tag` finding. For a tag of your own, turn that kind off with
+  `rules: { 'unknown-tag': { severity: 'off', tags: ['helix-mine'] } }`.
 - **`configuration`**: the settings the run was made under, each override in
   effect, and how many findings each override turned off, by kind.
 - **`withheld`**: the categories your configuration turned off for sending,
@@ -280,12 +332,14 @@ works on it:
 
 | Kind | Severity | Means |
 | --- | --- | --- |
-| `dead-part` | error | A `::part()` names a part the element does not publish |
+| `dead-part` | error | A `::part()` names a part the element does not publish, or follows another `::part()`, which is not valid CSS. The browser drops a rule of the second kind before the page reads it, so `helix scan` finds it |
 | `dead-hook` | error | A hook is set where nothing answers it, or a name close to a hook is set that nothing reads |
 | `unknown-attribute` | error | A Helix element carries an attribute it does not take |
 | `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 |
+| `false-boolean` | error | A boolean attribute is written `="false"`, which turns it on: the element reads it as on wherever it is present, as `disabled` is. Remove the attribute to turn it off. An attribute that `"false"` turns off, such as Drawer's `modal`, is not one. `helix scan` leaves a framework's binding, such as Lit's `?disabled=${false}` or Vue's `:disabled="false"`, to the page, which judges what it writes |
+| `nested-interactive` | error | An interactive element is inside a button or a link, which HTML forbids: a Helix element inside a native `<button>` or an `<a>` with an `href`, or anything a person presses or types in inside a Helix element drawn inside one, such as `helix-icon-button` inside `helix-button` |
+| `unforwarded-part` | warn | The element's headless tag, such as `helix-headless-button` for `helix-button`, publishes the part and the styled tag does not forward it, which is a gap in Helix |
 | `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 |
@@ -308,6 +362,32 @@ for another route.
 attributes, `aria-*`, `data-*`, and the prefixes frameworks write are never
 findings. The markup Helix renders inside its own components is Helix's.
 
+**Nesting is judged through elements whose place the markup settles.** The
+Helix elements drawn inside a native button are Button, Icon Button, Copy
+Button, Toggle, Motion Toggle, Radio, and Tab, and Skip Link is drawn inside a
+link. A slot for actions, such as a card's `footer-actions`, holds a button
+outside anything pressable, and is not a finding. A custom element of your own,
+or a framework's component such as a router's `<Link>`, places its children
+itself, so the check stops there: `helix scan` stops at the component, and the
+page sees the `<a>` it renders.
+
+## Scope
+
+The scan and the page check what the lint data can settle. They do not check:
+
+- the value a token or a hook is set to, such as `--helix-radii-md: red`.
+  `helix scan` checks each `--helix-` name you write;
+- a selector that descends into a component, such as `helix-card .title` or
+  `helix-button span`. It matches only the elements you put inside the
+  component;
+- a `::part()` on a selector with no Helix tag in it, such as
+  `.cta::part(label)`, since the class names no element whose parts can be
+  read;
+- an attribute value an expression sets, such as `tone={tone}` in JSX or
+  `:tone` in Vue, in `helix scan`. The page judges the attribute it writes;
+- the contrast of a color you write yourself. `helix theme audit` checks the
+  theme's tokens.
+
 ## Runtime events
 
 Helix reports these itself as it runs, through one channel in
@@ -336,6 +416,7 @@ diagnostics counts it by kind and tag. None fails a CI job.
 | `missing-trigger` | A tooltip's `for` names no element in its own tree |
 | `negative-value` | An area chart was given a negative number, which it draws as none |
 | `not-a-graph` | `connectGraph` was given an element that is not a graph frame |
+| `not-a-number` | A numeric attribute holds something that is not a number, such as `page-size="1O"`, or an attribute in milliseconds something that is not a time, such as `delay="soon"`, so the property keeps its default. Development builds only (the `development` export condition) |
 | `not-a-plot` | `connectSpatialScatterChart` or `connectSpatialSurfaceChart` was given an element that is not the chart it connects |
 | `picture-in-picture-refused` | The browser refused picture in picture |
 | `refused-length` | A grid's `min` is not a length it can write, so it lays out by `columns` |
@@ -349,6 +430,7 @@ diagnostics counts it by kind and tag. None fails a CI job.
 | `typed-marks` | A quote's text starts or ends with a typed quotation mark, which the browser's marks double |
 | `unknown-event` | A React `on` prop names an event that no element dispatches. Development builds only (the `development` export condition) |
 | `unknown-icon` | An icon's `name` is not in the Helix set, so it draws nothing |
+| `unknown-language` | A sandbox editor's `language` is not a language it reads, so its source is drawn plain |
 | `unlinked-trigger` | A tooltip's trigger does not name it in `aria-describedby` |
 | `unreachable-label` | A text is rendered as a label, a deprecated value that labels no control |
 | `unregistered-part` | A part with an entry of its own, such as a filter menu, is in the page and its entry was never imported |
@@ -425,14 +507,16 @@ diagnose({
 | `detail.evidence` | `full`, `selector`, or `none` | `full` |
 | `detail.hookValues` | `true` or `false` | `true` |
 | `detail.pages` | `patterns`, `full` (the path, never the query), or `none` | `patterns` |
-| `environments.<name>` | `true` or `false`; `production` takes `{ sample }` from 0 to 1 | development and CI on |
+| `environments.<name>` | `true` or `false`, for sending runs from that environment. `production` takes `false` or `{ sample }` from 0 to 1, which is also the share of production page loads diagnostics runs on | development and CI on |
 | `project` | `key`, `name`, and `tags` | none |
 
 `send`, `detail`, and `environments` decide what the diagnostics service is
 sent, and the service is not built yet. They are recorded in every report, so a
-dashboard knows what a project withheld. The relay runs on your own machine and
-receives each run whole. A setting or a value that does not exist throws, and
-names the closest that does.
+dashboard knows what a project withheld. `environments.production` also
+decides whether diagnostics runs in production at all, and
+`environments.development` and `environments.ci` change nothing on the page.
+The relay runs on your own machine and receives each run whole. A setting or a
+value that does not exist throws, and names the closest that does.
 
 **What the page requests**: the lint data, from `cdn`, once per page load, and
 the relay, where `sinks.relay` is on. Nothing else leaves the page.

package/dist/analyze.d.ts

@@ -87,9 +87,11 @@ export declare const skew: (tags: Map<string, Published>, from: Document, page?:
  */
 export declare const versionSkew: (manifests: Record<string, string>, seen: string[]) => Raw[];
 /**
- * The attributes on the page's Helix elements that do nothing: a name the
- * element does not take, and a value outside the ones a closed set allows.
- * Both are valid HTML and silent, since the element falls back to its default.
+ * The attributes on the page's Helix elements that do nothing, or the
+ * opposite of what they say: a name the element does not take, a value
+ * outside the ones a closed set allows, and `"false"` on an attribute that is
+ * on wherever it is present. And an interactive element inside a button or a
+ * link. Each is valid to the parser and silent.
  *
  * **Only what the page wrote.** An element Helix renders inside another is
  * Helix's own markup. One finding per tag, attribute, and value, however many

package/dist/analyze.js

@@ -214,6 +214,18 @@ const unreflected = (selector, located, tags, from) => {
     }
     return found;
 };
+const headlessOf = (tag) => tag.startsWith('helix-') && !tag.startsWith('helix-headless-')
+    ? `helix-headless-${tag.slice('helix-'.length)}`
+    : undefined;
+const listed = (names) => {
+    const quoted = names.slice(0, 3).map((name) => `\`${name}\``);
+    if (names.length > 3) {
+        return `${quoted.join(', ')}, and ${names.length - 3} more`;
+    }
+    return quoted.length < 3
+        ? quoted.join(' and ')
+        : `${quoted.slice(0, 2).join(', ')}, and ${quoted[2]}`;
+};
 const origin = (located) => ({
     cssText: located.rule.cssText,
     index: located.index,
@@ -276,12 +288,12 @@ export const analyze = (rules, tags, from, answered = new Map(), used = new Set(
                 if (publishers) {
                     continue;
                 }
-                const elsewhere = [...tags].find(([other, entry]) => other !== tag && entry.parts.has(part));
-                if (elsewhere) {
+                const headless = headlessOf(tag);
+                if (headless !== undefined && tags.get(headless)?.parts.has(part)) {
                     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.`,
+                        message: `\`${tag}\` does not publish \`${part}\`, though \`${headless}\` 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})`,
                         tag,
@@ -349,7 +361,7 @@ export const analyze = (rules, tags, from, answered = new Map(), used = new Set(
                 kind: 'dead-hook',
                 message: suggestion
                     ? `\`${tag}\` does not answer \`${property}\`. It answers \`${suggestion}\`, two edits or fewer away, which is almost certainly what was meant.`
-                    : `\`${tag}\` does not answer \`${property}\`, and nothing under it that does was found in the page. ${[...answerers].sort().slice(0, 3).join(', ')} answer it, so this either targets the wrong element or expects a descendant that is not there.`,
+                    : `\`${tag}\` does not answer \`${property}\`, and nothing under it that does was found in the page. ${listed([...answerers].sort())} ${answerers.size === 1 ? 'answers' : 'answer'} it, so this either targets the wrong element or expects a descendant that is not there.`,
                 origin: origin(located),
                 subject: `${selector} { ${property} }`,
                 tag,
@@ -482,23 +494,93 @@ const unknownTag = (tags, tag) => {
         tag,
     };
 };
+const NATIVE_INTERACTIVE = {
+    a: (element) => element.hasAttribute('href'),
+    audio: (element) => element.hasAttribute('controls'),
+    button: () => true,
+    details: () => true,
+    embed: () => true,
+    iframe: () => true,
+    img: (element) => element.hasAttribute('usemap'),
+    input: (element) => (element.getAttribute('type') ?? '').toLowerCase() !== 'hidden',
+    label: () => true,
+    select: () => true,
+    textarea: () => true,
+    video: (element) => element.hasAttribute('controls'),
+};
+const enclosing = (inner, tags) => {
+    for (let at = inner.parentElement; at; at = at.parentElement) {
+        const name = at.localName;
+        const published = tags.get(name);
+        if (published?.interactive === 'button' || published?.interactive === 'link') {
+            return { element: at, noun: published.interactive };
+        }
+        if (name === 'button') {
+            return { element: at, noun: 'button' };
+        }
+        if (name === 'a' && at.hasAttribute('href')) {
+            return { element: at, noun: 'link' };
+        }
+        if (name.includes('-') && !published) {
+            return undefined;
+        }
+    }
+    return undefined;
+};
+const nested = (element, tags) => {
+    const inner = element.localName;
+    const kind = tags.get(inner)?.interactive;
+    if (kind === undefined && !NATIVE_INTERACTIVE[inner]?.(element)) {
+        return undefined;
+    }
+    const found = enclosing(element, tags);
+    if (!found) {
+        return undefined;
+    }
+    const outer = found.element.localName;
+    const helix = tags.has(outer);
+    if (!(helix || kind)) {
+        return undefined;
+    }
+    const named = (tag, article) => tags.has(tag) ? `\`${tag}\`` : `${article} \`<${tag}>\``;
+    const some = (tag) => named(tag, /^[aeiou]/.test(tag) ? 'an' : 'a');
+    const opening = some(inner);
+    const hint = outer === 'a' && kind === 'button'
+        ? ' To draw the link as a button, write `data-button` on the `<a>`.'
+        : '';
+    return {
+        kind: 'nested-interactive',
+        message: `${opening.charAt(0).toUpperCase()}${opening.slice(1)} is inside ${some(outer)}${helix ? `, which draws its content inside a native ${found.noun}` : ''}. HTML allows no interactive element inside a button or a link, and browsers and screen readers differ on what a press or a focus there does. Move ${named(inner, 'the')} out of ${named(outer, 'the')}.${hint}`,
+        subject: `<${outer}> <${inner}>`,
+        tag: helix ? outer : inner,
+    };
+};
 export const markup = (tags, from, page = pageOf(from)) => {
     const found = new Map();
+    const keep = (raw) => {
+        const key = `${raw.kind} ${raw.subject}`;
+        const seen = found.get(key);
+        if (seen) {
+            seen.count += 1;
+        }
+        else {
+            found.set(key, { ...raw, count: 1 });
+        }
+    };
     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) {
+            const raw = nested(element, tags);
+            if (raw) {
+                keep(raw);
+            }
+        }
         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 });
-                }
+                keep(raw);
             }
         }
         if (published) {
@@ -523,6 +605,14 @@ export const markup = (tags, from, page = pageOf(from)) => {
                         tag,
                     };
                 }
+                else if (published.booleans?.has(name) && value.toLowerCase() === 'false') {
+                    raw = {
+                        kind: 'false-boolean',
+                        message: `\`${name}="${value}"\` turns \`${name}\` on. \`${tag}\` reads the attribute as on wherever it is present, whatever its value. Remove the attribute to turn it off. In a framework, bind it, such as \`?${name}=\${false}\` in Lit or \`:${name}="false"\` in Vue.`,
+                        subject: `<${tag} ${name}="${value}">`,
+                        tag,
+                    };
+                }
                 else if (allows && value !== '' && !allows.has(value)) {
                     const suggestion = nearest(value, allows);
                     raw = {
@@ -534,14 +624,7 @@ export const markup = (tags, from, page = pageOf(from)) => {
                     };
                 }
                 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 });
-                    }
+                    keep(raw);
                 }
             }
         }

package/dist/config.d.ts

@@ -75,6 +75,12 @@ export declare const DEFAULTS: {
 export declare const LOCAL: RegExp;
 /** Throws on a setting that names nothing, or a value it cannot take. */
 export declare const checkConfig: (config: Config | undefined, layer: Exclude<Layer, 'shipped'>) => void;
+/**
+ * Throws on an `environment` that names none, and names the closest. Taken as
+ * declared, `staging`, which a bundler's mode hands over as readily as
+ * `development`, would run on a deployed host with the console and the relay.
+ */
+export declare const checkEnvironment: (environment: unknown) => void;
 /** The settings in effect, from the defaults, the file, and the call. */
 export interface Resolved {
     configuration: Omit<Configuration, 'overrides' | 'silenced'>;

package/dist/config.js

@@ -1,5 +1,5 @@
 import { nearest } from './manifest.js';
-import { CATEGORIES } from './report.js';
+import { CATEGORIES, ENVIRONMENTS, } from './report.js';
 import { checkRules } from './rules.js';
 export const DEFAULTS = {
     console: {
@@ -109,6 +109,14 @@ export const checkConfig = (config, layer) => {
         }
     }
 };
+export const checkEnvironment = (environment) => {
+    if (environment === undefined || ENVIRONMENTS.includes(environment)) {
+        return;
+    }
+    const close = typeof environment === 'string' ? nearest(environment, ENVIRONMENTS) : undefined;
+    throw new Error(`The argument sets \`environment\` to \`${JSON.stringify(environment)}\`. It takes ${ENVIRONMENTS.map(shown).join(', ')}.` +
+        (close ? ` The closest is \`${close}\`.` : ''));
+};
 export const resolveConfig = (file, call) => {
     checkConfig(file, 'file');
     checkConfig(call, 'argument');

package/dist/diagnose.js

@@ -1,6 +1,6 @@
 import { analyze, markup, registrations, skew, versionSkew } from './analyze.js';
 import { collect } from './collect.js';
-import { pagePattern, resolveConfig } from './config.js';
+import { checkEnvironment, pagePattern, resolveConfig } from './config.js';
 import { identify } from './identity.js';
 import { index, lintFor, versionsOf } from './manifest.js';
 import { pageOf } from './page.js';
@@ -17,6 +17,7 @@ export const diagnose = (options) => {
     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.');
     }
+    checkEnvironment(environment);
     const resolved = resolveConfig(file, call);
     const { detail } = resolved.configuration;
     const document_ = from ?? globalThis.document;

package/dist/identity.js

@@ -3,9 +3,11 @@ const CATEGORY = {
     'dead-part': 'styling',
     'disabled-attribute': 'styling',
     'duplicate-registration': 'integrity',
+    'false-boolean': 'markup',
     'invalid-value': 'markup',
     'manifest-skew': 'integrity',
     'native-element': 'guideline',
+    'nested-interactive': 'markup',
     'primitive-token': 'styling',
     'unforwarded-part': 'styling',
     'unimported-tag': 'integrity',
@@ -21,9 +23,11 @@ const OWNER = {
     'dead-part': 'consumer',
     'disabled-attribute': 'consumer',
     'duplicate-registration': 'consumer',
+    'false-boolean': 'consumer',
     'invalid-value': 'consumer',
     'manifest-skew': 'consumer',
     'native-element': 'consumer',
+    'nested-interactive': 'consumer',
     'primitive-token': 'consumer',
     'unforwarded-part': 'helix',
     'unimported-tag': 'consumer',

package/dist/init.js

@@ -1,4 +1,4 @@
-import { checkConfig, LOCAL, resolveConfig } from './config.js';
+import { checkConfig, checkEnvironment, LOCAL, resolveConfig } from './config.js';
 import { report as print } from './console.js';
 import { diagnose } from './diagnose.js';
 import { overlayOn } from './overlay.js';
@@ -56,6 +56,7 @@ const start = (options, page) => {
     const { cdn = CDN, duplicates, environment, file, onReport, page: route, tiers, ...call } = options;
     let resolved;
     try {
+        checkEnvironment(environment);
         resolved = resolveConfig(file, call);
     }
     catch (error) {

package/dist/manifest.d.ts

@@ -35,8 +35,21 @@ export interface ManifestSource {
                     text?: string;
                 };
             }>;
+            /**
+             * Helix's own fields: `interactive`, the native control the element
+             * draws its content inside, from `@interactive`, and `family`, the family
+             * an element joins from another package, from `@family`.
+             */
+            helix?: {
+                family?: string;
+                interactive?: string;
+            };
             members?: Array<{
                 attribute?: string;
+                /** How the attribute turns a boolean property on, where it is one. */
+                helix?: {
+                    boolean?: string;
+                };
                 kind?: string;
                 name: string;
                 readonly?: boolean;
@@ -78,9 +91,26 @@ export interface LintData {
 export interface LintTag {
     /** Each attribute, with the values it allows, or `null` where it takes any. */
     attributes: Record<string, string[] | null>;
-    /** The family, from the module's path. */
+    /**
+     * The attributes that are on wherever they are present, `"false"`
+     * included: each turns on a boolean property Lit reads with
+     * `type: Boolean`. Absent from lint data written before this field, which a
+     * reader takes as unknown.
+     */
+    booleans?: string[];
+    /** The family, from `@family` or else from the module's path. */
     family?: string | undefined;
     hooks: string[];
+    /**
+     * What a person presses or types in, where the element is one: `button` or
+     * `link` for an element that draws its content inside its own native button
+     * or link, and `control` for any other form control. Absent where the
+     * element is neither. **Typed as any `string`**: a page passes the
+     * `lint.json` it imports, and TypeScript reads every string in an imported
+     * JSON file as `string`, so the {@link Interactive} union here refused every
+     * page's `{ lint }`. `index` keeps only the kinds it knows.
+     */
+    interactive?: string;
     parts: string[];
     /**
      * The slots the element has, by name, the default one as `""`. Absent from
@@ -96,6 +126,12 @@ export interface LintTag {
     /** The attributes the element writes on itself: one named for a read-only member. */
     written: string[];
 }
+/**
+ * What a person presses or types in: an element drawn inside a native
+ * `button` or `link`, which HTML allows no interactive element inside, or
+ * another form `control`.
+ */
+export type Interactive = 'button' | 'control' | 'link';
 /**
  * One installed tier: its manifest, with the package name, or its lint data,
  * which names the package itself.
@@ -123,9 +159,17 @@ export interface Published {
      * is a union of string literals, and `null` where it takes any value.
      */
     attributes: Map<string, Set<string> | null>;
+    /**
+     * The attributes that are on wherever they are present, `"false"`
+     * included. Absent where a tier's lint data predates the field, which says
+     * nothing either way.
+     */
+    booleans?: Set<string> | undefined;
     /** The family, from the module's path: `button` for `src/button/root/button-root.ts`. */
     family?: string | undefined;
     hooks: Map<string, Set<string>>;
+    /** What a person presses or types in, where the element is one. */
+    interactive?: Interactive | undefined;
     /**
      * 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.

package/dist/manifest.js

@@ -1,7 +1,8 @@
+const isInteractive = (kind) => kind === 'button' || kind === 'control' || kind === 'link';
 export const lintOf = (manifest, name) => {
     const tags = {};
     for (const module of manifest.modules ?? []) {
-        const family = /^src\/([^/]+)\//.exec(module.path ?? '')?.[1];
+        const folder = /^src\/([^/]+)\//.exec(module.path ?? '')?.[1];
         for (const declaration of module.declarations ?? []) {
             const tag = declaration.tagName;
             if (!tag) {
@@ -9,7 +10,8 @@ export const lintOf = (manifest, name) => {
             }
             const entry = tags[tag] ?? {
                 attributes: {},
-                family,
+                booleans: [],
+                family: declaration.helix?.family ?? folder,
                 hooks: [],
                 parts: [],
                 reflected: [],
@@ -17,10 +19,20 @@ export const lintOf = (manifest, name) => {
                 written: [],
             };
             tags[tag] = entry;
+            const drawn = declaration.helix?.interactive;
+            if (drawn === 'button' || drawn === 'link') {
+                entry.interactive = drawn;
+            }
+            else if ((declaration.members ?? []).some((member) => member.name === 'form' && member.kind === 'field' && !member.static)) {
+                entry.interactive = 'control';
+            }
             for (const member of declaration.members ?? []) {
                 if (member.reflects && member.attribute) {
                     entry.reflected?.push(member.attribute);
                 }
+                if (member.attribute && member.helix?.boolean === 'present') {
+                    entry.booleans?.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()}`));
                 }
@@ -40,6 +52,7 @@ export const lintOf = (manifest, name) => {
         entry.hooks = [...new Set(entry.hooks)];
         entry.slots = [...new Set(entry.slots)];
         entry.reflected = [...new Set(entry.reflected)];
+        entry.booleans = [...new Set(entry.booleans)];
     }
     return {
         package: manifest.helix?.package ?? name,
@@ -67,6 +80,15 @@ export const index = (tiers) => {
             for (const name of entry.written) {
                 element.written.add(name);
             }
+            if (isInteractive(entry.interactive)) {
+                element.interactive ??= entry.interactive;
+            }
+            if (entry.booleans) {
+                element.booleans ??= new Set();
+                for (const name of entry.booleans) {
+                    element.booleans.add(name);
+                }
+            }
             if (entry.reflected) {
                 element.reflected ??= new Set();
                 for (const name of entry.reflected) {

package/dist/report.d.ts

@@ -50,8 +50,9 @@ export interface Origin {
 export interface Finding {
     /**
      * What the fault is about: `styling` for parts and hooks, `markup` for
-     * attributes and slots, `integrity` for the page and the library
-     * disagreeing, `guideline` for advice. A dashboard groups by it.
+     * attributes, slots, and what an element holds, `integrity` for the page
+     * and the library disagreeing, `guideline` for advice. A dashboard groups
+     * by it.
      */
     category: FindingCategory;
     /**
@@ -97,7 +98,7 @@ export interface Finding {
     tag: string;
 }
 /** Every fault class, stable across versions. */
-export declare const KINDS: readonly ['dead-hook', 'dead-part', 'disabled-attribute', 'duplicate-registration', 'invalid-value', 'manifest-skew', 'native-element', 'primitive-token', 'unforwarded-part', 'unimported-tag', 'unknown-attribute', 'unknown-event', 'unknown-slot', 'unknown-tag', 'unknown-token', 'unreflected-attribute'];
+export declare const KINDS: readonly ['dead-hook', 'dead-part', 'disabled-attribute', 'duplicate-registration', 'false-boolean', 'invalid-value', 'manifest-skew', 'native-element', 'nested-interactive', '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. */
@@ -199,8 +200,10 @@ export interface RuntimeEntry {
     /** The tag of the element it happened on, where there is one. */
     tag?: string;
 }
+/** Where a run can be declared to happen. */
+export declare const ENVIRONMENTS: readonly ['ci', 'development', 'production'];
 /** Where a run was declared to happen. Undeclared is never sent. */
-export type Environment = 'ci' | 'development' | 'production';
+export type Environment = (typeof ENVIRONMENTS)[number];
 /**
  * A sheet the collector could not read, and the reason. For a scan, a file
  * that did not parse is `threw`, and a stylesheet in a language the scan does

package/dist/report.js

@@ -3,9 +3,11 @@ export const KINDS = [
     'dead-part',
     'disabled-attribute',
     'duplicate-registration',
+    'false-boolean',
     'invalid-value',
     'manifest-skew',
     'native-element',
+    'nested-interactive',
     'primitive-token',
     'unforwarded-part',
     'unimported-tag',
@@ -25,3 +27,4 @@ export const CATEGORIES = [
     'runtime',
     'usage',
 ];
+export const ENVIRONMENTS = ['ci', 'development', 'production'];

package/dist/rules.js

@@ -5,9 +5,11 @@ export const SHIPPED_RULES = {
     'dead-part': 'error',
     'disabled-attribute': 'error',
     'duplicate-registration': 'error',
+    'false-boolean': 'error',
     'invalid-value': 'error',
     'manifest-skew': 'error',
     'native-element': 'warn',
+    'nested-interactive': 'error',
     'primitive-token': 'error',
     'unforwarded-part': 'warn',
     'unimported-tag': 'warn',

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

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.206.0';
+export const VERSION = '0.207.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.206.0",
+  "version": "0.207.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -20,7 +20,8 @@
     "./ci": {
       "types": "./dist/ci.d.ts",
       "default": "./dist/ci.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"
@@ -33,7 +34,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.206.0",
+    "@fusion.dev/helix-testing": "0.207.0",
     "@types/bun": "^1.4.2"
   },
   "homepage": "https://fusion.dev",