@wix/origami-lint 0.0.0-stage → 1.34.1

package/dist/rules/breakpoints.js

@@ -0,0 +1,124 @@
+import { describeAtRule, reportCssProblem } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+/** The converter's shape for a declaration's name: a dashed identifier. */
+const DASHED_NAME = /^--[A-Za-z0-9_-]+$/;
+export default defineRule({
+    name: 'breakpoints',
+    editors: ['studio2'],
+    callbacks: {
+        Program: ({ rulesApi, report }) => {
+            const site = getSiteBreakpoints(rulesApi);
+            for (const file of getFileBreakpoints(rulesApi)) {
+                checkDeclarations(file, site, report);
+                checkNamedUses(file, site, report);
+                checkRanges(file, site, report);
+            }
+        },
+    },
+});
+// ── the steps ──
+/** Every `@custom-media` of a file: well formed (CONV-astParser.ts:328), its name declared once in the file (CONV-breakpoints.ts:197); in a page file, with a theme to compare with, also one of the site's names (:335) with its range (:339). theme.css's own are the site's. */
+function checkDeclarations(file, site, report) {
+    const first = new Map();
+    for (const declaration of file.declared) {
+        if (!isWellFormed(file, declaration, report))
+            continue;
+        if (!isFirstOfName(file, declaration, first, report))
+            continue;
+        if (file.isPage && site.hasTheme && isSiteName(file, declaration, site, report))
+            keepsSiteRange(file, declaration, site, report);
+    }
+}
+/** Reports a `@custom-media` without a dashed name or without a query (CONV-astParser.ts:328). */
+function isWellFormed(file, declaration, report) {
+    if (hasShape(declaration))
+        return true;
+    const params = `${declaration.name} ${declaration.query}`.trim();
+    reportCssProblem(report, file.name, declaration.line, `\`@custom-media ${params}\` isn't \`--<name> <media query>\`; write it like \`@custom-media --mobile (max-width: 750px);\` (tracker CONV-astParser.ts:328).`);
+    return false;
+}
+/** Reports a second `@custom-media` of a name the file already declares: the import can't tell two ranges with one name apart (CONV-breakpoints.ts:197). */
+function isFirstOfName(file, declaration, first, report) {
+    const earlier = first.get(declaration.name);
+    if (!earlier)
+        return first.set(declaration.name, declaration), true;
+    reportCssProblem(report, file.name, declaration.line, `\`@custom-media ${declaration.name}\` is declared again (first at ${file.name}:${earlier.line}). The import can't tell two ranges with one name apart: keep one (tracker CONV-breakpoints.ts:197).`);
+    return false;
+}
+/** Reports a page file's declaration whose name isn't one of the site's (CONV-astParser.ts:335). */
+function isSiteName(file, declaration, site, report) {
+    const names = site.breakpoints.map(({ name }) => name);
+    if (names.includes(declaration.name))
+        return true;
+    reportCssProblem(report, file.name, declaration.line, `\`@custom-media ${declaration.name}\` isn't one of the site's named breakpoints (the theme has ${names.join(', ') || 'none'}). Use a range the site declares; breakpoints are added in the editor, not in CSS (tracker CONV-astParser.ts:335).`);
+    return false;
+}
+/** Reports a page file's declaration whose range isn't the site's for that name, to the letter: the import compares the text (CONV-astParser.ts:339). */
+function keepsSiteRange(file, declaration, site, report) {
+    const exported = getSiteRange(declaration.name, site);
+    if (exported.trim() === declaration.query.trim())
+        return true;
+    reportCssProblem(report, file.name, declaration.line, `\`@custom-media ${declaration.name} ${declaration.query}\` changes the site's range for ${declaration.name}, which is \`${exported}\`. Restore it; a breakpoint's width is changed in the editor, not in CSS (tracker CONV-astParser.ts:339).`);
+    return false;
+}
+/** Reports a `@media (--name)` with no declaration of that name in the same file (CONV-breakpoints.ts:57). A malformed declaration of the name (its own line) counts as the declaration, so the use gets no second line. */
+function checkNamedUses(file, site, report) {
+    const declared = new Set(file.declared.flatMap(({ name }) => [name, `--${name}`]));
+    for (const { name, line } of file.used) {
+        if (!name || declared.has(name))
+            continue;
+        const range = getSiteRange(name, site);
+        const fix = range
+            ? `add \`@custom-media ${name} ${range};\` at the top of ${file.name}, or write the range itself, \`@media ${range}\``
+            : `add \`@custom-media ${name} (<its range>);\` at the top of ${file.name} (the range the site gives it), or write the range itself`;
+        reportCssProblem(report, file.name, line, `\`@media (${name})\` uses a name the file doesn't declare: ${fix} (tracker CONV-breakpoints.ts:57).`);
+    }
+}
+/** Reports each `@media` of a file whose range is none of the site's (P4-R01, CONV-breakpoints.ts:75); nothing without a theme to compare with. A name is read through the file's declaration when that declaration is the site's; otherwise the steps above report it. A component's own breakpoint (inside `@scope`) is compared once unmapped.json is read. */
+function checkRanges(file, site, report) {
+    if (!site.hasTheme)
+        return;
+    for (const media of file.used) {
+        if (media.scope !== null)
+            continue;
+        const query = resolve(media, file.declared, site);
+        if (query === null || site.breakpoints.some((breakpoint) => canonical(breakpoint.query) === canonical(query)))
+            continue;
+        reportCssProblem(report, file.name, media.line, `\`${describeAtRule({ name: 'media', params: media.query })}\` is a breakpoint the site doesn't have. Write one of the theme's breakpoints: ${describe(site.breakpoints)} (rule P4-R01; tracker CONV-breakpoints.ts:75). The import refuses a value for a breakpoint the site doesn't have.`);
+    }
+}
+// ── reading the files ──
+/** The site's breakpoints from theme.css: its well-formed `@custom-media` (a malformed one is the shape step's). */
+const getSiteBreakpoints = (rulesApi) => ({ hasTheme: rulesApi.page.css.files.theme !== undefined, breakpoints: rulesApi.getCustomMedia('theme').filter(hasShape) });
+/** For layout.css, style.css and theme.css: the breakpoints each declares (`@custom-media`) and uses (`@media`). */
+const getFileBreakpoints = (rulesApi) => ['layout', 'style', 'theme'].map((kind) => {
+    const isPage = kind !== 'theme';
+    return { name: `${kind}.css`, isPage, declared: rulesApi.getCustomMedia(kind), used: getMedia(rulesApi.page.css.files[kind], isPage, rulesApi) };
+});
+/** Every `@media` a file writes, in order. In a page file: not inside the file's own `@mixin` (no-page-mixin's), and only one with a block. In theme.css: every one, inside its mixins too. */
+function getMedia(file, isPage, rulesApi) {
+    const media = [];
+    file?.walkAtRules('media', (node) => {
+        const around = rulesApi.getEnclosingAtRules(node);
+        if (isPage && (!node.nodes || around.some(({ name }) => name === 'mixin')))
+            return;
+        const query = node.params.trim();
+        media.push({ query, name: rulesApi.getBreakpointName(query), line: node.source?.start?.line ?? 1, scope: around.findLast(({ name }) => name === 'scope')?.params.trim() ?? null });
+    });
+    return media;
+}
+const hasShape = ({ name, query }) => DASHED_NAME.test(name) && query !== '';
+/** The site's range for a name; undefined when the theme has no well-formed declaration of it. */
+const getSiteRange = (name, site) => site.breakpoints.find((breakpoint) => breakpoint.name === name)?.query;
+/** The range to compare: the @media's own; for `(--name)`, the range the file declares for it, when that declaration is the site's name with the site's range (otherwise the steps above report it); null when there is nothing to compare. */
+function resolve(media, declarations, site) {
+    if (!media.name)
+        return media.query;
+    const declaration = declarations.find((entry) => entry.name === media.name && hasShape(entry));
+    const exported = getSiteRange(media.name, site);
+    return declaration && exported !== undefined && exported.trim() === declaration.query.trim() ? declaration.query : null;
+}
+/** How the import reads a range: `(max-width:1023px)` and `(max-width: 1023px)` are the same; anything else, a different case or other spaces included, is another query. */
+const canonical = (query) => query.trim().replace(/:\s+/g, ':');
+// ── reporting ──
+const describe = (site) => site.length ? site.map(({ query, line }) => `\`@media ${query}\` (theme.css:${line})`).join(', ') : 'none: theme.css declares no @custom-media';

package/dist/rules/css-file-nesting.js

@@ -0,0 +1,196 @@
+import { BREAKPOINT_AT_RULES, createCssFileReporter, describeAtRule, getCssChildren, ORIGAMI_TARGETS, PREAMBLE_LAYER } from "../rules-api/index.js";
+import { defineRule } from "./define-rule.js";
+/** The import's leading-import line (cssFileParser.ts `IMPORT_LINE_PATTERN`). */
+const IMPORT_LINE = /^@import '([^']+)';$/;
+export default defineRule({
+    name: 'css-file-nesting',
+    editors: ['studio2'],
+    callbacks: {
+        Program: ({ rulesApi, report }) => {
+            for (const kind of ['layout', 'style', 'theme']) {
+                const root = rulesApi.page.css.files[kind];
+                if (root)
+                    checkTopLevel(root, `${kind}.css`, report);
+            }
+        },
+    },
+});
+// ── the steps ──
+/** The file's top level: imports, at-rules, declarations, rules and breakpoint blocks (CONV-fromBundle.ts:987, CONV-utils.ts:92, :76, CONV-astParser.ts:412). */
+function checkTopLevel(root, file, report) {
+    const reportInFile = createCssFileReporter(file, report);
+    const leadingImportLines = file === 'theme.css' ? 0 : countLeadingImportLines(root.source?.input.css ?? '');
+    for (const node of root.nodes) {
+        if (node.type === 'comment')
+            continue;
+        if (node.type === 'atrule' && node.name === 'layer' && node.params.trim() === PREAMBLE_LAYER)
+            continue;
+        if (node.type === 'rule')
+            checkRule(node, file, reportInFile);
+        else if (node.type === 'decl')
+            checkTopLevelDeclaration(node, file, reportInFile);
+        else if (node.type === 'atrule')
+            checkTopAtRule(node, file, (node.source?.start?.line ?? 0) <= leadingImportLines, reportInFile);
+    }
+}
+function checkTopAtRule(node, file, isLeadingImport, reportInFile) {
+    if (node.name === 'import' && isLeadingImport)
+        return reportInFile(node, `\`@import ${node.params.trim()}\` can't be in ${file}: an item's CSS carries no imports (the preview loads the theme from _generated/). Remove the line (tracker CONV-fromBundle.ts:987).`);
+    if (node.name === 'custom-media')
+        return;
+    if (node.name === 'mixin' && file !== 'layout.css')
+        return checkMixin(node, reportInFile);
+    if (node.name === 'scope' && file === 'layout.css')
+        return checkLayoutScope(node, reportInFile);
+    if (!hasBlock(node, reportInFile))
+        return;
+    if (BREAKPOINT_AT_RULES.includes(node.name))
+        return checkBreakpoint(node, file, reportInFile);
+    reportInFile(node, `\`@${node.name}\` isn't part of the export format at the top of ${file}. At the top level only @media, @scope, @custom-media${file === 'layout.css' ? '' : ' and @mixin'} are allowed${pageMixinNote(file)} (tracker CONV-utils.ts:92).`);
+}
+/** Reports a bare declaration at the top of layout.css (CONV-astParser.ts:412); style.css and theme.css drop one silently. */
+function checkTopLevelDeclaration(node, file, reportInFile) {
+    if (file !== 'layout.css')
+        return;
+    reportInFile(node, `\`${node.prop}: ${node.value}\` is at the top level. Put the declaration inside the element's rule (\`.comp-a { … }\`) (tracker CONV-astParser.ts:412).`);
+}
+/** A layout `@scope` holds exactly one `@media`, checked before its block (CONV-astParser.ts:399, as parseCssAst does). */
+function checkLayoutScope(node, reportInFile) {
+    const scopeChildren = node.nodes === undefined ? [] : getCssChildren(node);
+    if (scopeChildren.length !== 1 || !isMedia(scopeChildren[0])) {
+        return reportInFile(node, `\`@scope ${node.params.trim()}\` must hold exactly one \`@media (…) { … }\` block. Put the rules inside one @media in the @scope (tracker CONV-astParser.ts:399).`);
+    }
+    if (hasBlock(scopeChildren[0], reportInFile))
+        checkBreakpointContent(scopeChildren[0], 'layout.css', reportInFile);
+}
+/** A top-level style or theme `@media` / `@scope` (its block checked already). */
+function checkBreakpoint(node, file, reportInFile) {
+    const media = getScopedMedia(node, reportInFile);
+    if (media)
+        checkBreakpointContent(media, file, reportInFile);
+}
+/** The `@media` a breakpoint at-rule stands for, following `@scope` → its first child as the import does (CONV-utils.ts:92, :76); null after reporting. */
+function getScopedMedia(node, reportInFile) {
+    let current = node;
+    while (current.name === 'scope') {
+        const first = getCssChildren(current)[0];
+        if (first?.type === 'atrule' && first.name === 'scope') {
+            if (!hasBlock(first, reportInFile))
+                return null;
+            current = first;
+            continue;
+        }
+        if (!isMedia(first)) {
+            reportInFile(current, `\`@scope ${current.params.trim()}\` must start with a \`@media (…) { … }\` block: put the rules inside it (tracker CONV-utils.ts:92).`);
+            return null;
+        }
+        if (!hasBlock(first, reportInFile))
+            return null;
+        current = first;
+    }
+    return current;
+}
+/** A breakpoint block holds element rules only (CONV-astParser.ts:147, :151). */
+function checkBreakpointContent(media, file, reportInFile) {
+    for (const child of getCssChildren(media)) {
+        if (child.type === 'rule')
+            checkRule(child, file, reportInFile);
+        else if (child.type === 'atrule')
+            reportInFile(child, `\`@${child.name}\` inside \`${describeAtRule(media)}\` is not allowed. A breakpoint block holds only element rules: declare \`@mixin\` at the top level${pageMixinNote(file)} and put its breakpoint variant in a \`@media\` inside its \`@result\`; don't nest one \`@media\` in another (tracker CONV-astParser.ts:147).`);
+        else if (child.type === 'decl')
+            reportInFile(child, `\`${child.prop}: ${child.value}\` sits directly in \`${describeAtRule(media)}\`. Wrap it in the element's rule: \`@media (…) { .comp-a { … } }\` (tracker CONV-astParser.ts:151).`);
+    }
+}
+/** Reports an at-rule written without a block (CONV-utils.ts:76): the import reads every top-level at-rule but `@custom-media` and `@mixin` as a breakpoint. */
+function hasBlock(node, reportInFile) {
+    if (node.nodes !== undefined)
+        return true;
+    reportInFile(node, `\`${describeAtRule(node)}\` has no block. Give it a \`{ … }\` block with the element rules, or remove it (tracker CONV-utils.ts:76).`);
+    return false;
+}
+/** An element rule: layout's (CONV-astParser.ts:74, :51, :54, :57) or style's and theme's (CONV-astParser.ts:95). */
+function checkRule(rule, file, reportInFile) {
+    if (file === 'layout.css')
+        checkLayoutRule(rule, reportInFile);
+    else
+        checkStyleRule(rule, reportInFile);
+}
+function checkLayoutRule(rule, reportInFile) {
+    const selector = rule.selector.trim();
+    const seenTargets = new Set();
+    for (const child of getCssChildren(rule)) {
+        if (child.type === 'decl')
+            continue;
+        if (child.type === 'atrule' && child.name === 'origami-target') {
+            checkOrigamiTarget(child, selector, seenTargets, reportInFile);
+            continue;
+        }
+        const what = child.type === 'rule' ? `the rule \`${child.selector.trim()}\`` : `\`${describeAtRule(child)}\``;
+        const fix = child.type === 'rule' ? 'Write it as its own rule' : child.name === 'media' ? `Move it out: \`@media (…) { ${selector} { … } }\` at the top level` : 'Move it out of the rule';
+        reportInFile(child, `rule \`${selector}\`: ${what} can't be inside a layout rule, which holds only declarations and @origami-target blocks. ${fix} (tracker CONV-astParser.ts:74).`);
+    }
+}
+/** An `@origami-target`: a block (CONV-astParser.ts:51), a known name (:54), once per rule (:57), only declarations (:51), in the converter's order. */
+function checkOrigamiTarget(node, selector, seenTargets, reportInFile) {
+    const target = node.params.trim();
+    const reportTargetShape = (fix) => reportInFile(node, `rule \`${selector}\`: \`@origami-target ${target}\` holds only declarations, in a \`{ … }\` block. ${fix} (tracker CONV-astParser.ts:51).`);
+    if (node.nodes === undefined)
+        return reportTargetShape("Give it a block with the container's declarations");
+    if (!ORIGAMI_TARGETS.includes(target))
+        return reportInFile(node, `rule \`${selector}\`: \`@origami-target ${target}\` is not a known target. Use \`@origami-target ${ORIGAMI_TARGETS[0]}\` or \`@origami-target ${ORIGAMI_TARGETS[1]}\` (tracker CONV-astParser.ts:54).`);
+    if (seenTargets.has(target))
+        return reportInFile(node, `rule \`${selector}\`: \`@origami-target ${target}\` appears twice. Merge the two blocks into one (tracker CONV-astParser.ts:57).`);
+    seenTargets.add(target);
+    const nested = getCssChildren(node).find((child) => child.type !== 'decl');
+    if (!nested)
+        return;
+    reportTargetShape(nested.type === 'atrule' && nested.name === 'media' ? `Move the \`@media\` out and around the whole rule: \`@media (…) { ${selector} { @origami-target … { … } } }\`` : 'Move it out of the block');
+}
+/** Reports an at-rule other than `@apply` inside a style rule, or a `@mixin`'s `&` rule (CONV-astParser.ts:95). A nested rule is dropped by the import, not refused. */
+function checkStyleRule(rule, reportInFile) {
+    const selector = rule.selector.trim();
+    for (const child of getCssChildren(rule)) {
+        if (child.type === 'atrule' && child.name !== 'apply') {
+            reportInFile(child, `rule \`${selector}\`: \`@${child.name}\` can't be nested in a style rule. Put the rule inside it instead: \`@media (…) { ${selector} { … } }\` (in a @mixin: \`@result { @media (…) { &… { … } } }\`) (tracker CONV-astParser.ts:95).`);
+        }
+    }
+}
+/** A `@mixin`'s `@result`: its `&` rules hold no at-rule but `@apply` (CONV-astParser.ts:95); its breakpoint blocks have a block (CONV-utils.ts:76) and a `@scope` starts with a `@media` (CONV-utils.ts:92). The rest of a mixin's shape is the global-styles rows'. */
+function checkMixin(node, reportInFile) {
+    for (const child of getCssChildren(node)) {
+        if (child.type !== 'atrule' || child.name !== 'result')
+            continue;
+        checkMixinLevel(getCssChildren(child), reportInFile, true);
+    }
+}
+/** One level of a `@mixin`'s `@result`: its `&` rules, and (at the first level) its breakpoint blocks, whose content is the next level. */
+function checkMixinLevel(nodes, reportInFile, allowBreakpoints) {
+    for (const child of nodes) {
+        if (child.type === 'rule') {
+            const selector = child.selector.trim();
+            if (selector.startsWith('&') && selector !== '&')
+                checkStyleRule(child, reportInFile);
+        }
+        else if (child.type === 'atrule' && allowBreakpoints && BREAKPOINT_AT_RULES.includes(child.name)) {
+            if (!hasBlock(child, reportInFile))
+                continue;
+            const media = getScopedMedia(child, reportInFile);
+            if (media)
+                checkMixinLevel(getCssChildren(media), reportInFile, false);
+        }
+    }
+}
+// ── reading the tree ──
+const isMedia = (node) => node?.type === 'atrule' && node.name === 'media';
+/** How many lines the import strips as leading imports: from the first line, each matching its pattern, no blank line between. A line
+ * ending in `\r\n` keeps its `\r` and doesn't match, as in the import (`extractLeadingCssImports` splits on `\n` too). */
+function countLeadingImportLines(css) {
+    const lines = css.split('\n');
+    let count = 0;
+    while (count < lines.length && IMPORT_LINE.test(lines[count]))
+        count += 1;
+    return count;
+}
+// ── reporting ──
+/** A page's style.css reads a `@mixin` only as one of the site's global styles (fromBundle.ts:1395, styleParser.ts:798); no note elsewhere. */
+const pageMixinNote = (file) => (file === 'style.css' ? " (in a page's style.css, only for a global style the site already has)" : '');