@wix/origami-lint 0.0.0-stage → 1.34.1

package/dist/rules/page-structure.js

@@ -0,0 +1,277 @@
+// The page-structure subject (tracker tab site-app-rules-mapping): what may sit inside what in a structure file.
+// A site page is  <Page>  →  sections  →  exactly one <InternalContainer> each; sections are Section, HeaderSection, FooterSection,
+// or the site's global header / footer. <Page> may also hold any other component: the page's own <Background> (the export writes it
+// as <Page>'s last child) and pinned elements (wix-site-edit components.md, layout.md "Pinned"); the import accepts any component
+// there. A global component is a section of the master page, so its top element is a section (rule card P1-R13). Types are
+// recognized by import source (rulesApi.getType), so renaming an import doesn't matter.
+// Checked in every file, pages and global components alike:
+// - Structure returns one element, with a string id (tracker CONV-runValidation.ts:9);
+// - a <Page> is only ever the top of its own page: one held by another element is refused at save (rule card P1-R16);
+// - the header and footer sit outside every <InternalContainer>: inside one, that container can no longer be deleted in the
+//   editor (rule card P1-R03). Both the HeaderSection / FooterSection tags and a page's reference to the global ones;
+// - a <Remove> holds exactly one component element (CONV-parseJsx.ts:1028), and no <Remove> sits inside another: <Remove> wraps
+//   the component itself (CONV-parseJsx.ts:1237; converter 0.86 parseJsx.ts:1500, :1681);
+// - only elements go between a component's tags: no text, no {…}, no fragment (CONV-parseJsx.ts:1668);
+// - an <InternalContainer>'s backgroundLayer / pinnedLayer is an array of elements (CONV-parseJsx.ts:1630).
+// Wrappers are transparent for the tree, as they are for the import: a section wrapped in <Remove> is still the page's child.
+// <Interaction> is no wrapper since converter 0.80 (interactions live in servicesConfigs/interactions.ts): allowed-imports
+// reports the tag, and it stays transparent here so the elements inside it aren't reported too. Context-provider wrappers join
+// once the page model lists the providers.
+import { FILE_START } from "../page-model/index.js";
+import { LAYER_ATTRIBUTES, SECTIONS, WRAPPERS } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+export default defineRule({
+    name: 'page-structure',
+    editors: 'all',
+    callbacks: {
+        Program: (input) => hasRoot(input),
+        JSXElement: (input) => {
+            if (!input.rulesApi.getComponent(input.node))
+                return;
+            if (isWrapper(input.node, input.rulesApi)) {
+                if (input.rulesApi.getType(input.node) !== 'remove')
+                    return;
+                holdsOneElement(input);
+                checkNoRemoveInRemove(input);
+                return;
+            }
+            if (isLandmark(input.node, input.rulesApi))
+                hasSectionInLandmark(input);
+            hasOnlyElements(input);
+            hasLayerArrays(input);
+            isNotNestedPage(input);
+            isOutsideInternalContainers(input);
+            if (!isTop(input.node, input.rulesApi))
+                return;
+            if (!isSectionAtTop(input))
+                return;
+            rootHasId(input);
+            if (input.rulesApi.page.kind !== 'page')
+                return;
+            if (!startsWithPage(input))
+                return;
+            for (const section of getSections(input))
+                hasOneInternalContainer(section, input);
+        },
+    },
+});
+// ── the steps ──
+/** Reports a file whose Structure returns no element (CONV-runValidation.ts:9). */
+function hasRoot({ rulesApi, report }) {
+    if (rulesApi.getRoot())
+        return;
+    if (rulesApi.page.kind === 'page')
+        report({ loc: FILE_START, message: 'A page must start with <Page>, found nothing.' });
+    else
+        report({ loc: FILE_START, message: 'A global component must start with a section (HeaderSection, FooterSection or Section), found nothing (tracker CONV-runValidation.ts:9).' });
+}
+/** On a global component, reports a top element that isn't a section (P1-R13); the steps after it are for a section. */
+function isSectionAtTop({ node, rulesApi, report }) {
+    if (rulesApi.page.kind !== 'global')
+        return true;
+    const type = rulesApi.getType(node);
+    if (isLandmark(node, rulesApi) || (type && SECTIONS.includes(type)))
+        return true;
+    report({ loc: getLoc(node, rulesApi), message: `${describeElement(node, rulesApi)} sits directly in the master page. A global component's top element is a section (HeaderSection, FooterSection or Section); put it inside one (rule P1-R13).` });
+    return false;
+}
+/** Reports a root element with no string id (CONV-runValidation.ts:9). The tree steps go on: the import reports them all in one run. */
+function rootHasId({ node, rulesApi, report }) {
+    if (rulesApi.getId(node) !== null)
+        return;
+    // Shared landmarks receive the instance identity from Structure's props.
+    if (rulesApi.page.kind === 'global' && isLandmark(node, rulesApi) && node.openingElement.attributes.some(attribute => attribute.type === 'JSXAttribute' && attribute.name.type === 'JSXIdentifier' && attribute.name.name === 'id'
+        && attribute.value?.type === 'JSXExpressionContainer' && attribute.value.expression.type === 'Identifier'
+        && attribute.value.expression.name === 'id') && receivesInstanceId(node))
+        return;
+    const tag = rulesApi.getTagName(node);
+    report({ loc: getLoc(node, rulesApi), message: `<${tag}> at the top has no id. Give the root element its id, like \`<${tag} id="c1dmp">\` (tracker CONV-runValidation.ts:9).` });
+}
+/** Reports a page's root that isn't <Page>. */
+function startsWithPage({ node, rulesApi, report }) {
+    if (rulesApi.getType(node) === 'page')
+        return true;
+    report({ loc: getLoc(node, rulesApi), message: `A page must start with <Page>, found ${describe(node, rulesApi)}.` });
+    return false;
+}
+/** <Page>'s sections. Any other component (the page's <Background>, a pinned element) is accepted, as the import accepts it; reports text and {…} (CONV-parseJsx.ts:1668). */
+function getSections({ node: page, rulesApi, report }) {
+    const sections = [];
+    for (const child of getStructuralChildren(page, rulesApi)) {
+        if (child.type === 'JSXElement') {
+            const type = rulesApi.getType(child);
+            if (type && SECTIONS.includes(type))
+                sections.push(child);
+            continue;
+        }
+        report({ loc: getLoc(page, rulesApi), message: `<Page> has ${describe(child, rulesApi)} as a child. Only elements go directly inside <Page>: a section, or a component pinned to the page (tracker CONV-parseJsx.ts:1668).` });
+    }
+    return sections;
+}
+/** Reports a section that doesn't hold exactly one <InternalContainer>, and nothing else. A wrapper in it that holds the wrong number of elements is reported by its own step first. */
+function hasOneInternalContainer(section, { rulesApi, report }) {
+    if (rulesApi.getChildren(section).some((child) => child.type === 'JSXElement' && isWrapper(child, rulesApi) && !holdsOne(child)))
+        return;
+    const inside = getStructuralChildren(section, rulesApi);
+    if (inside.length === 1 && inside[0].type === 'JSXElement' && rulesApi.getType(inside[0]) === 'innerElement')
+        return;
+    const name = rulesApi.getId(section) ?? `<${rulesApi.getTagName(section)}>`;
+    report({ loc: getLoc(section, rulesApi), message: `Section ${name} must contain exactly one <InternalContainer>, found: ${inside.map((child) => describe(child, rulesApi)).join(', ') || 'nothing'}.` });
+}
+/** Reports a <Page> held by another element (P1-R16), unless the root steps above report that placement already (a section's children). */
+function isNotNestedPage({ node, rulesApi, report }) {
+    if (rulesApi.getType(node) !== 'page')
+        return;
+    const holder = getHolder(node, rulesApi);
+    if (!holder || (rulesApi.getType(holder) !== 'page' && isRootTreeHolder(holder, rulesApi) && isStructuralChild(holder, node, rulesApi)))
+        return;
+    report({ loc: getLoc(node, rulesApi), message: `${describeElement(node, rulesApi)} is inside ${describeElement(holder, rulesApi)}. A page is only the top element of its own page (rule P1-R16).` });
+}
+/** Reports a header or footer, or a page's reference to the global one, with an <InternalContainer> among its ancestors (P1-R03). */
+function isOutsideInternalContainers({ node, rulesApi, report }) {
+    const kind = headerOrFooter(rulesApi.getType(node));
+    if (!kind)
+        return;
+    const container = getAncestors(node).find((ancestor) => rulesApi.getType(ancestor) === 'innerElement');
+    if (!container)
+        return;
+    report({ loc: getLoc(node, rulesApi), message: `The ${kind} ${describeElement(node, rulesApi)} is inside the internal container ${describeElement(container, rulesApi)}. Move it out of every internal container: the header and footer sit directly in the page or the master page (rule P1-R03).` });
+}
+/** Reports a wrapper that doesn't hold exactly one element: none, two, text, or a {…} (a comment too) beside it (CONV-parseJsx.ts:1028). */
+function holdsOneElement({ node, rulesApi, report }) {
+    if (holdsOne(node))
+        return;
+    report({ loc: node.openingElement.name.loc, message: `<${rulesApi.getTagName(node)}> wraps exactly one component element: give each component its own wrapper (tracker CONV-parseJsx.ts:1028).` });
+}
+/** Reports a <Remove> right inside another <Remove> (CONV-parseJsx.ts:1237): <Remove> wraps the component itself, so nothing nests in it. Compared with the element right around it, as the import does. */
+function checkNoRemoveInRemove({ node, rulesApi, report }) {
+    const outer = getAncestors(node)[0];
+    if (!outer || rulesApi.getType(outer) !== 'remove')
+        return;
+    report({ loc: node.openingElement.name.loc, message: `<${rulesApi.getTagName(node)}> is inside another <Remove>. <Remove> wraps the component itself: merge the two conditions into one <Remove> (tracker CONV-parseJsx.ts:1237).` });
+}
+/** Reports text, a {…} (a comment too), a fragment or a spread between a component's tags (CONV-parseJsx.ts:1668). The root steps report those in <Page> and its sections, except comments, which they don't see. */
+function hasOnlyElements({ node, rulesApi, report }) {
+    const commentsOnly = isRootTreeHolder(node, rulesApi);
+    for (const child of node.children) {
+        if (child.type === 'JSXElement' || (child.type === 'JSXText' && child.value.trim() === ''))
+            continue;
+        if (commentsOnly && !isComment(child))
+            continue;
+        report({ loc: child.type === 'JSXText' ? getTextLoc(child) : child.loc, message: `${describeElement(node, rulesApi)} has text or {…} as a child. Put the value in an attribute: only elements go between the tags (tracker CONV-parseJsx.ts:1668).` });
+    }
+}
+/** Reports an <InternalContainer>'s backgroundLayer / pinnedLayer that isn't an array literal of elements (CONV-parseJsx.ts:1630). */
+function hasLayerArrays({ node, rulesApi, report }) {
+    if (rulesApi.getType(node) !== 'innerElement')
+        return;
+    for (const attribute of node.openingElement.attributes) {
+        if (attribute.type !== 'JSXAttribute' || attribute.name.type !== 'JSXIdentifier' || !LAYER_ATTRIBUTES.includes(attribute.name.name))
+            continue;
+        if (isArrayOfElements(attribute))
+            continue;
+        report({ loc: attribute.loc, message: `${describeElement(node, rulesApi)}'s ${attribute.name.name} must be an array of elements: ${attribute.name.name}={[<… />]} (tracker CONV-parseJsx.ts:1630).` });
+    }
+}
+// ── reading the tree ──
+/** 'header' / 'footer' for the section tags and for a page's reference to the global ones; null for anything else. */
+function headerOrFooter(type) {
+    if (type === 'header' || type === 'globalHeader' || type === 'headerLandmark')
+        return 'header';
+    if (type === 'footer' || type === 'globalFooter' || type === 'footerLandmark')
+        return 'footer';
+    return null;
+}
+/** <Remove>, <Interaction>: a tag that wraps one component and isn't one. */
+function isWrapper(element, rulesApi) {
+    const type = rulesApi.getType(element);
+    return type !== null && WRAPPERS.includes(type);
+}
+/** The JSX elements around this one, closest first: its parents, and the element whose prop it's passed in. Wrappers included. */
+function getAncestors(element) {
+    const ancestors = [];
+    for (let node = element.parent; node; node = node.parent) {
+        if (node.type === 'JSXElement')
+            ancestors.push(node);
+    }
+    return ancestors;
+}
+/** The elements around this one that are components, closest first: wrappers are transparent. */
+const getHolders = (element, rulesApi) => getAncestors(element).filter((ancestor) => !isWrapper(ancestor, rulesApi));
+/** The closest component around this one; null at the top. */
+const getHolder = (element, rulesApi) => getHolders(element, rulesApi)[0] ?? null;
+/** The file's top element: no component around it (wrappers don't count). */
+const isTop = (element, rulesApi) => getHolders(element, rulesApi).length === 0;
+/** The element's children as the import sees them: a wrapper stands for the elements it holds. Text and {…} in a wrapper are its own problem. */
+const getStructuralChildren = (element, rulesApi) => rulesApi.getChildren(element).flatMap((child) => (child.type === 'JSXElement' && isWrapper(child, rulesApi) ? rulesApi.getChildElements(child) : [child]));
+/** On a page whose top is <Page>, the root steps report every child of that <Page> and of its sections: a child of those holders isn't reported twice. */
+function isRootTreeHolder(holder, rulesApi) {
+    if (rulesApi.page.kind !== 'page')
+        return false;
+    const around = getHolders(holder, rulesApi);
+    if (around.length === 0)
+        return rulesApi.getType(holder) === 'page';
+    const type = rulesApi.getType(holder);
+    return around.length === 1 && isRootTreeHolder(around[0], rulesApi) && type !== null && SECTIONS.includes(type) && isStructuralChild(around[0], holder, rulesApi);
+}
+/** Whether the element is one of the holder's children (through wrappers), not something passed in one of its attributes. */
+const isStructuralChild = (holder, element, rulesApi) => getStructuralChildren(holder, rulesApi).includes(element);
+/** A wrapper holds exactly one element: non-blank text, a {…} (a comment too), a fragment count as what it holds. */
+const holdsOne = (wrapper) => {
+    const inside = wrapper.children.filter((child) => child.type !== 'JSXText' || child.value.trim() !== '');
+    return inside.length === 1 && inside[0].type === 'JSXElement';
+};
+/** A JSX comment: an expression container with nothing in it. */
+const isComment = (child) => child.type === 'JSXExpressionContainer' && child.expression.type === 'JSXEmptyExpression';
+/** `backgroundLayer={[<Background … />]}`: an array literal whose every entry is an element. */
+function isArrayOfElements(attribute) {
+    const { value } = attribute;
+    if (value?.type !== 'JSXExpressionContainer' || value.expression.type !== 'ArrayExpression')
+        return false;
+    return value.expression.elements.every((entry) => entry !== null && entry.type === 'JSXElement');
+}
+// ── reporting ──
+/** Where a text child starts, its leading whitespace skipped: a text's node begins right after the opening tag. */
+function getTextLoc(text) {
+    const leading = /^\s*/.exec(text.value)[0];
+    const lines = leading.split('\n');
+    const start = lines.length > 1 ? { line: text.loc.start.line + lines.length - 1, column: lines[lines.length - 1].length } : { line: text.loc.start.line, column: text.loc.start.column + leading.length };
+    return { start, end: text.loc.end };
+}
+/** Where to mark an element: its id attribute, or its tag name. */
+const getLoc = (element, rulesApi) => rulesApi.getComponent(element)?.loc ?? element.openingElement.name.loc;
+/** '<Page> inner', or '<Top>' without an id. */
+function describeElement(element, rulesApi) {
+    const id = rulesApi.getId(element);
+    return `<${rulesApi.getTagName(element)}>${id ? ` ${id}` : ''}`;
+}
+function describe(child, rulesApi) {
+    if (child.type === 'JSXElement')
+        return `<${rulesApi.getTagName(child)}>`;
+    return child.type === 'JSXText' ? 'text' : 'a {…} expression';
+}
+function isLandmark(node, rulesApi) {
+    const type = rulesApi.getType(node);
+    return type === 'headerLandmark' || type === 'footerLandmark';
+}
+/** A landmark owns instance placement; the matching section owns the definition's content. */
+function hasSectionInLandmark(input) {
+    const { node, rulesApi, report } = input;
+    const expected = rulesApi.getType(node) === 'headerLandmark' ? 'header' : 'footer';
+    const children = getStructuralChildren(node, rulesApi);
+    if (children.length === 1 && children[0].type === 'JSXElement' && rulesApi.getType(children[0]) === expected) {
+        hasOneInternalContainer(children[0], input);
+        return;
+    }
+    report({ loc: getLoc(node, rulesApi), message: `<${rulesApi.getTagName(node)}> must contain exactly one ${expected === 'header' ? 'HeaderSection' : 'FooterSection'}.` });
+}
+function receivesInstanceId(node) {
+    for (let parent = node.parent; parent; parent = parent.parent) {
+        if (parent.type !== 'ArrowFunctionExpression')
+            continue;
+        const parameter = parent.params[0];
+        return parameter?.type === 'ObjectPattern' && parameter.properties.some(property => property.type === 'Property' && !property.computed && property.key.type === 'Identifier' && property.key.name === 'id'
+            && property.value.type === 'Identifier' && property.value.name === 'id');
+    }
+    return false;
+}

package/dist/rules/slot-attributes.js

@@ -0,0 +1,96 @@
+// Slot placement: how `slot=` is written on a component that fills a named spot.
+// An element goes into a spot in one of two ways: in an attribute (`content={<InternalContainer />}`), or as a child with `slot="…"`.
+// - an element in an attribute has no `slot=` of its own: its place is the attribute; layers are not slots (CONV-parseJsx.ts:1507);
+// - one component uses one way, not both: attribute elements, or children with `slot=` / an elementProps entry's `slots: {…}` (CONV-parseJsx.ts:1693);
+// - the root element has no `slot=`: it has no owner to be a slot of (CONV-fromBundle.ts:1312);
+// - two children of one owner don't share a slot key (CONV-slots.ts:555).
+// Children are the element children and the layer elements (backgroundLayer, pinnedLayer); <Remove> and <Interaction> are transparent.
+import { LAYER_ATTRIBUTES, WRAPPERS } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+export default defineRule({
+    name: 'slot-attributes',
+    editors: ['studio2'],
+    callbacks: {
+        JSXElement: (input) => {
+            if (!input.rulesApi.getComponent(input.node))
+                return;
+            rootHasNoSlot(input);
+            for (const { element, attribute } of input.rulesApi.getAttributeElements(input.node))
+                attributeElementHasNoSlot(element, attribute, input);
+            usesSlotsOnlyOneWay(input);
+            usesEachSlotKeyOnce(input);
+        },
+    },
+});
+// ── the steps ──
+/** Reports a slot attribute on the root element (CONV-fromBundle.ts:1312). */
+function rootHasNoSlot({ node, rulesApi, report }) {
+    const slot = rulesApi.getSlot(node);
+    if (slot === null || !isRoot(node, rulesApi))
+        return;
+    report({ loc: getLoc(node, rulesApi), message: `The root ${describe(node, rulesApi)} can't have a slot attribute. Remove slot="${slot}" (tracker CONV-fromBundle.ts:1312).` });
+}
+/** The root element: the top of Structure, or the element a <Remove> / <Interaction> at the top holds (the page model makes that wrapper the root). */
+function isRoot(node, rulesApi) {
+    let top = node;
+    while (top.parent?.type === 'JSXElement' && isWrapper(top.parent, rulesApi))
+        top = top.parent;
+    return rulesApi.getRoot() === rulesApi.getComponent(top);
+}
+const isWrapper = (element, rulesApi) => {
+    const type = rulesApi.getType(element);
+    return type !== null && WRAPPERS.includes(type);
+};
+/** Reports a slot attribute on an element that sits in an attribute of its owner, layers excluded: its place is the attribute (CONV-parseJsx.ts:1507). */
+function attributeElementHasNoSlot(element, attribute, { rulesApi, report }) {
+    const name = getAttributeName(attribute);
+    if (LAYER_ATTRIBUTES.includes(name) || rulesApi.getSlot(element) === null)
+        return;
+    report({ loc: getLoc(element, rulesApi), message: `${describe(element, rulesApi)} is placed in the attribute '${name}' and also has slot="${rulesApi.getSlot(element)}". Remove slot=: its place is the attribute (tracker CONV-parseJsx.ts:1507).` });
+}
+/** Reports an owner that holds elements in its attributes and also has a child with slot=, or an elementProps entry with slots: {…} (CONV-parseJsx.ts:1693). */
+function usesSlotsOnlyOneWay({ node, rulesApi, report }) {
+    if (!getSlotElements(node, rulesApi).length)
+        return;
+    if (!getSlottedChildren(node, rulesApi).length && !hasEntrySlots(node))
+        return;
+    report({ loc: getLoc(node, rulesApi), message: `${describe(node, rulesApi)} places slotted children both in attributes and with slot= (or slots: {…}). Use one way: elements in attributes, or children with slot= (tracker CONV-parseJsx.ts:1693).` });
+}
+/** Reports a slot key that two children of the owner share (CONV-slots.ts:555), at the later one in the owner's list: children first, then layer elements. */
+function usesEachSlotKeyOnce({ node, rulesApi, report }) {
+    const first = new Map();
+    for (const child of getSlottedChildren(node, rulesApi)) {
+        const slot = rulesApi.getSlot(child);
+        const other = first.get(slot);
+        if (!other)
+            first.set(slot, child);
+        else
+            report({ loc: getLoc(child, rulesApi), message: `Slot "${slot}" of ${describe(node, rulesApi)} is used by both ${describe(other, rulesApi)} and ${describe(child, rulesApi)}. Give each slotted child its own slot key (tracker CONV-slots.ts:555).` });
+    }
+}
+// ── reading the owner ──
+/** The elements the owner holds in its attributes, not counting its layers. */
+const getSlotElements = (owner, rulesApi) => rulesApi.getAttributeElements(owner).filter(({ attribute }) => !LAYER_ATTRIBUTES.includes(getAttributeName(attribute)));
+/** The owner's children (and layer elements) that have a slot key. */
+const getSlottedChildren = (owner, rulesApi) => [...rulesApi.getChildElements(owner), ...rulesApi.getAttributeElements(owner).filter(({ attribute }) => LAYER_ATTRIBUTES.includes(getAttributeName(attribute))).map(({ element }) => element)]
+    .filter((child) => rulesApi.getSlot(child) !== null);
+/** `elementProps={{ panel: { slots: {…} } }}`, or the same in a nested `elementProps` of an entry. */
+function hasEntrySlots(owner) {
+    const attribute = owner.openingElement.attributes.find((candidate) => candidate.type === 'JSXAttribute' && getAttributeName(candidate) === 'elementProps');
+    return attribute?.type === 'JSXAttribute' && attribute.value?.type === 'JSXExpressionContainer' && entriesHaveSlots(attribute.value.expression);
+}
+function entriesHaveSlots(entries) {
+    if (entries.type !== 'ObjectExpression')
+        return false;
+    return entries.properties.some((entry) => entry.type === 'Property' && entry.value.type === 'ObjectExpression' && entry.value.properties.some((property) => property.type === 'Property' && (getKeyName(property) === 'slots' || (getKeyName(property) === 'elementProps' && entriesHaveSlots(property.value)))));
+}
+const getKeyName = (property) => property.computed ? null : property.key.type === 'Identifier' ? property.key.name : property.key.type === 'Literal' ? String(property.key.value) : null;
+const getAttributeName = (attribute) => (attribute.name.type === 'JSXIdentifier' ? String(attribute.name.name) : '');
+// ── reporting ──
+/** Where to mark an element: its id attribute, or its tag name. */
+const getLoc = (element, rulesApi) => rulesApi.getComponent(element)?.loc ?? element.openingElement.name.loc;
+/** '<Page> c1dmp', or '<Top>' without an id. */
+function describe(element, rulesApi) {
+    const id = rulesApi.getId(element);
+    return `<${rulesApi.getTagName(element)}>${id ? ` ${id}` : ''}`;
+}

package/dist/rules/theme-font-ids.js

@@ -0,0 +1,69 @@
+// Every theme font token (`--wst-heading-1-font: normal normal 700 --spx(88)/1em benzin`) must end in exactly one font id
+// from the Wix font catalog in @wix/origami-fonts: no quotes, commas or fallbacks, the same case. The editor reads that
+// family as one Wix font id and fails the import otherwise. A legacy font, which the editor no longer offers, counts as
+// not in the catalog. A `var(…)` token is left alone.
+// theme.css isn't a file oxlint lints, so the rule runs on each linted page (a theme change lints every page) and
+// marks the page's start; the message names the token's line in theme.css.
+import { fonts } from '@wix/origami-fonts';
+import { reportCssProblem } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+const FONT_TOKEN = /^--wst-[\w-]+-font$/;
+// The size in a `font` shorthand, with its optional line height: the family follows it. The number's quantifiers
+// never overlap, so a long run of digits that is not a size fails in linear time.
+const SIZE = /^(?:--spx\(.*\)|calc\(.*\)|(?:\d+(?:\.\d*)?|\.\d+)(?:px|em|rem|%|vw|vh|pt)?)(?:\/\S+)?$/i;
+const FONT_IDS = new Set(fonts.filter((font) => font.permissions !== 'legacy').map((font) => font.id));
+export default defineRule({
+    name: 'theme-font-ids',
+    editors: 'all',
+    callbacks: {
+        Program: (input) => {
+            for (const token of getFontTokens(input))
+                hasCatalogFontId(token, input);
+        },
+    },
+});
+// ── the steps ──
+/** The theme's font tokens: `--wst-…-font`. */
+function getFontTokens({ rulesApi }) {
+    return rulesApi.getThemeTokens().filter(({ name }) => FONT_TOKEN.test(name));
+}
+/** Reports a font token whose family isn't exactly one id from the catalog. A `var(…)` or a value without a family isn't checked. */
+function hasCatalogFontId({ name, value, line }, { report }) {
+    const family = getFontFamily(value);
+    if (family === undefined || FONT_IDS.has(family))
+        return;
+    reportCssProblem(report, 'theme.css', line, `${name} must name exactly one Wix font id from the catalog; found ${family}. Run \`wix origami search-font --font <name>\` for the id.`);
+}
+// ── reading a font value ──
+/** A value split on top-level whitespace, so `--spx(16)/1.3em` stays one part. */
+function splitParts(value) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const char of value) {
+        if (char === '(')
+            depth++;
+        else if (char === ')')
+            depth--;
+        if (depth === 0 && /\s/.test(char)) {
+            if (current)
+                parts.push(current);
+            current = '';
+        }
+        else
+            current += char;
+    }
+    if (current)
+        parts.push(current);
+    return parts;
+}
+/** A font shorthand's family as written, after its last size; undefined for `var(…)` or no family. */
+function getFontFamily(value) {
+    if (value.includes('var('))
+        return undefined;
+    const parts = splitParts(value);
+    const size = parts.findLastIndex((part) => SIZE.test(part));
+    if (size === -1 || size === parts.length - 1)
+        return undefined;
+    return parts.slice(size + 1).join(' ');
+}

package/dist/rules/theme-root.js

@@ -0,0 +1,122 @@
+import { describeAtRule, isPresetProperty, PREAMBLE_LAYER, reportCssProblem } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+const SPX_PROPS = ['--spx-ref-width', '--spx-resolver-type'];
+const SPX_RESOLVERS = ['scale', 'fixed'];
+/** A named breakpoint: `(--tablet)`. */
+export default defineRule({
+    name: 'theme-root',
+    editors: ['studio2'],
+    callbacks: {
+        Program: (input) => {
+            const { css } = input.rulesApi.page;
+            for (const root of findRootRules(css.files.theme, input)) {
+                if (root.layer === PREAMBLE_LAYER)
+                    continue;
+                if (!isAlone('theme.css', root, input))
+                    continue;
+                checkThemeRoot(root, input);
+            }
+            for (const file of ['layout', 'style']) {
+                for (const rule of findRootRules(css.files[file], input)) {
+                    if (rule.layer === PREAMBLE_LAYER)
+                        continue;
+                    if (isAlone(`${file}.css`, rule, input))
+                        isNotInPage(file, rule, input);
+                }
+            }
+        },
+    },
+});
+// ── the steps ──
+/** Reports a selector with a part after `:root` (CONV-cssSelectors.ts:388). */
+function isAlone(file, rule, { report }) {
+    if (rule.selector === ':root')
+        return true;
+    reportCssProblem(report, file, rule.line, `\`${rule.selector}\` puts a part after :root. Write \`:root { … }\` alone; style elements by their own class (\`.comp-a { … }\`) (tracker CONV-cssSelectors.ts:388).`);
+    return false;
+}
+/** Reports a `:root` rule in a page's own CSS: in style.css (CONV-styleParser.ts:443); in layout.css too, which the import refuses as well (seen live, no tracker row yet). */
+function isNotInPage(file, rule, { report }) {
+    const source = file === 'style' ? 'tracker CONV-styleParser.ts:443' : 'the import refuses it: seen live';
+    reportCssProblem(report, `${file}.css`, rule.line, `\`:root\` can't be used in a page's ${file}.css: set site variables in global/themes/theme.css (${source}).`);
+}
+/** A theme `:root` rule: a preset (step 4), then only tokens or only the spx context (step 1); an spx context's values (step 2) and place (step 3). A `:root` inside a `@mixin` is the global-styles rows' (its selector must start with `&` there). */
+function checkThemeRoot(root, input) {
+    if (root.enclosing.some((atRule) => atRule.startsWith('@mixin')))
+        return;
+    if (!hasNoPreset(root, input))
+        return;
+    const kind = holdsTokensOrSpx(root, input);
+    if (kind !== 'spx')
+        return;
+    if (!isValidSpxContext(root, input))
+        return;
+    isSpxContextInPlace(root, input);
+}
+/** Reports `--preset` or `--preset-<part>` in `:root` (CONV-parseTheme.ts:224). */
+function hasNoPreset(root, { report }) {
+    const preset = root.declarations.find(({ prop }) => isPresetProperty(prop));
+    if (!preset)
+        return true;
+    reportCssProblem(report, 'theme.css', root.line, `\`:root\` can't set ${preset.prop}; theme.css holds only :root tokens, the spx context and @mixin global styles. Set a preset on the element's rule in its page's style.css (tracker CONV-parseTheme.ts:224).`);
+    return false;
+}
+/** Reports a plain property, or tokens mixed with the spx context (CONV-parseTheme.ts:170). 'tokens' / 'spx' when the rule is one of the two. */
+function holdsTokensOrSpx(root, { report }) {
+    const plain = root.declarations.find(({ prop }) => !prop.startsWith('--'));
+    if (plain) {
+        reportCssProblem(report, 'theme.css', root.line, `this :root rule has \`${plain.prop}\`; a :root rule holds only tokens (--…), or only --spx-ref-width and --spx-resolver-type. Move other properties to an element's rule in style.css (tracker CONV-parseTheme.ts:170).`);
+        return null;
+    }
+    const spx = root.declarations.filter(isSpx);
+    if (spx.length === 0)
+        return 'tokens';
+    if (spx.length === root.declarations.length)
+        return 'spx';
+    reportCssProblem(report, 'theme.css', root.line, `this :root rule mixes the spx context (--spx-ref-width, --spx-resolver-type) with other lines; write the spx context as its own :root rule (tracker CONV-parseTheme.ts:170).`);
+    return null;
+}
+/** Reports an spx context missing one of its two properties, with a width that isn't a positive plain number, or a resolver that isn't scale / fixed (CONV-parseTheme.ts:177). */
+function isValidSpxContext(root, { report }) {
+    const width = lastValue(root, '--spx-ref-width');
+    const resolver = lastValue(root, '--spx-resolver-type');
+    if (width !== undefined && Number.isFinite(Number(width)) && Number(width) > 0 && resolver !== undefined && SPX_RESOLVERS.includes(resolver))
+        return true;
+    reportCssProblem(report, 'theme.css', root.line, `this :root spx rule must set both --spx-ref-width (a positive number, like 1280) and --spx-resolver-type (scale or fixed) (tracker CONV-parseTheme.ts:177).`);
+    return false;
+}
+/** Reports an spx context under anything but one `@media (--name)` the theme declares: two conditions, a plain range, another at-rule (CONV-parseTheme.ts:82). At the top level it is the default range's. */
+function isSpxContextInPlace(root, { rulesApi, report }) {
+    if (root.enclosing.length === 0)
+        return;
+    const name = root.enclosing.length === 1 && root.enclosing[0].startsWith('@media ') ? rulesApi.getBreakpointName(root.enclosing[0].slice('@media '.length)) : null;
+    if (name && rulesApi.getCustomMedia('theme').some((breakpoint) => breakpoint.name === name))
+        return;
+    reportCssProblem(report, 'theme.css', root.line, `set the spx context at the top level or under \`@media (--<named range>)\`, one of the theme's @custom-media names; not under ${root.enclosing.map((atRule) => `\`${atRule}\``).join(', ')} (tracker CONV-parseTheme.ts:82).`);
+}
+// ── reading the CSS ──
+/** Every rule whose selector starts with `:root` in a parsed file, in order, with what's around it and its declarations. No file → none. */
+function findRootRules(file, { rulesApi }) {
+    const rules = [];
+    file?.walkRules((rule) => {
+        const selector = rule.selector.trim();
+        if (!selector.startsWith(':root'))
+            return;
+        const declarations = rule.nodes.flatMap((node) => (node.type === 'decl' ? [{ prop: node.prop, value: node.value.trim(), line: node.source?.start?.line ?? 1 }] : []));
+        rules.push({ selector, line: rule.source?.start?.line ?? 1, ...getPlace(rulesApi.getEnclosingAtRules(rule)), declarations });
+    });
+    return rules;
+}
+/** The at-rules around a rule, outer to inner, as written (`@layer` aside), and the nearest `@layer` name; [] and null at the top level. */
+function getPlace(atRules) {
+    const enclosing = atRules.filter(({ name }) => name !== 'layer').map(describeAtRule);
+    return { enclosing, layer: atRules.findLast(({ name }) => name === 'layer')?.params.trim() ?? null };
+}
+const isSpx = ({ prop }) => SPX_PROPS.includes(prop);
+/** A property's value as the import reads it: the last declaration wins. */
+function lastValue(root, prop) {
+    for (let i = root.declarations.length - 1; i >= 0; i--)
+        if (root.declarations[i].prop === prop)
+            return root.declarations[i].value;
+    return undefined;
+}

package/dist/rules-adapter/index.js

@@ -0,0 +1,3 @@
+// Part 5 — rules adapter: runs the rules inside a lint tool (oxlint today). Everything that knows oxlint is in oxlint/.
+export { runRules } from "./oxlint/run-rules.js";
+export { createReport, createToolCallbacks } from "./utils.js";

package/dist/rules-adapter/oxlint/adapt-rule.js

@@ -0,0 +1,17 @@
+import { getOrCreateRulesApi } from "../../rules-api/index.js";
+import { createReport, createToolCallbacks } from "../utils.js";
+export function toOxlintRule(rule) {
+    return {
+        meta: { type: 'problem' },
+        // oxlint calls this once per rule per file. The file's rules API is shared by every rule (getOrCreateRulesApi caches it).
+        create: (context) => {
+            const report = createReport((problem) => context.report(problem));
+            return createToolCallbacks(rule, { rulesApi: () => getOrCreateRulesApi(toLintedFile(context)), report, context });
+        },
+    };
+}
+/** oxlint already parsed the file: its syntax tree is reused instead of parsing it again. */
+function toLintedFile({ cwd, filename, sourceCode }) {
+    // oxlint's tree is oxc-parser's (oxlint runs on oxc), plus `parent`, `range` and `loc`. Their types are declared apart.
+    return { cwd, filename, text: sourceCode.text, program: sourceCode.ast };
+}

package/dist/rules-adapter/oxlint/callbacks.js

@@ -0,0 +1 @@
+export {};

package/dist/rules-adapter/oxlint/origami-rules.config.js

@@ -0,0 +1,12 @@
+// Passed to oxlint with -c by run-rules.ts. Not named oxlint.config.ts, so `oxlint .` in the origami repo does not load it as a nested config.
+import path from 'node:path';
+import { defineConfig } from 'oxlint';
+import { ruleRegistry } from "../../rules/index.js";
+/** Each rule on at its own severity. oxlint exits 0 when it finds only warnings, so warnings don't fail the lint. */
+export const ruleSeverities = (rules) => Object.fromEntries(rules.map(({ name, severity = 'error' }) => [`origami/${name}`, severity]));
+export default defineConfig({
+    // .ts in the origami repo, .js once built: the build rewrites imports, not this path.
+    jsPlugins: [path.join(import.meta.dirname, `oxlint-plugin${path.extname(import.meta.filename)}`)],
+    categories: { correctness: 'off' },
+    rules: ruleSeverities(ruleRegistry),
+});

package/dist/rules-adapter/oxlint/oxlint-plugin.js

@@ -0,0 +1,7 @@
+// The plugin oxlint loads when it starts: every rule as an oxlint rule.
+import { ruleRegistry } from "../../rules/index.js";
+import { toOxlintRule } from "./adapt-rule.js";
+export default {
+    meta: { name: 'origami' },
+    rules: Object.fromEntries(ruleRegistry.map((rule) => [rule.name, toOxlintRule(rule)])),
+};

package/dist/rules-adapter/oxlint/run-rules.js

@@ -0,0 +1,22 @@
+// Runs the rules with oxlint on the pages' structure files. Its config loads the rules (through oxlint-plugin.ts).
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { log } from "../../shared/log.js";
+import { ROOT } from "../../shared/paths.js";
+// oxlint is the lint's own dependency: found from here, wherever the package manager installed it.
+const OXLINT_BIN = path.join(path.dirname(createRequire(import.meta.url).resolve('oxlint/package.json')), 'bin/oxlint');
+// .ts in the origami repo, .js once built.
+const OXLINT_CONFIG = path.join(import.meta.dirname, `origami-rules.config${path.extname(import.meta.filename)}`);
+/** jsxFiles: the pages' structure files, from the site root. true when there was nothing to lint, or oxlint found no errors. */
+export function runRules(jsxFiles) {
+    const passed = runOxlint(jsxFiles);
+    log(passed ? 'rules passed' : 'rules failed');
+    return passed;
+}
+function runOxlint(files) {
+    if (files.length === 0)
+        return true;
+    const result = spawnSync(process.execPath, [OXLINT_BIN, '-c', OXLINT_CONFIG, ...files], { cwd: ROOT, stdio: 'inherit' });
+    return result.status === 0;
+}

package/dist/rules-adapter/tool-types.js

@@ -0,0 +1 @@
+export {};