@fusion.dev/helix-diagnostics 0.135.0 → 0.137.0

package/dist/rules.js

@@ -0,0 +1,76 @@
+import { nearest } from './manifest.js';
+import { KINDS, } from './report.js';
+export const SHIPPED_RULES = {
+    'dead-hook': 'error',
+    'dead-part': 'error',
+    'duplicate-registration': 'error',
+    'manifest-skew': 'error',
+    'unforwarded-part': 'warn',
+    'unknown-tag': 'error',
+};
+const SEVERITIES = new Set(['error', 'info', 'off', 'warn']);
+export const checkRules = (rules, layer) => {
+    for (const [kind, value] of Object.entries(rules ?? {})) {
+        if (!KINDS.includes(kind)) {
+            const close = nearest(kind, KINDS);
+            throw new Error(`The ${layer} overrides \`${kind}\`, which is no kind of finding.` +
+                (close ? ` The closest is \`${close}\`.` : ` The kinds are ${KINDS.join(', ')}.`));
+        }
+        for (const one of Array.isArray(value) ? value : [value]) {
+            const severity = typeof one === 'string' ? one : one?.severity;
+            if (!SEVERITIES.has(severity)) {
+                throw new Error(`The ${layer} sets \`${kind}\` to \`${String(severity)}\`. A severity is error, warn, info, or off.`);
+            }
+            if (typeof one === 'object' && !(Array.isArray(one.tags) && one.tags.length > 0)) {
+                throw new Error(`The ${layer} scopes \`${kind}\` with no tags. Give the tags it applies to, or set the severity alone.`);
+            }
+        }
+    }
+};
+const said = (rules, finding) => {
+    const value = rules?.[finding.kind];
+    if (value === undefined) {
+        return undefined;
+    }
+    const list = Array.isArray(value) ? value : [value];
+    const scoped = list.find((one) => typeof one === 'object' && one.tags.includes(finding.tag));
+    if (scoped && typeof scoped === 'object') {
+        return scoped.severity;
+    }
+    const plain = list.find((one) => typeof one === 'string');
+    return typeof plain === 'string' ? plain : undefined;
+};
+export const applyRules = (findings, file, argument) => {
+    const off = new Map();
+    const kept = [];
+    for (const finding of findings) {
+        let severity = SHIPPED_RULES[finding.kind];
+        let decidedBy = 'shipped';
+        for (const [layer, rules] of [
+            ['file', file],
+            ['argument', argument],
+        ]) {
+            const value = said(rules, finding);
+            if (value !== undefined) {
+                severity = value;
+                decidedBy = layer;
+            }
+        }
+        if (severity === 'off') {
+            const layer = decidedBy;
+            const key = `${finding.kind} ${layer}`;
+            const entry = off.get(key) ?? { count: 0, kind: finding.kind, layer };
+            entry.count += 1;
+            off.set(key, entry);
+            continue;
+        }
+        kept.push({ ...finding, decidedBy, severity });
+    }
+    return { findings: kept, silenced: [...off.values()] };
+};
+export const overridesOf = (file, argument) => [
+    ['file', file],
+    ['argument', argument],
+].flatMap(([layer, rules]) => Object.entries(rules ?? {}).flatMap(([kind, value]) => (Array.isArray(value) ? value : [value]).map((one) => typeof one === 'string'
+    ? { kind: kind, layer, severity: one }
+    : { kind: kind, layer, severity: one.severity, tags: one.tags })));

package/dist/usage.d.ts

@@ -0,0 +1,50 @@
+import type { Answered, Located } from './collect.js';
+import type { Published } from './manifest.js';
+import type { Usage } from './report.js';
+/** The element counts, before the stylesheets add theirs. */
+type Counted = Pick<Usage, 'axes' | 'composed' | 'slots' | 'tags'>;
+/**
+ * The Helix versions loaded on the page: every copy of core adds its own to
+ * a list under a registered symbol as it loads. Empty for a core older than
+ * 0.137, which lists nothing.
+ */
+export declare const loadedVersions: () => string[];
+/** The elements in the page now, counted once each. */
+export declare const walk: (from: Document) => Counted;
+/**
+ * The counts for the tags a manifest lists, and the rest apart as `unlisted`.
+ *
+ * Counted by prefix, since `watch()` runs before any manifest is at hand, and
+ * sorted here, where one is.
+ */
+export declare const listed: (counted: Counted, tags: Map<string, Published>) => Counted & Pick<Usage, 'unlisted'>;
+/** A running count of what renders, from `watch()`. */
+export interface Watcher {
+    /** The counts so far. A copy: counting goes on after it is read. */
+    counts(): Counted;
+    /** Stops counting, and gives the slot back to whatever held it before. */
+    stop(): void;
+}
+/**
+ * Starts counting the Helix elements that render, from now on, and the ones
+ * already in the page.
+ *
+ * Hand the watcher to `diagnose`, and its report counts every element seen
+ * since, including the ones that have gone. Without one, `diagnose` counts the
+ * elements in the page at the moment it runs, and says so.
+ *
+ * **Start it early**, before the components load where you can, so the
+ * elements an early route renders and removes are counted. The ones in the
+ * page when it starts are counted by walking the page once.
+ *
+ * Two watchers on one page both count: a second one keeps the first's
+ * listener and calls it too.
+ */
+export declare const watch: (from?: Document) => Watcher;
+/**
+ * The parts and hooks a page's stylesheets reach for, where the manifest or
+ * the element's own styles say they exist. A dead one is a finding and is not
+ * counted as use.
+ */
+export declare const styled: (rules: Located[], tags: Map<string, Published>, answered: Answered, values?: boolean) => Pick<Usage, 'hookValues' | 'hooks' | 'parts'>;
+export {};

package/dist/usage.js

@@ -0,0 +1,147 @@
+import { parts, targets } from './analyze.js';
+const SLOT = Symbol.for('fusion.dev/helix/usage');
+const AXES = ['emphasis', 'material', 'separation', 'tone'];
+const bump = (into, key, by = 1) => {
+    into[key] = (into[key] ?? 0) + by;
+};
+const under = (into, key, make) => {
+    let found = into[key];
+    if (found === undefined) {
+        found = make();
+        into[key] = found;
+    }
+    return found;
+};
+const empty = () => ({ axes: {}, composed: {}, slots: {}, tags: {} });
+export const loadedVersions = () => {
+    const listed = globalThis[Symbol.for('fusion.dev/helix/versions')];
+    return Array.isArray(listed) ? listed.filter((one) => typeof one === 'string').sort() : [];
+};
+const tally = (counted, element) => {
+    const tag = element.localName;
+    if (!tag.startsWith('helix-')) {
+        return;
+    }
+    const root = element.getRootNode();
+    const host = root instanceof ShadowRoot ? root.host.localName : '';
+    if (host.startsWith('helix-')) {
+        bump(counted.composed, tag);
+        return;
+    }
+    bump(counted.tags, tag);
+    for (const axis of AXES) {
+        const value = element.getAttribute(axis);
+        if (value !== null && value !== '') {
+            bump(under(under(counted.axes, tag, () => ({})), axis, () => ({})), value);
+        }
+    }
+    for (const child of element.children) {
+        const name = child.getAttribute('slot');
+        if (name) {
+            bump(under(counted.slots, tag, () => ({})), name);
+        }
+    }
+};
+const everyElement = (from, visit, depth = 0) => {
+    if (depth > 32) {
+        return;
+    }
+    for (const element of from.querySelectorAll('*')) {
+        visit(element);
+        if (element.shadowRoot) {
+            everyElement(element.shadowRoot, visit, depth + 1);
+        }
+    }
+};
+export const walk = (from) => {
+    const counted = empty();
+    everyElement(from, (element) => tally(counted, element));
+    return counted;
+};
+export const listed = (counted, tags) => {
+    const keep = (counts) => Object.fromEntries(Object.entries(counts).filter(([tag]) => tags.has(tag)));
+    const unlisted = {};
+    for (const counts of [counted.tags, counted.composed]) {
+        for (const [tag, count] of Object.entries(counts)) {
+            if (!tags.has(tag)) {
+                bump(unlisted, tag, count);
+            }
+        }
+    }
+    return {
+        axes: keep(counted.axes),
+        composed: keep(counted.composed),
+        slots: keep(counted.slots),
+        tags: keep(counted.tags),
+        unlisted,
+    };
+};
+export const watch = (from = document) => {
+    const counted = empty();
+    const seen = new WeakSet();
+    const see = (element) => {
+        if (!seen.has(element)) {
+            seen.add(element);
+            tally(counted, element);
+        }
+    };
+    const store = globalThis;
+    const before = store[SLOT];
+    let live = true;
+    const listener = (element) => {
+        if (live) {
+            see(element);
+        }
+        if (typeof before === 'function') {
+            before(element);
+        }
+    };
+    store[SLOT] = listener;
+    everyElement(from, see);
+    return {
+        counts: () => structuredClone(counted),
+        stop: () => {
+            live = false;
+            if (store[SLOT] === listener) {
+                store[SLOT] = before;
+            }
+        },
+    };
+};
+export const styled = (rules, tags, answered, values = true) => {
+    const counted = {
+        hooks: {},
+        hookValues: {},
+        parts: {},
+    };
+    for (const located of rules) {
+        const selector = located.rule.selectorText;
+        if (!selector?.includes('helix-')) {
+            continue;
+        }
+        for (const { names, tag } of parts(selector)) {
+            for (const name of names) {
+                if (tags.get(tag)?.parts.has(name)) {
+                    bump(under(counted.parts, tag, () => ({})), name);
+                }
+            }
+        }
+        for (const tag of targets(selector)) {
+            for (const property of Array.from(located.rule.style ?? [])) {
+                if (property.startsWith('--') &&
+                    (tags.get(tag)?.hooks.has(property) || answered.get(tag)?.has(property))) {
+                    bump(under(counted.hooks, tag, () => ({})), property);
+                    if (values) {
+                        const value = (located.rule.style?.getPropertyValue?.(property) ?? '')
+                            .trim()
+                            .slice(0, 200);
+                        if (value !== '') {
+                            bump(under(under(counted.hookValues, tag, () => ({})), property, () => ({})), value);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return counted;
+};

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The version of the package this file ships in.
+ *
+ * **Written by `fusion/scripts/version.mjs`** wherever it writes the package's
+ * `package.json`, and stamped back into the repository beside it after a
+ * 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.137.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.137.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.135.0",
+  "version": "0.137.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -29,7 +29,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-testing": "0.135.0",
+    "@fusion.dev/helix-testing": "0.137.0",
     "@types/bun": "^1.3.0"
   },
   "homepage": "https://fusion.dev",