@wix/origami-lint 0.0.0-stage → 1.34.1

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @wix/origami-lint (POC)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline lint for an exported Origami site. Each run lints only the pages whose files changed since the last passing
+run (every page when `theme.css` changed), and runs every rule on every component of those pages.
+The rules run as plain oxlint rules.
+
+Published to the Wix registry (public npm later). How the lint works, its parts and how to write a rule:
+[lint/README.md](lint/README.md).
+
+## In a site
+
+`export-site` adds the lint to every exported site, in the site's root `package.json`: `@wix/origami-lint` in the dev
+dependencies and a `lint` script (`origami-lint`). It also writes the root `.gitignore` (the lint snapshots every file
+git doesn't ignore) and runs `git init` at the end (the lint keeps the last passing version in the site's repository).
+
+The lint runs only from the site's root: the folder it starts in is the site, and it stops unless that folder's
+`package.json` has `@wix/origami-lint` and the folder holds the git repository.
+
+```bash
+yarn install                       # at the site's root
+yarn lint                          # what changed since the last passing run
+yarn lint --full                   # everything
+ORIGAMI_LINT_BASE=main yarn lint   # compare with a git ref; never saved as passing
+yarn up @wix/origami-lint          # a new lint version: the next run checks everything
+```
+
+## Develop
+
+```bash
+pnpm --filter @wix/origami-lint run build     # typecheck (tsc -p .), then lint/ → dist/ (tsconfig.build.json)
+pnpm --filter @wix/origami-lint run test
+pnpm --filter @wix/origami-lint run lint
+```
+
+```
+lint/        the source (lint.ts is the entry point and the origami-lint bin)
+dist/        lint/ built to JavaScript: what the package publishes (Node won't run .ts inside node_modules)
+test/        rules on in-memory pages, CSS, the pages to lint, the oxlint adapter; history, the site root and a whole run on temporary repositories
+```
+
+The oxlint config is `lint/rules-adapter/oxlint/origami-rules.config.ts`, passed to oxlint with `-c`. It is not named
+`oxlint.config.ts`, so `oxlint .` in this repo doesn't load it as a nested config.

package/dist/history/changed-files.js

@@ -0,0 +1,42 @@
+// Which files changed since the last passing run. Now = the tree hash of the whole folder, committed or not,
+// taken with a private index file, so your staging area, branches and history are never touched.
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { log } from "../shared/log.js";
+import { LINT_DIR } from "../shared/paths.js";
+import { lastPassingVersion } from "./last-passing.js";
+import { git, gitList } from "./utils.js";
+const PRIVATE_INDEX = { GIT_INDEX_FILE: path.join(LINT_DIR, 'index') };
+/** `--full`: compare with nothing. `ORIGAMI_LINT_BASE=main`: compare with main instead of the last passing run. */
+export function getChangedFiles() {
+    const base = process.env.ORIGAMI_LINT_BASE;
+    const now = takeSnapshot();
+    const before = findVersionToCompareWith(base);
+    const changedFiles = {
+        now,
+        since: before && (base ?? before.slice(0, 7)),
+        comparedWithBase: Boolean(base),
+        changed: before ? gitList(['diff', '--name-only', '-z', '--no-renames', before, now]) : null,
+        all: gitList(['ls-tree', '-r', '-z', '--name-only', now]),
+    };
+    logChangedFiles(changedFiles);
+    return changedFiles;
+}
+function takeSnapshot() {
+    mkdirSync(LINT_DIR, { recursive: true });
+    git(['add', '-A'], PRIVATE_INDEX);
+    return git(['write-tree'], PRIVATE_INDEX);
+}
+function findVersionToCompareWith(base) {
+    if (process.argv.includes('--full'))
+        return null;
+    if (base)
+        return git(['rev-parse', base]);
+    return lastPassingVersion();
+}
+function logChangedFiles({ since, changed }) {
+    if (!changed)
+        log('all files (nothing to compare with)');
+    else
+        log(`${changed.length} files changed since ${since}`);
+}

package/dist/history/index.js

@@ -0,0 +1,3 @@
+// Part 1 — history: which files changed since the last passing run, and saving a run as passing. The only part that knows git.
+export { getChangedFiles } from "./changed-files.js";
+export { markPassing } from "./last-passing.js";

package/dist/history/last-passing.js

@@ -0,0 +1,44 @@
+// The last passing run: its snapshot, stored as a git ref, and the lint version that passed it, stored in .lint/.
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { log } from "../shared/log.js";
+import { LINT_DIR, LINT_PACKAGE_FILE } from "../shared/paths.js";
+import { git } from "./utils.js";
+const LAST_PASSING_REF = 'refs/origami/last-valid';
+const LAST_PASSING_FILE = path.join(LINT_DIR, 'last-passing.json');
+const LINT_VERSION = JSON.parse(readFileSync(LINT_PACKAGE_FILE, 'utf8')).version;
+/** null = nothing to compare with: nothing passed yet, or another lint version passed it (its rules may differ). */
+export function lastPassingVersion() {
+    const snapshot = lastPassingSnapshot();
+    if (!snapshot)
+        return null;
+    const passedWith = lastPassingLintVersion();
+    if (passedWith === LINT_VERSION)
+        return snapshot;
+    log(`the lint changed since the last passing run (${passedWith ?? 'unknown'} → ${LINT_VERSION})`);
+    return null;
+}
+/** The next run compares with the version that just passed. */
+export function markPassing({ now, comparedWithBase }) {
+    if (comparedWithBase)
+        return log('not saved as passing: compared with ORIGAMI_LINT_BASE');
+    git(['update-ref', LAST_PASSING_REF, now]);
+    writeFileSync(LAST_PASSING_FILE, `${JSON.stringify({ lintVersion: LINT_VERSION }, null, 2)}\n`);
+    log('saved as passing: the next run compares with now');
+}
+function lastPassingSnapshot() {
+    try {
+        return git(['rev-parse', '--verify', '--quiet', LAST_PASSING_REF]);
+    }
+    catch {
+        return null;
+    }
+}
+function lastPassingLintVersion() {
+    try {
+        return JSON.parse(readFileSync(LAST_PASSING_FILE, 'utf8')).lintVersion;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/history/utils.js

@@ -0,0 +1,13 @@
+// Git commands used by history.
+import { execFileSync } from 'node:child_process';
+import { ROOT } from "../shared/paths.js";
+function runGit(args, env = {}) {
+    return execFileSync('git', args, { cwd: ROOT, maxBuffer: 256 * 2 ** 20, env: { ...process.env, ...env } });
+}
+export function git(args, env) {
+    return runGit(args, env).toString('utf8').trim();
+}
+/** Output of a `-z` command, split on NUL. */
+export function gitList(args) {
+    return runGit(args).toString('utf8').split('\0').filter(Boolean);
+}

package/dist/lint.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Origami lint: lints the pages whose files changed since the last passing run. See lint/README.md.
+import { getChangedFiles, markPassing } from "./history/index.js";
+import { runRules } from "./rules-adapter/index.js";
+import { findPagesToLint } from "./page-model/index.js";
+import { checkStartedAtSiteRoot } from "./shared/paths.js";
+checkStartedAtSiteRoot();
+const changedFiles = getChangedFiles();
+const pagesToLint = findPagesToLint(changedFiles);
+const passed = runRules(pagesToLint);
+if (passed)
+    markPassing(changedFiles);
+process.exit(passed ? 0 : 1);

package/dist/page-model/build-page-model.js

@@ -0,0 +1,11 @@
+import { connectCssToComponents } from "./connect-css.js";
+import { readCss } from "./read-css.js";
+import { readStructure } from "./read-structure.js";
+import { GLOBAL_COMPONENTS_FOLDER } from "../shared/site-files-tree-mapping.js";
+export function buildPageModel({ jsxFile, text, program }, readFile) {
+    const page = jsxFile.slice(0, jsxFile.lastIndexOf('/'));
+    const structure = readStructure(jsxFile, text, program);
+    const css = readCss(page, readFile);
+    connectCssToComponents(structure.components, css);
+    return { path: page, kind: page.startsWith(`${GLOBAL_COMPONENTS_FOLDER}/`) ? 'global' : 'page', jsxFile, ...structure, css };
+}

package/dist/page-model/connect-css.js

@@ -0,0 +1,43 @@
+// THE place that ties CSS to components: each component takes the CSS of each of its class names (`.x`, as the import
+// matches it since converter 0.63). Class names no component took become unconnectedCss.
+import { CSS_FILES, CSS_KINDS } from "./model.js";
+/** Two components with the same class name both take its CSS, as in a browser. */
+export function connectCssToComponents(components, css) {
+    const connected = new Set();
+    for (const component of Object.values(components)) {
+        const taken = component.classNames.filter((name) => css.byClassName[name]);
+        if (!taken.length)
+            continue;
+        component.css = joinCss(taken.map((name) => css.byClassName[name]));
+        for (const name of taken)
+            connected.add(name);
+    }
+    moveUnconnected(css, connected);
+}
+/** One component's CSS from several class names: per kind and property, the lines of all of them in the order they're written,
+ * as the cascade reads them (`.card` then `.wide` in the file: `.wide` wins, whatever the className's order). A line that two of
+ * its classes both reach (`.a, .b { … }` on className="a b") is one line, as the browser applies it once. */
+function joinCss(all) {
+    if (all.length === 1)
+        return all[0];
+    return Object.fromEntries(CSS_KINDS.map((kind) => {
+        const joined = Object.create(null);
+        for (const componentCss of all)
+            for (const [property, lines] of Object.entries(componentCss[kind]))
+                (joined[property] ??= []).push(...lines);
+        for (const [property, lines] of Object.entries(joined))
+            joined[property] = lines.sort(byPlace).filter((line, index) => index === 0 || !isSameLine(lines[index - 1], line));
+        return [kind, joined];
+    }));
+}
+const byPlace = (a, b) => CSS_FILES.indexOf(a.file) - CSS_FILES.indexOf(b.file) || a.line - b.line || a.column - b.column;
+/** The same line of the file, reached through the same selector and media. */
+const isSameLine = (a, b) => byPlace(a, b) === 0 && a.selector === b.selector && a.media === b.media;
+function moveUnconnected(css, connected) {
+    for (const [name, componentCss] of Object.entries(css.byClassName)) {
+        if (connected.has(name))
+            continue;
+        css.unconnectedCss[`.${name}`] = componentCss;
+        delete css.byClassName[name];
+    }
+}

package/dist/page-model/css-selectors.js

@@ -0,0 +1,49 @@
+// CSS selectors: joining a nested rule to its parent, and which component a selector belongs to (the one of its first `.x`).
+/** `&` is the parent selector; a child without `&` is a descendant of it. */
+export function nestSelectors(parents, children) {
+    if (!parents.length)
+        return children;
+    return parents.flatMap((parent) => children.map((child) => (child.includes('&') ? child.replaceAll('&', parent) : `${parent} ${child}`)));
+}
+/** A selector's owner is its first `.x` or `#x` outside [attribute] brackets (only the first is read): '.comp-x' → '.comp-x', '&';
+ * '.comp-x:hover' → '.comp-x', '&:hover'; '.comp-x .label' → '.comp-x', '& .label'; '#comp-x' → '#comp-x', '&'; ':root' → null, ':root'. */
+export function parseComponentSelector(selector) {
+    const normalized = selector.replace(/\s+/g, ' ').trim();
+    const owner = findOwner(normalized);
+    if (!owner)
+        return { owner: null, selector: normalized };
+    return { owner: owner.text, selector: `${normalized.slice(0, owner.start)}&${normalized.slice(owner.start + owner.text.length)}` };
+}
+/** A CSS name: letters, digits, `-`, `_`, any non-ASCII letter, and escapes (`\:`, `\31 `). */
+const NAME = /^(?:[\w-]|\P{ASCII}|\\[0-9a-fA-F]{1,6}\s?|\\[^\n0-9a-fA-F])+/u;
+/** `a\:b` → 'a:b', `\31 23` → '123': the class name an escaped selector names. */
+export const unescapeName = (name) => name.replace(/\\([0-9a-fA-F]{1,6})\s?|\\(.)/g, (_, hex, char) => (hex ? String.fromCodePoint(parseInt(hex, 16)) : char));
+/** The first `.name` or `#name` outside [ ] (an attribute's value can hold a dot), a quoted value (it can hold a `]`) and ( ) (`:not(.x)`,
+ * `:is(.a, .b)` name other elements or a choice, not the one the rule is on). */
+function findOwner(selector) {
+    let depth = 0;
+    let quote = null;
+    for (let index = 0; index < selector.length; index++) {
+        const char = selector[index];
+        if (quote) {
+            if (char === '\\')
+                index++;
+            else if (char === quote)
+                quote = null;
+        }
+        else if (char === '"' || char === "'")
+            quote = char;
+        else if (char === '\\')
+            index++;
+        else if (char === '[' || char === '(')
+            depth++;
+        else if (char === ']' || char === ')')
+            depth--;
+        else if (depth === 0 && (char === '.' || char === '#')) {
+            const name = NAME.exec(selector.slice(index + 1))?.[0];
+            if (name)
+                return { text: `${char}${name}`, start: index };
+        }
+    }
+    return null;
+}

package/dist/page-model/index.js

@@ -0,0 +1,5 @@
+// Part 2 — page model: which pages to lint, and one page's model (its components, each with its CSS).
+export * from "./model.js";
+export { buildPageModel } from "./build-page-model.js";
+export { findPagesToLint, JSX_FILES } from "./pages.js";
+export { readPage } from "./read-page.js";

package/dist/page-model/model.js

@@ -0,0 +1,5 @@
+/** layout.css, style.css, and what a component gets from the theme through @apply. */
+export const CSS_KINDS = ['layout', 'style', 'theme'];
+/** A page's own CSS files, in the order they're read; with the structure file, the files that make a page (pages.ts). */
+export const CSS_FILES = ['layout.css', 'style.css'];
+export const FILE_START = { start: { line: 1, column: 0 }, end: { line: 1, column: 0 } };

package/dist/page-model/pages.js

@@ -0,0 +1,27 @@
+import { log } from "../shared/log.js";
+import { CSS_FILES } from "./model.js";
+import { GLOBAL_COMPONENTS_FOLDER, PAGES_FOLDER, THEME_FILE } from "../shared/site-files-tree-mapping.js";
+export const PAGE_ROOTS = [PAGES_FOLDER, GLOBAL_COMPONENTS_FOLDER];
+/** A page's structure file: structure.tsx, or structure.jsx (exports). structure.tsx wins if both exist. */
+export const JSX_FILES = ['structure.tsx', 'structure.jsx'];
+/** Written by the site generator inside a page folder; never a page itself. */
+const GENERATED_FOLDER = '_generated';
+/** The structure files to lint: the pages of the changed files; every page on a full run. */
+export function findPagesToLint({ changed, all }) {
+    const pagesToLint = findPages(changed ?? all, all);
+    log(`${pagesToLint.length} pages to lint`);
+    return pagesToLint;
+}
+/** The structure files of the pages these files belong to (every page when the theme is one of them), among currentFiles. */
+export function findPages(files, currentFiles) {
+    const existing = new Set(currentFiles);
+    const pageFilesToCheck = files.includes(THEME_FILE) ? currentFiles : files;
+    const pages = new Set(pageFilesToCheck.map(pageOfFile).filter((page) => page !== null));
+    return [...pages].map((page) => JSX_FILES.map((name) => `${page}/${name}`).find((file) => existing.has(file))).filter((file) => file !== undefined);
+}
+/** 'packages/site-app/src/pages/about-us/team/style.css' → 'packages/site-app/src/pages/about-us/team'; other files → null. Pages can be nested. */
+function pageOfFile(file) {
+    const page = file.slice(0, file.lastIndexOf('/'));
+    const isInPageFolder = PAGE_ROOTS.some((root) => page.startsWith(`${root}/`)) && !page.split('/').includes(GENERATED_FOLDER);
+    return isInPageFolder && [...JSX_FILES, ...CSS_FILES].map((name) => `${page}/${name}`).includes(file) ? page : null;
+}

package/dist/page-model/read-css.js

@@ -0,0 +1,84 @@
+// A page's layout.css + style.css, and theme.css → PageCss: every line under its selector's class name and its kind, or in globalCss;
+// each file as parsed.
+// Nested rules are joined to their parent, and `@apply --mixin` is replaced by the theme's mixin, as kind 'theme'.
+import postcss, {} from 'postcss';
+import { CSS_FILES } from "./model.js";
+import { nestSelectors, parseComponentSelector, unescapeName } from "./css-selectors.js";
+import { THEME_FILE } from "../shared/site-files-tree-mapping.js";
+import { mixinName, readMixins } from "./read-theme.js";
+import { emptyComponentCss } from "./utils.js";
+const KIND_OF_FILE = { 'layout.css': 'layout', 'style.css': 'style' };
+/** A property's name as the browser reads it: `Position` is `position`; a custom property (`--Gap`) keeps its case, which counts. */
+const propertyName = (prop) => (prop.startsWith('--') ? prop : prop.toLowerCase());
+const placeOf = (node) => ({ line: node.source?.start?.line ?? 1, column: node.source?.start?.column ?? 1 });
+/** theme.css is read and parsed once: its tree feeds the mixins `@apply` puts in, and rulesApi reads its tokens and breakpoints. */
+export function readCss(page, readFile) {
+    const themeCss = readFile(THEME_FILE);
+    const theme = themeCss === undefined ? undefined : postcss.parse(themeCss);
+    const css = {
+        // No prototype: a class named `constructor` or `__proto__` is a key like any other, not Object's.
+        byClassName: Object.create(null),
+        unconnectedCss: Object.create(null),
+        globalCss: emptyComponentCss(),
+        files: { layout: undefined, style: undefined, theme },
+    };
+    const mixins = readMixins(theme);
+    const addLine = lineAdderTo(css);
+    for (const file of CSS_FILES) {
+        const text = readFile(`${page}/${file}`);
+        if (text === undefined)
+            continue;
+        const root = postcss.parse(text);
+        const kind = KIND_OF_FILE[file];
+        css.files[kind] = root;
+        readNodes(root.nodes, { selectors: [], media: null, target: null, kind, file, applying: [], appliedAt: null }, mixins, addLine);
+    }
+    return css;
+}
+/** A line goes under its selector's first class name, or in globalCss when the selector has no `.x` or `#x`. A `#x` owner is
+ * unconnected from the start: the import doesn't read #id since converter 0.63. */
+function lineAdderTo(css) {
+    return (selector, property, value, { media, target, kind, file }, { line, column }) => {
+        const { owner, selector: componentSelector } = parseComponentSelector(selector);
+        const componentCss = !owner ? css.globalCss
+            : owner.startsWith('.') ? (css.byClassName[unescapeName(owner.slice(1))] ??= emptyComponentCss())
+                : (css.unconnectedCss[owner] ??= emptyComponentCss());
+        (componentCss[kind][property] ??= []).push({ value, media, selector: target ? `${componentSelector} @origami-target ${target}` : componentSelector, file, line, column });
+    };
+}
+function readNodes(nodes, context, mixins, addLine) {
+    for (const node of nodes) {
+        if (node.type === 'decl' && context.selectors.length) {
+            for (const selector of context.selectors)
+                addLine(selector, propertyName(node.prop), node.value.trim(), context, context.appliedAt ?? placeOf(node));
+        }
+        else if (node.type === 'rule') {
+            readNodes(node.nodes, { ...context, selectors: nestSelectors(context.selectors, node.selectors) }, mixins, addLine);
+        }
+        else if (node.type === 'atrule') {
+            readAtRule(node, context, mixins, addLine);
+        }
+    }
+}
+function readAtRule(node, context, mixins, addLine) {
+    const params = node.params.trim();
+    if (node.name === 'mixin')
+        return;
+    if (node.name === 'apply')
+        return applyMixin(mixinName(params), { ...context, appliedAt: context.appliedAt ?? placeOf(node) }, mixins, addLine);
+    if (!node.nodes)
+        return;
+    if (node.name === 'media')
+        readNodes(node.nodes, { ...context, media: context.media ? `${context.media} and ${params}` : params }, mixins, addLine);
+    else if (node.name === 'origami-target')
+        readNodes(node.nodes, { ...context, target: params }, mixins, addLine);
+    else
+        readNodes(node.nodes, context, mixins, addLine);
+}
+/** A missing mixin, or one that applies itself, adds nothing. */
+function applyMixin(name, context, mixins, addLine) {
+    const body = mixins.get(name);
+    if (!body || context.applying.includes(name))
+        return;
+    readNodes(body, { ...context, kind: 'theme', applying: [...context.applying, name] }, mixins, addLine);
+}

package/dist/page-model/read-page.js

@@ -0,0 +1,17 @@
+// A page from disk: the structure file the lint tool is linting, and its CSS and the theme read from the site's folder.
+// A page reads only its own files and the theme, so linting only the pages whose files changed misses nothing.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { buildPageModel } from "./build-page-model.js";
+/** root: the site's folder. Nothing is cached here: the rules API keeps one page per file. */
+export function readPage(root, structure) {
+    return buildPageModel(structure, (file) => readIfExists(path.join(root, file)));
+}
+function readIfExists(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/page-model/read-structure.js

@@ -0,0 +1,58 @@
+// structure.jsx (or .tsx) → components. Every JSX element inside Structure is a component.
+// Only what the lint tool can't give a rule: each component's key and parentKey, to connect its CSS. The rest is in the tool's syntax tree.
+import { parseSync } from 'oxc-parser';
+import { findDeclaration, isIdAttribute, getLiteralClassNames, getLiteralId, getNestingContext, createSourceReader, walk, emptyComponentCss } from "./utils.js";
+/** program: the same text's oxc syntax tree, when the lint tool already has it (oxlint's is the same shape); otherwise parsed here. */
+export function readStructure(jsxFile, text, program = parseSync(jsxFile, text).program) {
+    const source = createSourceReader(text);
+    const elements = findElements(program);
+    return { components: toComponents(elements, assignKeys(elements, source), source) };
+}
+/** Every JSX element inside the `Structure` declaration, outermost first. */
+function findElements(program) {
+    const structure = findDeclaration(program, 'Structure');
+    if (!structure)
+        return [];
+    const elements = [];
+    const siblingCounts = new Map();
+    walk(structure, [], (node, ancestors) => {
+        if (node.type !== 'JSXElement')
+            return;
+        const { parent, slot } = getNestingContext(ancestors);
+        const siblings = `${parent?.start}|${slot}`;
+        const index = siblingCounts.get(siblings) ?? 0;
+        siblingCounts.set(siblings, index + 1);
+        elements.push({ node: node, parent, slot, index });
+    });
+    return elements;
+}
+/** Its literal id when no other element uses it, else its path: 'comp-x/div[1]', 'comp-x/backgroundLayer:Background[0]'. */
+function assignKeys(elements, source) {
+    const ids = elements.map(({ node }) => getLiteralId(node)).filter((id) => id !== null);
+    const isUnique = (id) => ids.indexOf(id) === ids.lastIndexOf(id);
+    const keys = new Map();
+    for (const { node, parent, slot, index } of elements) {
+        const id = getLiteralId(node);
+        const parentKey = parent ? keys.get(parent) : null;
+        const path = `${parentKey ? `${parentKey}/` : ''}${slot ? `${slot}:` : ''}${source.code(node.openingElement.name)}[${index}]`;
+        keys.set(node, id && isUnique(id) ? id : path);
+    }
+    return keys;
+}
+/** slot, tag and index make the path keys; they aren't kept (a rule reads an element's slot with rulesApi.getSlot). */
+function toComponents(elements, keys, source) {
+    const components = {};
+    for (const { node, parent } of elements) {
+        const key = keys.get(node);
+        components[key] = {
+            key,
+            sourceStart: node.start,
+            id: getLiteralId(node),
+            classNames: getLiteralClassNames(node),
+            parentKey: parent ? keys.get(parent) : null,
+            css: emptyComponentCss(),
+            loc: source.loc(node.openingElement.attributes.find(isIdAttribute) ?? node.openingElement.name),
+        };
+    }
+    return components;
+}

package/dist/page-model/read-theme.js

@@ -0,0 +1,14 @@
+/** `@mixin --name { @result { … } }` (or without @result) → name → its body. No theme → no mixins. */
+export function readMixins(theme) {
+    const mixins = new Map();
+    if (theme === undefined)
+        return mixins;
+    theme.walkAtRules('mixin', (mixin) => {
+        const first = mixin.first;
+        const body = first?.type === 'atrule' && first.name === 'result' ? first : mixin;
+        mixins.set(mixinName(mixin.params), body.nodes ?? []);
+    });
+    return mixins;
+}
+/** '--button-primary' and '--button-primary()' are the same mixin. */
+export const mixinName = (params) => params.trim().replace(/\(\)$/, '');

package/dist/page-model/utils.js

@@ -0,0 +1,78 @@
+import { CSS_KINDS } from "./model.js";
+// ── syntax tree ──
+/** Calls visit(node, ancestors) for every node. Skips `parent`, which oxlint's syntax tree has (oxc-parser's doesn't). */
+export function walk(node, ancestors, visit) {
+    visit(node, ancestors);
+    ancestors.push(node);
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'parent')
+            continue;
+        for (const child of Array.isArray(value) ? value : [value])
+            if (typeof child?.type === 'string')
+                walk(child, ancestors, visit);
+    }
+    ancestors.pop();
+}
+/** Top-level statements, with `export` unwrapped. */
+function topLevelDeclarations(program) {
+    return program.body.map((statement) => (statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement));
+}
+export function findDeclaration(program, name) {
+    for (const node of topLevelDeclarations(program)) {
+        if (node?.type === 'FunctionDeclaration' && node.id?.name === name)
+            return node;
+        if (node?.type === 'VariableDeclaration') {
+            const declarator = node.declarations.find((d) => d.id.type === 'Identifier' && d.id.name === name);
+            if (declarator)
+                return declarator;
+        }
+    }
+    return null;
+}
+// ── JSX ──
+/** The nearest enclosing element, and the prop we came through if the element is passed in one. */
+export function getNestingContext(ancestors) {
+    let slot = null;
+    for (const node of [...ancestors].reverse()) {
+        if (node.type === 'JSXAttribute' && slot === null)
+            slot = attributeName(node);
+        if (node.type === 'JSXElement')
+            return { parent: node, slot };
+    }
+    return { parent: null, slot: null };
+}
+export function attributeName(attr) {
+    if (attr.type !== 'JSXAttribute')
+        return null;
+    return attr.name.type === 'JSXIdentifier' ? attr.name.name : `${attr.name.namespace.name}:${attr.name.name.name}`;
+}
+export const isIdAttribute = (attr) => attributeName(attr) === 'id';
+/** id="comp-x" → 'comp-x'; no id, or id={variable} → null. */
+export const getLiteralId = (node) => getLiteralAttribute(node, 'id');
+/** className="comp-x card" → ['comp-x', 'card']; no className, or className={variable} → []. */
+export const getLiteralClassNames = (node) => getLiteralAttribute(node, 'className')?.split(/\s+/).filter(Boolean) ?? [];
+function getLiteralAttribute(node, name) {
+    const attr = node.openingElement.attributes.find((attribute) => attributeName(attribute) === name);
+    const value = attr?.type === 'JSXAttribute' ? attr.value : null;
+    return value?.type === 'Literal' && typeof value.value === 'string' ? value.value : null;
+}
+export function createSourceReader(text) {
+    const lineStarts = [0];
+    for (let i = 0; i < text.length; i++)
+        if (text[i] === '\n')
+            lineStarts.push(i + 1);
+    const position = (offset) => {
+        let line = 0;
+        while (line + 1 < lineStarts.length && lineStarts[line + 1] <= offset)
+            line++;
+        return { line: line + 1, column: offset - lineStarts[line] };
+    };
+    return {
+        code: (node) => text.slice(node.start, node.end).replace(/\s+/g, ' ').trim(),
+        loc: (node) => ({ start: position(node.start), end: position(node.end) }),
+    };
+}
+// ── CSS ──
+/** No CSS of any kind. */
+/** No prototype: a property written `constructor` or `__proto__` is a key like any other, not Object's. */
+export const emptyComponentCss = () => Object.fromEntries(CSS_KINDS.map((kind) => [kind, Object.create(null)]));