@prongsjs/ui 0.0.0-stage → 0.3.0

package/dist/tooling/index.js

@@ -0,0 +1,540 @@
+import { twMerge } from 'tailwind-merge';
+import { classSimilarity, isTextStyleClass, isVisualClass, splitClasses, stripVariants } from '../classes.js';
+import { domainOf } from '@prongsjs/core';
+import { componentFor } from '../vocabulary.js';
+import { analyzeFile, hasMarker } from './analyze.js';
+import { describeBinding, groupByComponent, uiReferenceSection, uiSpecSection, uiUsage } from './spec.js';
+const LEAVES = ['Text', 'Action', 'Field', 'Media', 'Dialog', 'Popover'];
+const BOX_TAGS = new Set(['div', 'section', 'aside', 'article', 'header', 'footer', 'nav', 'main', 'ul', 'ol', 'li', 'form']);
+/** Classes that give a box its own surface: fill, border, corners, shadow. */
+const SURFACE = /^(bg-(?!transparent$|none$)|border(?!-0$|-none$|-transparent$|-collapse$|-separate$|-spacing)|rounded|shadow(?!-none$)|ring-(?!0$)|backdrop-|card-)/;
+/** Inline style properties that change how something looks (layout properties are fine). */
+const VISUAL_STYLE = /^(color|background|backgroundColor|backgroundImage|border|border(Top|Right|Bottom|Left)?(Color|Width|Style)?|borderRadius|boxShadow|outline|font|fontSize|fontWeight|fontFamily|fontStyle|lineHeight|letterSpacing|textDecoration|textTransform|opacity|filter)$/;
+const TEXT_TAGS = new Set(['p', 'span', 'label', 'small', 'strong', 'em', 'li', 'blockquote']);
+const TEXT_INPUT_TYPES = new Set(['text', 'email', 'password', 'search', 'number', 'url', 'tel']);
+/** A colour written as a value instead of a token: `bg-[#e5383b]`, `[color:rgb(0_0_0)]`. */
+const LITERAL_COLOR = /\[[^\]]*(#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb)\()/i;
+/** A colour from Tailwind's palette, which a theme cannot change: `text-sky-700`. White and black are allowed. */
+const PALETTE_COLOR = /^(?:bg|text|border(?:-[trblxyse])?|ring|ring-offset|outline|fill|stroke|divide|placeholder|accent|caret|decoration|from|via|to|shadow|inset-shadow)-(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}(?:\/\d+)?$/;
+/** Variables Tailwind itself provides (its theme namespaces and internals). */
+const TAILWIND_VARIABLE = /^--(?:tw-|color-|spacing|font-|text-|leading-|tracking-|radius-|shadow-|inset-shadow-|drop-shadow-|blur-|breakpoint-|container-|ease-|animate-|perspective-|aspect-|default-)/;
+const STYLESHEET = /\.(css|scss|sass|less)$/;
+/** The document root and inline SVG may carry classes; icons are not looks an intent owns. */
+const FREE_TAGS = new Set(['html', 'body', 'svg', 'path', 'g', 'circle', 'ellipse', 'rect', 'line', 'polyline', 'polygon', 'defs', 'use', 'mask', 'clipPath', 'br', 'option']);
+/** Classes that change behaviour or motion but no look of their own. */
+const INERT = /^(group|peer)(\/[\w-]+)?$|^(cursor-|select-|pointer-events-|transition|duration-|ease-|delay-|appearance-|list-|will-change-|touch-|outline-none$|resize|snap-|scroll-smooth$|isolate$|surface-page$|\[scrollbar-)/;
+/** A selector or Tailwind variant that matches elements by their intent: [data-intent=...], data-[intent=...]. */
+const INTENT_SELECTOR = /\[\s*data-intent\b|data-\[intent\b/;
+/** How many times a Layout tweak repeats before it counts as a missing intent. */
+const REPEATED_TWEAK = 3;
+/** Elements that change what a region does, so an intent rendering one is no stand-in for a plain box. */
+const BEHAVIOUR_TAGS = new Set(['form', 'table', 'ul', 'ol', 'li', 'hr', 'details', 'main', 'nav', 'header', 'footer', 'figure', 'aside']);
+/** The class strings in a registry module, with where each starts. */
+function registryClassStrings(text) {
+    const found = [];
+    for (const m of text.matchAll(/classes:\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1/g)) {
+        found.push({ value: m[2], offset: m.index + m[0].indexOf(m[1]) });
+    }
+    return found;
+}
+function strings(site, attr) {
+    const value = site.attrs.get(attr);
+    return value?.kind === 'strings' ? value.values : null;
+}
+function classesOf(site) {
+    return (strings(site, 'className') ?? []).flatMap(splitClasses);
+}
+/** Which component should replace a raw element, or undefined when the element is fine as is. */
+function replacementFor(site) {
+    const classes = classesOf(site);
+    if (site.nextLink || site.tag === 'a')
+        return classes.some(isVisualClass) ? 'Action' : undefined;
+    if (site.tag === 'button')
+        return 'Action';
+    if (/^h[1-6]$/.test(site.tag))
+        return 'Text';
+    if (site.tag === 'textarea' || site.tag === 'select')
+        return 'Field';
+    if (site.tag === 'img')
+        return site.attrs.has('className') ? 'Media' : undefined;
+    if (site.tag === 'dialog')
+        return 'Dialog';
+    if (site.attrs.has('popover'))
+        return 'Popover';
+    if (site.tag === 'input') {
+        const type = strings(site, 'type')?.[0] ?? 'text';
+        return TEXT_INPUT_TYPES.has(type) ? 'Field' : undefined;
+    }
+    if (TEXT_TAGS.has(site.tag))
+        return classes.some(isTextStyleClass) ? 'Text' : undefined;
+    return undefined;
+}
+/** Lowercase words from code: `toggleSave(item)` -> toggle, save, item. */
+function words(text) {
+    return new Set((text ?? '')
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z]+/)
+        .filter((w) => w.length > 2));
+}
+/** True when the code mentions `word` or a close inflection of it (share/shared/sharing). */
+function mentions(found, word) {
+    if (found.has(word))
+        return true;
+    // Prefix matching only for real stems; "see" must not match "set".
+    const stem = word.length > 4 ? word.replace(/e$/, '') : word;
+    if (stem.length < 4)
+        return false;
+    return [...found].some((w) => w.startsWith(stem) && w.length - stem.length <= 3);
+}
+/** Call-site intents for a component, ranked by how closely they match an element. */
+function rankIntents(registry, component, site, limit = 2) {
+    const classes = classesOf(site);
+    const type = strings(site, 'type')?.[0];
+    return registry.ids
+        .filter((id) => !registry.isInternal(id) && componentFor(id) === component)
+        .map((id) => {
+        const binding = registry.resolve(id).binding;
+        const similarity = classSimilarity(classes, splitClasses(binding.classes));
+        let score = similarity;
+        if (binding.element === site.tag)
+            score += 0.5;
+        if (type && binding.behavior?.type === type)
+            score += 0.5;
+        if (site.nextLink && id === 'action.navigate')
+            score += 0.3;
+        return { id, score, similarity };
+    })
+        .filter(({ score }) => score > 0)
+        // On a tie, the intent whose classes match more closely wins over one that only shares the element.
+        .sort((a, b) => b.score - a.score || b.similarity - a.similarity || a.id.localeCompare(b.id))
+        .slice(0, limit)
+        .map(({ id }) => id);
+}
+export function createUiTooling(options) {
+    const componentsDir = options.componentsDir.replace(/\/+$/, '');
+    const cli = options.cli ?? 'npx prongs';
+    const suggestIntent = (registry, id) => ({
+        intent: id,
+        component: componentFor(id),
+        text: registry.defs[id].description,
+    });
+    const violation = (ctx, site, rule, severity, message, suggestions = [], extra = {}) => ({
+        rule,
+        severity,
+        path: ctx.file.path,
+        line: site.line,
+        column: site.offset - ctx.file.text.lastIndexOf('\n', site.offset - 1),
+        snippet: (ctx.file.text.split('\n')[site.line - 1] ?? '').trim(),
+        message,
+        suggestions,
+        ...extra,
+    });
+    const registryPath = options.registryPath ? options.registryPath.replace(/^\.\//, '') : undefined;
+    /** One violation per class string in the registry that `offending` finds something in. */
+    const registryViolations = (ctx, rule, severity, offending, message) => {
+        if (ctx.file.path !== registryPath)
+            return [];
+        const lines = ctx.file.text.split('\n');
+        return registryClassStrings(ctx.file.text).flatMap(({ value, offset }) => {
+            const found = offending(splitClasses(value), value);
+            if (found.length === 0)
+                return [];
+            const line = ctx.file.text.slice(0, offset).split('\n').length;
+            return [{
+                    rule,
+                    severity,
+                    path: ctx.file.path,
+                    line,
+                    column: offset - ctx.file.text.lastIndexOf('\n', offset - 1),
+                    snippet: (lines[line - 1] ?? '').trim(),
+                    message: message(found),
+                    suggestions: [],
+                    data: { found },
+                }];
+        });
+    };
+    const sitesOf = (ctx) => {
+        if (!/\.[jt]sx$/.test(ctx.file.path))
+            return [];
+        const analysis = analyzeFile(ctx.file, componentsDir);
+        return analysis.sites
+            .filter((site) => !hasMarker(analysis, site.line, 'ignore'))
+            .map((site) => ({ site, analysis }));
+    };
+    const rules = [
+        {
+            id: 'domain-mismatch',
+            run(ctx) {
+                return sitesOf(ctx).flatMap(({ site }) => {
+                    if (!site.component)
+                        return [];
+                    return (strings(site, 'intent') ?? [])
+                        .filter((id) => ctx.registry.has(id) && !ctx.registry.isInternal(id))
+                        .filter((id) => componentFor(id) !== site.component)
+                        .map((id) => violation(ctx, site, 'domain-mismatch', 'error', `<${site.component}> cannot render "${id}"; use <${componentFor(id)}>.`, [
+                        { component: componentFor(id), intent: id, text: `<${componentFor(id)} intent="${id}">` },
+                    ], { intent: id }));
+                });
+            },
+        },
+        {
+            id: 'dynamic-intent',
+            run(ctx) {
+                return sitesOf(ctx)
+                    .filter(({ site }) => site.component && site.attrs.get('intent')?.kind === 'dynamic')
+                    .map(({ site }) => violation(ctx, site, 'dynamic-intent', 'info', 'Intent is computed at runtime, so it was not checked. Prefer literal intents or a ternary of literals.'));
+            },
+        },
+        {
+            id: 'leaf-classname',
+            run(ctx) {
+                return sitesOf(ctx)
+                    .filter(({ site }) => site.component && LEAVES.includes(site.component) && site.attrs.has('className'))
+                    .map(({ site }) => violation(ctx, site, 'leaf-classname', 'error', `<${site.component}> takes no className. Use its layout props (align, width, hideBelow, showBelow, truncate, nowrap), wrap it in a <Layout>, or change the intent.`, [], { intent: strings(site, 'intent')?.[0], data: { classes: classesOf(site) } }));
+            },
+        },
+        {
+            id: 'leaf-style',
+            run(ctx) {
+                return sitesOf(ctx)
+                    .filter(({ site }) => site.component && LEAVES.includes(site.component) && site.attrs.has('style'))
+                    .map(({ site }) => violation(ctx, site, 'leaf-style', 'error', `<${site.component}> takes no style: an inline style overrides the intent just like a className. Pick or add an intent that looks right.`, [], { intent: strings(site, 'intent')?.[0] }));
+            },
+        },
+        {
+            id: 'layout-visual-class',
+            run(ctx) {
+                return sitesOf(ctx).flatMap(({ site }) => {
+                    if (site.component !== 'Layout')
+                        return [];
+                    const visual = classesOf(site).filter(isVisualClass);
+                    if (visual.length === 0)
+                        return [];
+                    const intent = strings(site, 'intent')?.[0];
+                    return [
+                        violation(ctx, site, 'layout-visual-class', 'error', `Layout className may only hold layout and spacing classes; "${visual.join(' ')}" changes the look.`, intent
+                            ? [{
+                                    text: 'Give this region its own intent',
+                                    command: `${cli} add-intent layout.<name> --refs ${intent} --classes "${visual.join(' ')}" --description "..."`,
+                                }]
+                            : [], { intent, data: { classes: visual } }),
+                    ];
+                });
+            },
+        },
+        {
+            id: 'unsafe-classname',
+            run(ctx) {
+                return sitesOf(ctx).flatMap(({ site, analysis }) => {
+                    if (!site.component || !site.attrs.has('unsafeClassName'))
+                        return [];
+                    const classes = (strings(site, 'unsafeClassName') ?? []).flatMap(splitClasses);
+                    const intent = strings(site, 'intent')?.[0];
+                    const reasoned = hasMarker(analysis, site.line, 'unsafe');
+                    return [
+                        violation(ctx, site, 'unsafe-classname', reasoned ? 'warning' : 'error', reasoned
+                            ? `unsafeClassName "${classes.join(' ')}" bypasses the intent.`
+                            : 'unsafeClassName needs a `prongs-unsafe: <reason>` comment on the line above.', intent
+                            ? [{
+                                    text: 'If this repeats, make it an intent',
+                                    command: `${cli} add-intent ${intent.split('.')[0]}.<name> --refs ${intent} --classes "${classes.join(' ')}" --description "..."`,
+                                }]
+                            : [], { intent, data: { classes } }),
+                    ];
+                });
+            },
+        },
+        {
+            id: 'raw-style',
+            run(ctx) {
+                return sitesOf(ctx).flatMap(({ site }) => {
+                    if (site.component && site.component !== 'Layout')
+                        return []; // leaf components reject style outright
+                    const visual = (site.styleKeys ?? []).filter((k) => !k.startsWith('--') && VISUAL_STYLE.test(k));
+                    if (visual.length === 0)
+                        return [];
+                    return [
+                        violation(ctx, site, 'raw-style', 'error', `Inline style sets how this looks (${visual.join(', ')}). Looks belong to intents; pass values that come from data as CSS variables (vars={{ '--x': value }} on Prongs components).`, [], { data: { tag: site.component ?? site.tag, styleKeys: visual } }),
+                    ];
+                });
+            },
+        },
+        {
+            id: 'raw-surface',
+            run(ctx) {
+                return sitesOf(ctx).flatMap(({ site }) => {
+                    if (site.component || !BOX_TAGS.has(site.tag))
+                        return [];
+                    const surface = classesOf(site).filter((c) => SURFACE.test(stripVariants(c)));
+                    if (surface.length === 0)
+                        return [];
+                    const ranked = rankIntents(ctx.registry, 'Layout', site);
+                    return [
+                        violation(ctx, site, 'raw-surface', 'error', `<${site.tag}> draws its own surface (${surface.join(' ')}); use <Layout> with an intent that says what this region is.`, ranked.length ? ranked.map((id) => suggestIntent(ctx.registry, id)) : [{ component: 'Layout', text: '<Layout intent="...">' }], { data: { tag: site.tag, component: 'Layout', classes: classesOf(site) } }),
+                    ];
+                });
+            },
+        },
+        {
+            id: 'name-mismatch',
+            run(ctx) {
+                const { registry } = ctx;
+                return sitesOf(ctx).flatMap(({ site }) => {
+                    if (site.component !== 'Action')
+                        return [];
+                    const used = strings(site, 'intent')?.[0];
+                    if (!used || !registry.has(used) || registry.isInternal(used))
+                        return [];
+                    // Only actions are named by verbs; nav and choice labels name destinations and options.
+                    if (domainOf(used) !== 'action')
+                        return [];
+                    // A link's text names where it goes ("Create one" -> /create), not an action.
+                    if (used === 'action.navigate' && site.attrs.has('href'))
+                        return [];
+                    const said = [site.handlerText, site.childText, ...(strings(site, 'aria-label') ?? []), ...(strings(site, 'label') ?? [])];
+                    const found = words(said.filter(Boolean).join(' '));
+                    if (found.size === 0)
+                        return [];
+                    // The meaning word plus keywords, inherited through refs, so action.bookmark.reader
+                    // answers to everything action.bookmark does. Variant words ("item") are not signals.
+                    const signals = (id, seen = new Set()) => {
+                        if (seen.has(id) || !registry.has(id))
+                            return [];
+                        seen.add(id);
+                        const def = registry.defs[id];
+                        return [
+                            id.split('.')[1],
+                            ...(def.keywords ?? []),
+                            ...(def.refs ?? []).filter((r) => domainOf(r) === domainOf(id)).flatMap((r) => signals(r, seen)),
+                        ];
+                    };
+                    if (signals(used).some((w) => mentions(found, w)))
+                        return [];
+                    const better = registry.ids.filter((id) => id !== used &&
+                        !registry.isInternal(id) &&
+                        domainOf(id) === domainOf(used) &&
+                        signals(id).some((w) => mentions(found, w)));
+                    if (better.length === 0)
+                        return [];
+                    return [
+                        violation(ctx, site, 'name-mismatch', 'warning', `The code says "${[...found].join(' ')}", which points to ${better.join(' or ')}, not ${used}.`, better.map((id) => suggestIntent(registry, id)), { intent: used }),
+                    ];
+                });
+            },
+        },
+        {
+            id: 'raw-value',
+            run(ctx) {
+                const inRegistry = registryViolations(ctx, 'raw-value', 'warning', (classes) => classes.filter((c) => LITERAL_COLOR.test(c) || PALETTE_COLOR.test(stripVariants(c))), (found) => `${found.join(' ')} ${found.length === 1 ? 'is a colour' : 'are colours'} the theme cannot change. Use a token (text-destructive, bg-surface-hover, var(--success)), or declare one in your CSS.`);
+                // A CSS variable may carry a value from data, but not a colour fixed in code.
+                const inVars = sitesOf(ctx).flatMap(({ site }) => (site.colorVars ?? []).map((found) => violation(ctx, site, 'raw-value', 'warning', `${found.name} in ${found.attr} is set to the colour ${found.value}, which the theme cannot change. Fixed colours belong in your theme as tokens; vars and style are for values that come from data.`, [], { data: found })));
+                return [...inRegistry, ...inVars];
+            },
+        },
+        {
+            id: 'unknown-token',
+            run(ctx) {
+                const tokens = options.tokens;
+                if (!tokens || tokens.size === 0)
+                    return [];
+                // Variables a registry class sets itself, like [--primary:var(--destructive)].
+                const local = new Set([...ctx.file.text.matchAll(/\[(--[\w-]+):/g)].map((m) => m[1]));
+                return registryViolations(ctx, 'unknown-token', 'error', (_, value) => 
+                // A var() with a fallback is optional on purpose (a value passed through `vars` only sometimes).
+                [...new Set([...value.matchAll(/(?:var\(|-\()(--[\w-]+)(?![\w-]|\s*,)/g)].map((m) => m[1]))].filter((name) => !tokens.has(name) && !local.has(name) && !TAILWIND_VARIABLE.test(name)), (found) => `${found.join(', ')} ${found.length === 1 ? 'is' : 'are'} not declared in any CSS file or passed through \`vars\`, so ${found.length === 1 ? 'it resolves' : 'they resolve'} to nothing. Fix the name or declare it in your theme.`);
+            },
+        },
+        {
+            id: 'intent-selector',
+            run(ctx) {
+                const message = 'Styles an element by its data-intent. data-intent is for finding elements (analytics, tests, A/B tools), not styling them: change the look in the registry, or add an intent.';
+                if (STYLESHEET.test(ctx.file.path)) {
+                    const lines = ctx.file.text.split('\n');
+                    let inComment = false;
+                    return lines.flatMap((text, index) => {
+                        // Comments may mention data-intent; strip them before looking for selectors.
+                        let code = '';
+                        for (let i = 0; i < text.length; i++) {
+                            if (inComment) {
+                                if (text.startsWith('*/', i))
+                                    (inComment = false), i++;
+                            }
+                            else if (text.startsWith('/*', i))
+                                (inComment = true), i++;
+                            else
+                                code += text[i];
+                        }
+                        const column = code.search(INTENT_SELECTOR);
+                        if (column < 0)
+                            return [];
+                        return [{ rule: 'intent-selector', severity: 'error', path: ctx.file.path, line: index + 1, column: column + 1, snippet: text.trim(), message, suggestions: [] }];
+                    });
+                }
+                const inRegistry = registryViolations(ctx, 'intent-selector', 'error', (classes) => classes.filter((c) => INTENT_SELECTOR.test(c)), () => message);
+                const inJsx = sitesOf(ctx).flatMap(({ site }) => {
+                    const classes = [...classesOf(site), ...(strings(site, 'unsafeClassName') ?? []).flatMap(splitClasses)].filter((c) => INTENT_SELECTOR.test(c));
+                    return classes.length ? [violation(ctx, site, 'intent-selector', 'error', message, [], { data: { classes } })] : [];
+                });
+                return [...inRegistry, ...inJsx];
+            },
+        },
+        {
+            id: 'raw-look',
+            run(ctx) {
+                return sitesOf(ctx).flatMap(({ site }) => {
+                    if (site.component || site.nextLink || !/^[a-z]/.test(site.tag) || FREE_TAGS.has(site.tag))
+                        return [];
+                    // raw-element and raw-surface already report these.
+                    if (replacementFor(site))
+                        return [];
+                    const classes = classesOf(site);
+                    if (BOX_TAGS.has(site.tag) && classes.some((c) => SURFACE.test(stripVariants(c))))
+                        return [];
+                    const looks = classes.filter((c) => isVisualClass(c) && !INERT.test(stripVariants(c)));
+                    if (looks.length === 0)
+                        return [];
+                    const component = looks.some(isTextStyleClass) && !looks.some((c) => SURFACE.test(stripVariants(c))) ? 'Text' : 'Layout';
+                    return [
+                        violation(ctx, site, 'raw-look', 'error', `<${site.tag}> sets its own look (${looks.join(' ')}). Give it an intent: <${component} intent="...">, or Media for frames and images. A justified exception takes // prongs-ignore: <reason>.`, [{ component, text: `<${component} intent="...">` }], { data: { tag: site.tag, component, classes: looks } }),
+                    ];
+                });
+            },
+        },
+        {
+            id: 'raw-element',
+            run(ctx) {
+                return sitesOf(ctx).flatMap(({ site }) => {
+                    if (site.component)
+                        return [];
+                    const component = replacementFor(site);
+                    if (!component)
+                        return [];
+                    const name = site.nextLink ? 'Link' : `<${site.tag}>`;
+                    const ranked = rankIntents(ctx.registry, component, site);
+                    return [
+                        violation(ctx, site, 'raw-element', 'error', `${site.nextLink ? '<Link>' : name} with its own styling; use <${component}> with an intent.`, ranked.length ? ranked.map((id) => suggestIntent(ctx.registry, id)) : [{ component, text: `<${component} intent="...">` }], { data: { tag: site.nextLink ? 'Link' : site.tag, component, classes: classesOf(site) } }),
+                    ];
+                });
+            },
+        },
+    ];
+    /** How a box lays out its children, at the base breakpoint. */
+    const directionOf = (classes) => {
+        const base = new Set(classes);
+        if (base.has('grid'))
+            return 'grid';
+        if (base.has('flex-col'))
+            return 'column';
+        return base.has('flex') || base.has('inline-flex') ? 'row' : 'block';
+    };
+    /**
+     * Layout intents that already carry the tweak: same direction once the tweak applies, the same
+     * element or a plain one, and no look of their own beyond the tweaked intent's.
+     */
+    const intentsWithTweak = (registry, intent, classes) => {
+        const own = registry.resolve(intent).binding;
+        const wanted = splitClasses(twMerge(own.classes, classes.join(' ')));
+        const ownLooks = new Set(splitClasses(own.classes).filter(isVisualClass));
+        return registry.ids
+            .filter((id) => id !== intent && !registry.isInternal(id) && componentFor(id) === 'Layout')
+            .map((id) => ({ id, binding: registry.resolve(id).binding }))
+            .filter(({ binding }) => !binding.element || binding.element === own.element || !BEHAVIOUR_TAGS.has(binding.element))
+            .filter(({ binding }) => {
+            const has = splitClasses(binding.classes);
+            const set = new Set(has);
+            return (classes.every((c) => set.has(c)) &&
+                directionOf(has) === directionOf(wanted) &&
+                has.filter(isVisualClass).every((c) => ownLooks.has(c)));
+        })
+            .map(({ id, binding }) => ({ id, score: classSimilarity(wanted, splitClasses(binding.classes)) }))
+            // Below this, the candidate merely shares a class; swapping to it would change more than the tweak.
+            .filter(({ score }) => score >= 0.5)
+            .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+            .slice(0, 2)
+            .map(({ id }) => id);
+    };
+    const projectRules = [
+        {
+            id: 'repeated-tweak',
+            run({ registry, files }) {
+                const byClass = new Map();
+                for (const file of files) {
+                    for (const { site } of sitesOf({ registry, file })) {
+                        if (site.component !== 'Layout')
+                            continue;
+                        const intent = strings(site, 'intent')?.[0];
+                        if (!intent || !registry.has(intent) || registry.isInternal(intent))
+                            continue;
+                        // Visual classes are layout-visual-class errors already; a ternary may list a class twice.
+                        for (const cls of new Set(classesOf(site).filter((c) => !isVisualClass(c)))) {
+                            const key = `${intent} ${cls}`;
+                            const group = byClass.get(key) ?? { intent, cls, places: [] };
+                            group.places.push({ file, site });
+                            byClass.set(key, group);
+                        }
+                    }
+                }
+                // Classes that always travel together ("min-w-0 flex-1") are one tweak, not two.
+                const where = (p) => `${p.file.path}:${p.site.line}`;
+                const tweaks = new Map();
+                for (const group of byClass.values()) {
+                    if (group.places.length < REPEATED_TWEAK)
+                        continue;
+                    const key = `${group.intent} ${group.places.map(where).join(',')}`;
+                    const tweak = tweaks.get(key) ?? { intent: group.intent, classes: [], places: group.places };
+                    tweak.classes.push(group.cls);
+                    tweaks.set(key, tweak);
+                }
+                return [...tweaks.values()].map(({ intent, classes, places }) => {
+                    const [first, ...rest] = places;
+                    const shown = rest.slice(0, 4).map(where);
+                    const more = rest.length - shown.length;
+                    const also = shown.length ? ` Also at ${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}.` : '';
+                    const own = new Set(splitClasses(registry.resolve(intent).binding.classes));
+                    if (classes.every((c) => own.has(c))) {
+                        return violation({ registry, file: first.file }, first.site, 'repeated-tweak', 'warning', `${intent} already has "${classes.join(' ')}", so it does nothing in these ${places.length} places; remove it.${also}`, [], { intent, data: { classes, count: places.length, places: places.map(where), redundant: true } });
+                    }
+                    const existing = intentsWithTweak(registry, intent, classes);
+                    const fix = existing.length
+                        ? `If these are the same kind of region, ${existing.join(' or ')} already ${existing.length > 1 ? 'have' : 'has'} it.`
+                        : 'If these are the same kind of region, give it an intent.';
+                    return violation({ registry, file: first.file }, first.site, 'repeated-tweak', 'warning', `${intent} gets "${classes.join(' ')}" in ${places.length} places. A tweak that repeats is a missing intent. ${fix}${also}`, [
+                        ...existing.map((id) => suggestIntent(registry, id)),
+                        {
+                            text: 'Or add an intent for it',
+                            command: `${cli} add-intent layout.<name> --refs ${intent} --classes "${classes.join(' ')}" --description "..."`,
+                        },
+                    ], { intent, data: { classes, count: places.length, places: places.map(where) } });
+                });
+            },
+        },
+    ];
+    return {
+        name: 'ui',
+        appliesTo: (path) => path === registryPath || STYLESHEET.test(path) || (/\.[jt]sx$/.test(path) && !path.startsWith(componentsDir + '/')),
+        findUsages(ctx) {
+            return sitesOf(ctx).flatMap(({ site }) => {
+                if (!site.component)
+                    return [];
+                return (strings(site, 'intent') ?? []).map((intent) => ({
+                    intent,
+                    path: ctx.file.path,
+                    line: site.line,
+                    column: 1,
+                    snippet: (ctx.file.text.split('\n')[site.line - 1] ?? '').trim(),
+                    via: site.component,
+                }));
+            });
+        },
+        rules,
+        projectRules,
+        describe: describeBinding,
+        groupOf: groupByComponent,
+        usage: uiUsage,
+        specSection: uiSpecSection,
+        referenceSection: uiReferenceSection,
+    };
+}
+export { UI_RULE_DOCS, specExamples, uiSpecTooling } from './spec.js';
+export { themeCss, THEME_TOKENS, THEME_VARIABLES, SURFACE_TOKENS, SURFACE_CLASSES } from './theme.js';

package/dist/tooling/spec.d.ts

@@ -0,0 +1,24 @@
+import type { AnyRegistry } from '@prongsjs/core';
+import type { RuleDoc, SpecContext, SpecTooling } from '@prongsjs/core/engine';
+/** What an intent renders, without its classes: `<form>`, `role="status"`, `type="email"`. */
+export declare function describeBinding(binding: unknown): string;
+/** The examples whose intents all exist, for tests that check them against a registry. */
+export declare function specExamples(registry: AnyRegistry): {
+    title: string;
+    code: string;
+}[];
+export declare function uiSpecSection(registry: AnyRegistry, context: SpecContext): string;
+/** What only editing the registry or the theme needs: PRONGS.reference.md. */
+export declare function uiReferenceSection(): string;
+/** How a call site writes an intent, for `prongs find`. */
+export declare function uiUsage(id: string, binding: unknown): string;
+/** Groups the spec's index by the component that renders each intent. */
+export declare function groupByComponent(id: string): string;
+/**
+ * What the UI profile adds to PRONGS.md, without the code analysis (and the TypeScript
+ * compiler it needs). For writing the spec somewhere other than the CLI, like a docs site.
+ */
+export { COMPONENT_DOCS, LAYOUT_PROPS, type ComponentDoc, type PropDoc } from './components.js';
+export declare const uiSpecTooling: SpecTooling;
+/** What each UI rule finds, for the docs and for anyone reading a check report. */
+export declare const UI_RULE_DOCS: readonly RuleDoc[];