@wix/origami-lint 1.34.30 → 1.34.31

package/dist/rules/project/index.js

@@ -1,4 +1,5 @@
 import homePageFolder from "./home-page-folder.js";
+import themeConnectionNotes from "./theme-connection-notes.js";
 export { defineProjectRule } from "./define-project-rule.js";
 // Execution registries combine already-checked rules; only this boundary erases their individual key unions.
-export const projectRuleRegistry = [homePageFolder];
+export const projectRuleRegistry = [homePageFolder, themeConnectionNotes];

package/dist/rules/project/theme-connection-notes.js

@@ -0,0 +1,221 @@
+// The theme-connection-notes subject: how an element's style.css connects to the Theme. Warnings: the import stores each value as
+// written, so it takes all of these; the editor edits a half-connected element worse, and its Theme no longer changes a copied literal.
+// - KIT-slotMix: an element takes every field from one slot of a family. A slot is the theme's --wst-* tokens of one look: a button
+//   (button-primary, -secondary, -tertiary), a box (box-primary, -secondary) or a type style (heading-1 to heading-6, paragraph-1 to -3).
+// - KIT-slotPartial: an element connected to a slot writes no raw value on that slot's fields: a type slot's font or color, any color of
+//   a button or a box.
+// - KIT-themeRepeat: a literal color or font written on three or more element rules across the site, when a --wst-* token in
+//   global/themes/theme.css holds it: connect them to the token.
+// An element's fields are its classes' own rules in its page's, popup's or global component's style.css, joined as the cascade
+// reads them (`className="base extra"` takes both): per breakpoint (`@media`) and property, the line that applies. Its inner parts
+// (`.comp-a .item`) are left out, as the editor itself writes a slot's font with a raw color on them (converter fixture
+// f16-c1dmp-real-page); so are states (`:hover`) and what an `@apply` puts in (a global style is the theme's). KIT-themeRepeat counts
+// class rules, and needs every page at once, so this is a project rule: it builds each page's model and reads the theme.
+import { buildPageModel, findPages, JSX_FILES } from "../../page-model/index.js";
+import { readThemeTokens } from "../../shared/css.js";
+import { POPUPS_FOLDER, SITE_SRC } from "../../shared/site-files-tree-mapping.js";
+import { defineProjectRule } from "./define-project-rule.js";
+/** One check per row: KIT-slotMix, KIT-slotPartial, KIT-themeRepeat. */
+const CHECKS = ['mixed_slots', 'raw_slot_field', 'repeated_theme_literal'];
+/** A var() of a slot's token: `var(--wst-heading-1-font)` → 'heading-1'. */
+const SLOT_TOKEN = /var\(\s*--wst-(button-(?:primary|secondary|tertiary)|box-(?:primary|secondary)|heading-[1-6]|paragraph-[1-3])-/g;
+/** A type slot's fields; a button's and a box's are every color they write. */
+const TYPE_FIELDS = ['font', 'color'];
+/** At least this many element rules write a literal before KIT-themeRepeat reports it. */
+const REPEATS = 3;
+/** At most this many rules are named in a KIT-themeRepeat message. */
+const NAMED_RULES = 5;
+/** A literal color in a value: `#` and 3 to 8 hex digits, or `rgb(…)` / `rgba(…)`. */
+const LITERAL_COLOR = /#[0-9a-f]{3,8}\b|rgba?\([^)]*\)/gi;
+const HEX_COLOR = /^#([0-9a-f]{3,8})$/i;
+const RGB_COLOR = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+%?)\s*)?\)$/i;
+const THEME_TOKEN = /^--wst-/;
+const FONT_TOKEN = /^--wst-[\w-]+-font$/;
+export default defineProjectRule({
+    name: 'theme-connection-notes',
+    checks: CHECKS,
+    editors: ['studio2'],
+    severity: 'warn',
+    check: (project) => {
+        const pages = getPageModels(project);
+        const holders = getThemeHolders(pages[0]);
+        return [
+            ...pages.flatMap(getElementsFields).flatMap(checkElementSlots),
+            ...[...getLiteralUses(pages.flatMap(getClassRulesFields))].flatMap(([key, uses]) => checkLiteralConnected(key, uses, holders)),
+        ];
+    },
+});
+// ── the steps ──
+/** Per family of slots the element uses: one slot (KIT-slotMix), then that slot's fields connected (KIT-slotPartial). */
+function checkElementSlots(element) {
+    return [...getSlotsByFamily(element)].flatMap(([family, slots]) => {
+        const mix = checkElementOneSlot(element, slots);
+        return mix.length ? mix : checkSlotFieldsConnected(element, family, slots[0].slot);
+    });
+}
+/** Reports an element that takes fields from two slots of one family, on the line the second is first used (KIT-slotMix). */
+function checkElementOneSlot({ file, name }, slots) {
+    if (slots.length === 1)
+        return [];
+    const names = slots.map(({ slot }) => `--wst-${slot}-*`).join(' with ');
+    return [{ check: 'mixed_slots', file, line: slots[1].line, message: `${name} mixes ${names}. Connect every field to one slot (rule KIT-slotMix).` }];
+}
+/** Reports each raw value on the slot's fields: a type slot's font or color, any color of a button or a box (KIT-slotPartial). A transparent
+ * color is no raw look. */
+function checkSlotFieldsConnected({ file, name, fields }, family, slot) {
+    return fields.flatMap(({ property, value, line }) => {
+        if (value.includes('var(') || !(family === 'type' ? TYPE_FIELDS.includes(property) && !isTransparent(value) : readLiteralColors(value).length > 0))
+            return [];
+        const token = family === 'type' ? `var(--wst-${slot}-${property})` : `a --wst-${slot}-* token with var()`;
+        return [{ check: 'raw_slot_field', file, line, message: `${name} is connected to --wst-${slot}-* but its ${property} is a raw value (${value}). Connect it to ${token}, or keep it as a deliberate one-off (rule KIT-slotPartial).` }];
+    });
+}
+/** Reports a literal written on three or more element rules that a theme token holds, on the first rule's line (KIT-themeRepeat). */
+function checkLiteralConnected(key, uses, holders) {
+    const tokens = holders.get(key);
+    if (uses.length < REPEATS || tokens === undefined)
+        return [];
+    const [kind, value] = [key.slice(0, key.indexOf(':')), key.slice(key.indexOf(':') + 1)];
+    const named = uses.slice(0, NAMED_RULES).map(({ file, name, line }) => `${name} in ${file.slice(SITE_SRC.length + 1)}:${line}`);
+    const rules = `${named.join(', ')}${uses.length > NAMED_RULES ? ', …' : ''}`;
+    const message = `${kind} ${value} is written on ${uses.length} rules (${rules}); ${tokens.join(' / ')} in theme.css holds it. Connect them with var(${tokens[0]}) (rule KIT-themeRepeat).`;
+    return [{ check: 'repeated_theme_literal', file: uses[0].file, line: uses[0].line, message }];
+}
+// ── reading the site ──
+/** The fields of each element of a page: its classes' CSS joined (`component.css`, as the cascade reads them, in file order). Elements with
+ * the same set of classes, in any order, are one, named by the set sorted: `.base.extra`. */
+function getElementsFields(page) {
+    const byName = new Map();
+    for (const component of Object.values(page.components)) {
+        const classNames = [...new Set(component.classNames.filter((className) => page.css.byClassName[className]))].sort();
+        if (classNames.length)
+            byName.set(`.${classNames.join('.')}`, component.css);
+    }
+    return [...byName].flatMap(([name, css]) => getFieldsByMedia(`${page.path}/style.css`, name, css));
+}
+/** Each class rule's fields: what KIT-themeRepeat counts, a rule written once whatever elements take it. */
+function getClassRulesFields(page) {
+    return Object.entries(page.css.byClassName).flatMap(([className, css]) => getFieldsByMedia(`${page.path}/style.css`, `.${className}`, css));
+}
+/** One entry per breakpoint (`@media`): the own style.css lines (`&`: no part, no state), per property the last one, which applies. */
+function getFieldsByMedia(file, name, css) {
+    const byMedia = new Map();
+    for (const [property, lines] of Object.entries(css.style)) {
+        for (const line of lines.filter(({ selector }) => selector === '&')) {
+            if (!byMedia.has(line.media))
+                byMedia.set(line.media, new Map());
+            byMedia.get(line.media).set(property, { property, ...line });
+        }
+    }
+    return [...byMedia.values()].map((fields) => ({ file, name, fields: [...fields.values()].sort((a, b) => a.line - b.line || a.column - b.column) }));
+}
+/** The model of each page, popup and global component, sorted by path; a page whose files can't be parsed is left out (the page rules report it,
+ * and a note never fails the run). */
+function getPageModels({ files, readFile }) {
+    return [...findPages([...files], [...files]), ...getPopupJsxFiles(files)].sort().flatMap((jsxFile) => {
+        try {
+            return [buildPageModel({ jsxFile, text: readFile(jsxFile) ?? '' }, readFile)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** Each popup's structure file: one popup per folder directly under popups/, written like a page (structure.tsx wins over structure.jsx).
+ * findPages, which picks the page rules' pages, has no popups. */
+function getPopupJsxFiles(files) {
+    const existing = new Set(files);
+    const folders = new Set(files.filter((file) => file.startsWith(`${POPUPS_FOLDER}/`) && file.split('/').length === POPUPS_FOLDER.split('/').length + 2).map((file) => file.slice(0, file.lastIndexOf('/'))));
+    return [...folders].flatMap((folder) => JSX_FILES.map((name) => `${folder}/${name}`).find((file) => existing.has(file)) ?? []);
+}
+/** The slots an element's fields use, by family, each once, in the order first used. */
+function getSlotsByFamily({ fields }) {
+    const slots = new Map();
+    for (const { value, line } of fields) {
+        for (const [, slot] of value.matchAll(SLOT_TOKEN)) {
+            const family = getFamily(slot);
+            const uses = slots.get(family) ?? [];
+            if (!uses.some((use) => use.slot === slot))
+                slots.set(family, [...uses, { slot, line }]);
+        }
+    }
+    return slots;
+}
+/** 'button-primary' → 'button'; 'box-secondary' → 'box'; 'heading-1', 'paragraph-2' → 'type'. */
+function getFamily(slot) {
+    if (slot.startsWith('button-'))
+        return 'button';
+    return slot.startsWith('box-') ? 'box' : 'type';
+}
+/** Each literal color and font the class rules write, with the rules that write it, each rule once, in order. */
+function getLiteralUses(rules) {
+    const uses = new Map();
+    const add = (key, use) => {
+        const keyUses = uses.get(key) ?? [];
+        if (!keyUses.some(({ file, name }) => file === use.file && name === use.name))
+            uses.set(key, [...keyUses, use]);
+    };
+    for (const { file, name, fields } of rules) {
+        for (const { property, value, line } of fields) {
+            const literal = value.replace(/!important\s*$/i, '').trim();
+            if (literal.includes('var('))
+                continue;
+            if (property === 'font')
+                add(fontKey(literal), { file, name, line });
+            for (const color of readLiteralColors(literal))
+                add(`color:${color}`, { file, name, line });
+        }
+    }
+    return uses;
+}
+/** The theme's --wst-* tokens whose value is one literal color or a literal font, by that literal. Every page holds the same theme. */
+function getThemeHolders(page) {
+    const holders = new Map();
+    for (const { name, value } of readThemeTokens(page?.css.files.theme)) {
+        if (!THEME_TOKEN.test(name) || value.includes('var('))
+            continue;
+        const color = normalizeColor(value);
+        const key = FONT_TOKEN.test(name) ? fontKey(value) : color && `color:${color}`;
+        if (key && !holders.get(key)?.includes(name))
+            holders.set(key, [...(holders.get(key) ?? []), name]);
+    }
+    return holders;
+}
+/** A font shorthand in one spelling: spaces collapsed, lower case. */
+const fontKey = (value) => `font:${value.replace(/\s+/g, ' ').trim().toLowerCase()}`;
+/** A literal color read: its channels in one spelling ('#116DFF', '#16f', 'rgb(17, 102, 255)' → '#116dff', '#1166ff') and its alpha, 0 to 1.
+ * Null for anything else ('red', 'var(--x)', '#12345'). */
+function parseColor(color) {
+    const hex = HEX_COLOR.exec(color.trim())?.[1].toLowerCase();
+    const rgb = hex ? null : RGB_COLOR.exec(color.trim());
+    let channels;
+    let alpha = 1;
+    if (hex) {
+        const digits = hex.length <= 4 ? [...hex].map((digit) => digit + digit).join('') : hex;
+        if (digits.length !== 6 && digits.length !== 8)
+            return null;
+        channels = [0, 2, 4].map((at) => parseInt(digits.slice(at, at + 2), 16));
+        if (digits.length === 8)
+            alpha = parseInt(digits.slice(6), 16) / 255;
+    }
+    else if (rgb) {
+        channels = rgb.slice(1, 4).map(Number);
+        if (rgb[4] !== undefined)
+            alpha = rgb[4].endsWith('%') ? parseFloat(rgb[4]) / 100 : Number(rgb[4]);
+    }
+    else
+        return null;
+    return { spelled: `#${channels.map((channel) => Math.round(channel).toString(16).padStart(2, '0')).join('')}`, alpha };
+}
+/** One spelling of a literal color, so two spellings of one color compare equal; with an alpha, '#116dff/0.5'. Null for a transparent
+ * color (alpha 0: not a look) and for anything that isn't a literal color. */
+function normalizeColor(color) {
+    const parsed = parseColor(color);
+    if (parsed === null || parsed.alpha === 0)
+        return null;
+    return parsed.alpha >= 1 ? parsed.spelled : `${parsed.spelled}/${Number(parsed.alpha.toFixed(2))}`;
+}
+/** `transparent`, or a literal color with alpha 0: no look of its own, so not a raw value. */
+const isTransparent = (value) => /^transparent$/i.test(value.trim()) || parseColor(value)?.alpha === 0;
+/** The literal colors written in a value, each in one spelling (normalizeColor), in order; a transparent one is left out. */
+const readLiteralColors = (value) => [...value.matchAll(LITERAL_COLOR)].flatMap(([color]) => normalizeColor(color) ?? []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-lint",
-  "version": "1.34.30",
+  "version": "1.34.31",
   "description": "Offline lint for an exported Origami site: lints the pages that changed since the last passing run",
   "type": "module",
   "bin": {
@@ -52,5 +52,5 @@
       ]
     }
   },
-  "falconPackageHash": "335c078a8c6afc26c556fcd6c71643e777664f3b26b63a3b7b9832a4"
+  "falconPackageHash": "686d35f346108816f50b0d95576cb023e273a903c797136d43187f3e"
 }