@wix/origami-lint 0.0.0-stage → 1.34.2

package/dist/rules/global-styles.js

@@ -0,0 +1,215 @@
+import { BREAKPOINT_AT_RULES, createCssFileReporter, describeAtRule, getCssChildren, getDashedId, getSegmentClass, getSelectorSegments, isCssIdentifier, isSafeCssIdentifier } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+export default defineRule({
+    name: 'global-styles',
+    editors: ['studio2'],
+    callbacks: {
+        Program: ({ rulesApi, report }) => {
+            const { files } = rulesApi.page.css;
+            if (files.style)
+                checkMixinsAndLinks(files.style, 'style.css', report);
+            if (files.theme)
+                checkMixinsAndLinks(files.theme, 'theme.css', report);
+        },
+    },
+});
+// ── the steps ──
+/** The file's top-level `@mixin`s, each checked on its own; then the links between them (CONV-styleParser.ts). */
+function checkMixinsAndLinks(root, file, report) {
+    const reportInFile = createCssFileReporter(file, report);
+    const mixins = getCssChildren(root).filter((node) => node.type === 'atrule' && node.name === 'mixin');
+    const rules = mixins.flatMap((mixin) => checkMixin(mixin, reportInFile));
+    const declaredIds = new Set(mixins.flatMap((mixin) => getMixinId(mixin) ?? []));
+    const linkedParts = checkLinks(rules.filter((rule) => rule.apply), declaredIds, reportInFile);
+    for (const group of groupBySelector(rules))
+        checkLinkOrValues(group, linkedParts, reportInFile);
+}
+/** `@mixin --id { @result { … } }` (CONV-astParser.ts:287, :293), then its `@result`; returns its `&` rules that pass. */
+function checkMixin(mixin, reportInFile) {
+    const id = getMixinId(mixin);
+    if (id === null) {
+        reportInFile(mixin, getMixinIdMessage(mixin.params.trim()));
+        return [];
+    }
+    const result = getResult(mixin);
+    if (!result) {
+        reportInFile(mixin, `\`@mixin --${id}\` must be \`@mixin --${id} { @result { … } }\`. Put everything inside one \`@result { }\` (tracker CONV-astParser.ts:293).`);
+        return [];
+    }
+    const rules = [];
+    checkResultLevel(getCssChildren(result), id, undefined, rules, reportInFile);
+    return rules.filter((rule) => checkSelector(rule, reportInFile));
+}
+/** One level of `@result`: its top, or a breakpoint block in it (CONV-astParser.ts:195–254, walkMixinResultNodes). */
+function checkResultLevel(nodes, id, breakpoint, rules, reportInFile) {
+    for (const node of nodes) {
+        if (node.type === 'rule')
+            checkMixinRule(node, id, breakpoint, rules, reportInFile);
+        else if (node.type === 'atrule')
+            checkResultAtRule(node, id, breakpoint, rules, reportInFile);
+    }
+}
+/** An `&` rule: starts with `&` (:195), not a bare `&` (:198), no nested rule (:204); kept when it's a value rule or a link. */
+function checkMixinRule(node, id, breakpoint, rules, reportInFile) {
+    const selector = node.selector.trim();
+    const inner = getCssChildren(node);
+    if (!selector.startsWith('&'))
+        return reportInFile(node, `\`@mixin --${id}\`: selector \`${selector}\` must start with \`&\`. Write \`& ${selector}\` (or \`&:hover\`) (tracker CONV-astParser.ts:195).`);
+    if (selector === '&')
+        return reportInFile(node, getBareAmpersandMessage(id, inner));
+    const nested = inner.find((child) => child.type === 'rule');
+    if (nested)
+        return reportInFile(nested, `\`@mixin --${id}\`: a rule is nested in \`${selector}\`. Write the whole selector on one rule: \`${joinSelectors(selector, nested.selector.trim())} { … }\` (tracker CONV-astParser.ts:204).`);
+    const atRules = inner.filter((child) => child.type === 'atrule');
+    const applies = atRules.filter((child) => child.name === 'apply');
+    // another at-rule (CONV-astParser.ts:211) is css-file-nesting's; two `@apply`s, one beside declarations, or one that isn't
+    // `@apply --id;` (CONV-astParser.ts:41), apply-and-presets': none is a link
+    if (applies.length < atRules.length || applies.length > 1 || (applies.length === 1 && (inner.some((child) => child.type === 'decl') || !isApplyWritten(applies[0]))))
+        return;
+    rules.push({ mixin: id, selector, node, breakpoint, apply: applies[0] });
+}
+/** An at-rule in `@result`: no `@apply` (:246), no `@mixin` (:251); only `@media` / `@scope` at its top, none inside them (:254). */
+function checkResultAtRule(node, id, breakpoint, rules, reportInFile) {
+    if (node.name === 'apply')
+        return reportInFile(node, `\`@mixin --${id}\`: \`@apply\` can't sit at the root of \`@result\`. Remove it, or move it into an inner part's rule: \`& .label { @apply ${node.params.trim()}; }\` (tracker CONV-astParser.ts:246).`);
+    if (node.name === 'mixin')
+        return reportInFile(node, `\`@mixin --${id}\`: \`@mixin ${node.params.trim()}\` is declared inside it. Declare each \`@mixin\` at the top level of the file (tracker CONV-astParser.ts:251).`);
+    if (breakpoint || !BREAKPOINT_AT_RULES.includes(node.name)) {
+        const where = breakpoint ? `\`${describeAtRule(breakpoint)}\` in \`@result\`` : '`@result`';
+        return reportInFile(node, `\`@mixin --${id}\`: \`@${node.name}\` is not allowed in ${where}. Use only \`@media\` / \`@scope\` directly inside \`@result\`, one level deep (tracker CONV-astParser.ts:254).`);
+    }
+    const media = getBreakpointBody(node);
+    if (media)
+        checkResultLevel(getCssChildren(media), id, node, rules, reportInFile);
+}
+/**
+ * Whether the rule's selector is one the links are read on: reports one that writes `&` again, or `:root`, after its start
+ * (CONV-cssSelectors.ts:351). A selector the import can't parse (invalidSelector) is the selectors rows', not read here: a list, an
+ * unbalanced bracket, `&` followed by anything but a state (`& > .label`, `&-x`, `&[data-state~="open"]`), an `&` inside a part (`.foo&`,
+ * `&:hover&`), a part that isn't a class (`& [data-ie-name="label"]:hover`). `:root` parses (parseSegment reads it as the root): :351's.
+ */
+function checkSelector(rule, reportInFile) {
+    const segments = getSelectorSegments(rule.selector);
+    if (segments === null || !/^&([:.[]|$)/.test(segments[0]) || segments.some((segment, index) => segment.indexOf('&', index === 0 ? 1 : 0) > 0))
+        return false;
+    if (segments.some((segment) => segment !== ':root' && getSegmentClass(segment) === null))
+        return false;
+    const repeated = segments.slice(1).find((segment) => segment.startsWith('&') || segment === ':root');
+    if (repeated === undefined)
+        return true;
+    const problem = repeated === ':root' ? 'has `:root` after `&`' : 'repeats `&`';
+    reportInFile(rule.node, `\`@mixin --${rule.mixin}\`: selector \`${rule.selector}\` ${problem}. Write \`&\` once, at the start of the selector (tracker CONV-cssSelectors.ts:351).`);
+    return false;
+}
+/** Each link, in the import's order (collectGlobalStyleLinks): no state (:655), no breakpoint (:664), a dashed id (:670) the file declares (:673), once per part (:677). Returns the parts a link names, by mixin. */
+function checkLinks(links, declaredIds, reportInFile) {
+    const linkedParts = new Set();
+    const validLinkParts = new Set();
+    for (const link of links) {
+        const child = link.apply.params.trim();
+        const linkDescription = `\`@mixin --${link.mixin}\`'s link \`@apply ${child}\``;
+        const fix = `write it as \`${getSelectorWithoutStates(link.selector)} { @apply ${child} }\``;
+        if (hasState(link.selector)) {
+            reportInFile(link.apply, `${linkDescription} can't be under a state or a breakpoint: ${fix} and put the state / breakpoint values in @mixin ${child} (tracker CONV-styleParser.ts:655).`);
+            continue;
+        }
+        if (link.breakpoint) {
+            reportInFile(link.apply, `${linkDescription} can't be under a state or a breakpoint: ${fix} outside \`${describeAtRule(link.breakpoint)}\`, and put the breakpoint values in @mixin ${child} (tracker CONV-styleParser.ts:655).`);
+            continue;
+        }
+        const part = getPartKey(link);
+        linkedParts.add(part);
+        const id = getDashedId(child);
+        if (!isSafeCssIdentifier(id)) {
+            reportInFile(link.apply, `\`@mixin --${link.mixin}\` links \`${child}\`, which is not a valid global style name: use letters, digits, - and _ (tracker CONV-styleParser.ts:670).`);
+            continue;
+        }
+        if (!declaredIds.has(id)) {
+            reportInFile(link.apply, `\`@mixin --${link.mixin}\` links \`${child}\`, but the file has no \`@mixin ${child}\`: add it (tracker CONV-styleParser.ts:673).`);
+            continue;
+        }
+        if (validLinkParts.has(part)) {
+            reportInFile(link.apply, `\`@mixin --${link.mixin}\` links two global styles at \`${getPart(link.selector)}\`: keep one (tracker CONV-styleParser.ts:677).`);
+            continue;
+        }
+        validLinkParts.add(part);
+    }
+    return linkedParts;
+}
+/** One selector of a mixin (across its breakpoints): a link alone, or values; values on an inner part where a link names it (CONV-styleParser.ts:803, :698). */
+function checkLinkOrValues(group, linkedParts, reportInFile) {
+    const link = group.find((rule) => rule.apply);
+    const values = group.filter((rule) => !rule.apply);
+    const [first] = group;
+    if (link && values.length > 0) {
+        return reportInFile(values[0].node, `\`${first.selector}\` of \`@mixin --${first.mixin}\` has both \`@apply ${link.apply.params.trim()}\` and values: move the values into @mixin ${link.apply.params.trim()} (tracker CONV-styleParser.ts:803).`);
+    }
+    const part = getPart(first.selector);
+    if (link || part === '' || linkedParts.has(getPartKey(first)))
+        return;
+    reportInFile(first.node, `\`@mixin --${first.mixin}\` styles \`${part}\` but links no global style there: add \`& ${part} { @apply --<child> }\` and move the values to that child's @mixin (tracker CONV-styleParser.ts:698).`);
+}
+// ── reading a mixin ──
+/** The id a `@mixin` declares (`--btn` → 'btn'), or null when it isn't one dashed identifier. */
+function getMixinId(mixin) {
+    const id = getDashedId(mixin.params);
+    return id !== undefined && isSafeCssIdentifier(id) ? id : null;
+}
+/** The mixin's one `@result` with no params and a block, beside nothing; undefined otherwise. */
+function getResult(mixin) {
+    if (mixin.nodes === undefined)
+        return undefined;
+    const [result, ...rest] = getCssChildren(mixin);
+    if (rest.length > 0 || result?.type !== 'atrule' || result.name !== 'result' || result.params.trim() || result.nodes === undefined)
+        return undefined;
+    return result;
+}
+/** The block a breakpoint in `@result` stands for: a `@media`'s own, a `@scope`'s first `@media` (utils.ts parseBreakpointAst). Undefined when it has none: css-file-nesting's rows. */
+function getBreakpointBody(node) {
+    let current = node;
+    while (current?.type === 'atrule' && current.name === 'scope' && current.nodes !== undefined)
+        current = getCssChildren(current)[0];
+    return current?.type === 'atrule' && current.name === 'media' && current.nodes !== undefined ? current : undefined;
+}
+/** A mixin's rules by selector, as the import groups its records (parseRecords): one group per mixin and selector, its breakpoints together. */
+function groupBySelector(rules) {
+    const groups = new Map();
+    for (const rule of rules) {
+        const key = `${rule.mixin}\0${rule.selector}`;
+        const group = groups.get(key);
+        if (group)
+            group.push(rule);
+        else
+            groups.set(key, [rule]);
+    }
+    return [...groups.values()];
+}
+// ── reading a selector ──
+const getSegments = (selector) => getSelectorSegments(selector) ?? [];
+/** The selector with no state: `&:hover .label` → `& .label`. */
+const getSelectorWithoutStates = (selector) => getSegments(selector).map((segment) => getSegmentClass(segment) ?? segment).join(' ');
+const hasState = (selector) => getSelectorWithoutStates(selector) !== getSegments(selector).join(' ');
+/** The inner part a selector styles, without states: `&:hover .label` → `.label`; '' for the mixin's own element. */
+const getPart = (selector) => getSegments(selector).slice(1).map((segment) => getSegmentClass(segment) ?? segment).join(' ');
+/** `@apply --id;`: one dashed id and no block, as the import reads it (applyTargetOf). */
+const isApplyWritten = (apply) => getDashedId(apply.params) !== undefined && getCssChildren(apply).length === 0;
+const getPartKey = (rule) => `${rule.mixin}\0${getPart(rule.selector)}`;
+/** A nested rule's selector written on its parent: `&:hover` + `& .label` (or `.label`) → `&:hover .label`. */
+const joinSelectors = (outer, inner) => (inner.includes('&') ? inner.replaceAll('&', outer) : `${outer} ${inner}`);
+// ── the messages ──
+/** `@mixin --btn:hover` → the dashed id to write, and where its state goes. */
+function getMixinIdMessage(params) {
+    const written = getDashedId(params);
+    if (written !== undefined && isCssIdentifier(written) && !isSafeCssIdentifier(written))
+        return `\`@mixin ${params}\`: \`${written}\` is reserved. Name the global style with another dashed identifier (\`@mixin --${written.replace(/^_+|_+$/g, '')}-style\`) (tracker CONV-astParser.ts:287).`;
+    const id = /^-*([_a-zA-Z][_a-zA-Z0-9-]*)/.exec(params)?.[1] ?? 'id';
+    const state = /[:[]/.test(params) ? `. Write the state as an \`&${params.slice(params.search(/[:[]/))} { … }\` rule inside \`@result\`` : '';
+    return `\`@mixin ${params}\` must name one dashed identifier (\`@mixin --${id}\`)${state} (tracker CONV-astParser.ts:287).`;
+}
+/** A bare `& { … }` (CONV-astParser.ts:198): its values go straight in `@result`; an `@apply` in it is the import's :658 case, refused here first. */
+function getBareAmpersandMessage(id, inner) {
+    const apply = inner.find((child) => child.type === 'atrule' && child.name === 'apply');
+    if (apply)
+        return `\`@mixin --${id}\` applies ${apply.params.trim()} to itself, which isn't supported: write the values in @mixin --${id}'s @result, or link a child on an inner part (\`& .label { @apply … }\`) (tracker CONV-astParser.ts:198, CONV-styleParser.ts:658).`;
+    return `\`@mixin --${id}\`: drop the \`& { }\` wrapper and write its declarations directly in \`@result\` (tracker CONV-astParser.ts:198).`;
+}

package/dist/rules/index.js

@@ -0,0 +1,16 @@
+import allowedImports from "./allowed-imports.js";
+import applyAndPresets from "./apply-and-presets.js";
+import bindings from "./bindings.js";
+import breakpoints from "./breakpoints.js";
+import cssFileNesting from "./css-file-nesting.js";
+import cssLayoutProperties from "./css-layout-properties.js";
+import dataValues from "./data-values.js";
+import globalStyles from "./global-styles.js";
+import noAbsoluteSection from "./no-absolute-section.js";
+import pageStructure from "./page-structure.js";
+import slotAttributes from "./slot-attributes.js";
+import themeFontIds from "./theme-font-ids.js";
+import themeRoot from "./theme-root.js";
+import noFreeCode from "./no-free-code.js";
+export const ruleRegistry = [allowedImports, noFreeCode, pageStructure, noAbsoluteSection, themeFontIds, slotAttributes, themeRoot, breakpoints, cssFileNesting, globalStyles, applyAndPresets, bindings, dataValues, cssLayoutProperties];
+export { defineRule } from "./define-rule.js";

package/dist/rules/no-absolute-section.js

@@ -0,0 +1,31 @@
+import { SECTIONS } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+export default defineRule({
+    name: 'no-absolute-section',
+    editors: 'all',
+    callbacks: {
+        JSXElement: (input) => {
+            const section = getSection(input);
+            if (section)
+                hasNoAbsolutePosition(section, input);
+        },
+    },
+});
+// ── the steps ──
+/** The section this element is; null for any other element, or JSX outside Structure. */
+function getSection({ node, rulesApi }) {
+    const type = rulesApi.getType(node);
+    return type && SECTIONS.includes(type) ? rulesApi.getComponent(node) : null;
+}
+/** Reports each `position: absolute` the section has, in any CSS, on any part of it, at any @media or @origami-target. */
+function hasNoAbsolutePosition(section, { rulesApi, report }) {
+    for (const decl of rulesApi.getCss(section, 'position').filter(isAbsolute)) {
+        report({ loc: section.loc, message: `Section ${section.key} has \`position: absolute\`${describeWhere(decl)}. Sections can't be absolutely positioned.` });
+    }
+}
+// ── reporting ──
+const isAbsolute = (decl) => decl.value.trim().toLowerCase() === 'absolute';
+function describeWhere({ media, selector }) {
+    const parts = [selector !== '&' && `\`${selector}\``, media && `@media ${media}`].filter(Boolean);
+    return parts.length ? ` (${parts.join(', ')})` : '';
+}

package/dist/rules/no-free-code.js

@@ -0,0 +1,112 @@
+import { STRUCTURE } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+const FREE_CODE = 'The import refuses this statement: a structure file holds only imports, `const` / `let` / `var` declarations and `export const Structure = () => …` (tracker CONV-parseJsx.ts:287).';
+const STRUCTURE_SHAPE = 'Declare Structure once, as `export const Structure = () => ( <Page …/> )`: an exported const arrow that returns the root element directly, with no `{ return … }`, fragment or condition around it (tracker CONV-parseJsx.ts:335).';
+const typeScript = (code) => `\`${code}\` is TypeScript. The import reads a structure file as plain JavaScript and fails on it: remove it (tracker CONV-parseJsx.ts:1845).`;
+/** Every statement type but ImportDeclaration (always allowed) and the TypeScript ones (TYPESCRIPT). */
+const STATEMENTS = [
+    'ExpressionStatement', 'ExportNamedDeclaration', 'ExportDefaultDeclaration', 'ExportAllDeclaration', 'VariableDeclaration',
+    'FunctionDeclaration', 'ClassDeclaration', 'BlockStatement', 'EmptyStatement', 'IfStatement', 'SwitchStatement', 'ForStatement',
+    'ForInStatement', 'ForOfStatement', 'WhileStatement', 'DoWhileStatement', 'BreakStatement', 'ContinueStatement', 'LabeledStatement',
+    'ThrowStatement', 'TryStatement', 'WithStatement', 'DebuggerStatement',
+];
+/** The TypeScript nodes that can sit where JavaScript is written; the other TS nodes are only inside these. */
+const TYPESCRIPT = [
+    'TSTypeAnnotation', 'TSTypeParameterDeclaration', 'TSTypeParameterInstantiation', 'TSAsExpression', 'TSSatisfiesExpression',
+    'TSNonNullExpression', 'TSTypeAssertion', 'TSInstantiationExpression', 'TSParameterProperty', 'TSIndexSignature', 'TSClassImplements',
+    'TSAbstractMethodDefinition', 'TSAbstractPropertyDefinition', 'TSAbstractAccessorProperty', 'TSEmptyBodyFunctionExpression',
+    'TSDeclareFunction', 'TSTypeAliasDeclaration', 'TSInterfaceDeclaration', 'TSEnumDeclaration', 'TSModuleDeclaration',
+    'TSImportEqualsDeclaration', 'TSExportAssignment', 'TSNamespaceExportDeclaration',
+    'ImportDeclaration', 'ImportSpecifier', 'ExportSpecifier',
+];
+export default defineRule({
+    name: 'no-free-code',
+    editors: 'all',
+    callbacks: {
+        ...on(STATEMENTS, isAllowedStatement),
+        ...on(TYPESCRIPT, hasNoTypeScript),
+        ArrowFunctionExpression: (input) => {
+            if (isStructureArrow(input.node))
+                returnsElement(input);
+        },
+    },
+});
+// ── the steps ──
+function isAllowedStatement({ node, rulesApi, report, context }) {
+    if (!isAtTop(node))
+        return;
+    if (rulesApi.isTypeScript(node))
+        return reportTypeScript(node, report, context);
+    const declaration = declarationOf(node);
+    if (rulesApi.isTypeScript(declaration)) {
+        // `export declare class` / `export abstract class`: no TYPESCRIPT callback sees a class or a variable, so it is reported here.
+        if (declaration && !TYPESCRIPT.includes(declaration.type))
+            reportTypeScript(declaration, report, context);
+        return;
+    }
+    if (isTypeOnlyExport(node, rulesApi))
+        return;
+    if (declaresStructure(node)) {
+        if (!structureArrowOf(node))
+            report({ loc: node.loc, message: STRUCTURE_SHAPE });
+        return;
+    }
+    // The import drops every variable declaration before it checks the statements (parseJsx.ts rejectTopLevelStatements).
+    if (declaration?.type !== 'VariableDeclaration')
+        report({ loc: node.loc, message: FREE_CODE });
+}
+/** Skips a file with no root element (page-structure reports it) and a body that is TypeScript (hasNoTypeScript reports it). */
+function returnsElement({ node, rulesApi, report }) {
+    const body = unwrap(node.body);
+    if (body.type === 'JSXElement' || rulesApi.isTypeScript(body) || !rulesApi.getRoot())
+        return;
+    report({ loc: node.body.loc, message: STRUCTURE_SHAPE });
+}
+/** In a structure.jsx it doesn't parse; this is for a structure.tsx, which the import parses as JavaScript too. */
+function hasNoTypeScript({ node, rulesApi, report, context }) {
+    if (rulesApi.isTypeScript(node) && !isInsideTypeScript(node, rulesApi))
+        reportTypeScript(node, report, context);
+}
+function reportTypeScript(node, report, context) {
+    report({ loc: node.loc, message: typeScript(shortCode(context.sourceCode.getText(node))) });
+}
+// ── reading the code ──
+function on(names, check) {
+    return Object.fromEntries(names.map((name) => [name, check]));
+}
+const isAtTop = (node) => node.parent?.type === 'Program';
+function isInsideTypeScript(node, rulesApi) {
+    for (let up = node.parent; up; up = up.parent)
+        if (rulesApi.isTypeScript(up))
+            return true;
+    return false;
+}
+const declarationOf = (node) => node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration' ? node.declaration : node;
+function declaresStructure(node) {
+    const declaration = declarationOf(node);
+    if (declaration?.type === 'VariableDeclaration')
+        return declaration.declarations.some(({ id }) => id.type === 'Identifier' && id.name === STRUCTURE);
+    return (declaration?.type === 'FunctionDeclaration' || declaration?.type === 'ClassDeclaration') && declaration.id?.name === STRUCTURE;
+}
+function structureArrowOf(node) {
+    if (node.type !== 'ExportNamedDeclaration' || node.declaration?.type !== 'VariableDeclaration' || node.declaration.kind !== 'const')
+        return null;
+    // The import sees no declaration at all in a const with a `{ a } = …` or a `b` with no value next to Structure (parseModule.ts isNamed).
+    const { declarations } = node.declaration;
+    if (!declarations.every(({ id, init }) => id.type === 'Identifier' && init))
+        return null;
+    const init = declarations.find(({ id }) => id.type === 'Identifier' && id.name === STRUCTURE)?.init;
+    // Parameters and `async` pass: the import reads only the arrow's body (parseJsx.ts structureElementOrIssue).
+    return init?.type === 'ArrowFunctionExpression' ? init : null;
+}
+/** `export { type Y } from 'x'` is TypeScript, reported once by its specifier (hasNoTypeScript), not as free code too. */
+const isTypeOnlyExport = (node, rulesApi) => node.type === 'ExportNamedDeclaration' && !node.declaration && node.specifiers.length > 0 && node.specifiers.every(rulesApi.isTypeScript);
+function isStructureArrow(node) {
+    const statement = node.parent.parent?.parent;
+    return statement?.type === 'ExportNamedDeclaration' && isAtTop(statement) && structureArrowOf(statement) === node;
+}
+const unwrap = (node) => (node.type === 'ParenthesizedExpression' ? node.expression : node);
+function shortCode(code) {
+    const [line] = code.trim().split('\n');
+    return line.length > 40 ? `${line.slice(0, 40)}…` : line;
+}