@plumeria/eslint-plugin 19.5.1 → 19.6.0

package/README.md

@@ -17,6 +17,7 @@ The `plugin:@plumeria/recommended` config enables the following:
 - `@plumeria/no-order-dependent-overlap`: **warn**
 - `@plumeria/no-unknown-css-properties`: **error**
 - `@plumeria/no-unused-keys`: **warn**
+- `@plumeria/no-unresolved-composition`: **warn**
 - `@plumeria/sort-properties`: **warn**
 - `@plumeria/format-properties`: **warn**
 - `@plumeria/validate-values`: **warn**
@@ -157,6 +158,49 @@ Validates CSS pseudo-classes and pseudo-elements inside `css.create()`. It check
 
 Validates at-rules inside `css.create()`. It accepts `@media`, `@container`, `@supports`, `@layer`, and `@scope`, each with a prelude, whether or not a space separates it from the keyword, and supports validation of computed keys when TypeScript is available.
 
+### no-unresolved-composition
+
+Warns when a `css.use()` result is combined with other class names using `+`,
+a template literal, or an inline array's `.join()`, or passed to a function such
+as `clsx` or `css.use()` itself. Enabled by `recommended` as `warn`:
+
+```js
+'@plumeria/no-unresolved-composition': 'warn'
+```
+
+```js
+// Warns: merge separate css.use() calls.
+`${css.use(styles.base)} ${css.use(styles.active)}`
+css.use(styles.base) + ' ' + (active ? css.use(styles.active) : '')
+
+// Warns: pass styles, not css.use() results, to one call.
+clsx(css.use(styles.base), className)
+css.use(css.use(styles.base), styles.active)
+
+// Warns: rewrite external classes with css.create().
+css.use(styles.base) + ' external'
+[css.use(styles.base), 'external'].join(' ')
+
+// Compose everything in one call; nested arrays are allowed.
+css.use(styles.base, [active && styles.active, styles.external])
+```
+
+When a `css.use()` result is a function argument, directly, inside an array or
+spread, or in a conditional branch, the rule reports that the styles should be
+passed to one `css.use()` call instead; this is reported before the other two.
+When two or more `css.use()` results are combined, the rule reports that they
+should be merged into one call; this is reported first, even if external classes
+are also present. When a `css.use()` result is combined with external class
+names, it lists them as written in the source and reports that their precedence is left to the CSS cascade and that they
+should be rewritten as styles with `css.create()` and passed into the same
+`css.use()` call. It offers no automatic fix. Whitespace-only
+additions are allowed. Imports and their aliases are resolved with scope, so
+unrelated or shadowed `use` functions are ignored. Detection covers calls within
+these expressions, including conditional branches, and follows results through
+local variables, `+=` assignments, arrays joined through a variable, and object
+properties. It does not follow values returned from functions or imported from
+other modules.
+
 ## Optional rules
 
 These rules are not enabled by `plumeria.configs.recommended`. Enable only the

package/dist/index.js

@@ -11,6 +11,7 @@ const no_mixed_styling_props_1 = require("./rules/no-mixed-styling-props");
 const no_physical_properties_1 = require("./rules/no-physical-properties");
 const no_order_dependent_overlap_1 = require("./rules/no-order-dependent-overlap");
 const no_unknown_css_properties_1 = require("./rules/no-unknown-css-properties");
+const no_unresolved_composition_1 = require("./rules/no-unresolved-composition");
 const no_unused_keys_1 = require("./rules/no-unused-keys");
 const sort_properties_1 = require("./rules/sort-properties");
 const format_properties_1 = require("./rules/format-properties");
@@ -31,6 +32,7 @@ const rules = {
     'no-order-dependent-overlap': no_order_dependent_overlap_1.noOrderDependentOverlap,
     'no-unknown-css-properties': no_unknown_css_properties_1.noUnknownCssProperties,
     'no-unused-keys': no_unused_keys_1.noUnusedKeys,
+    'no-unresolved-composition': no_unresolved_composition_1.noUnresolvedComposition,
     'sort-properties': sort_properties_1.sortProperties,
     'format-properties': format_properties_1.formatProperties,
     'validate-values': validate_values_1.validateValues,
@@ -55,6 +57,7 @@ const configs = {
             '@plumeria/no-order-dependent-overlap': 'warn',
             '@plumeria/no-unknown-css-properties': 'error',
             '@plumeria/no-unused-keys': 'warn',
+            '@plumeria/no-unresolved-composition': 'warn',
             '@plumeria/sort-properties': 'warn',
             '@plumeria/format-properties': 'warn',
             '@plumeria/validate-values': 'warn',

package/dist/rules/no-unresolved-composition.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from 'eslint';
+export declare const noUnresolvedComposition: Rule.RuleModule;

package/dist/rules/no-unresolved-composition.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noUnresolvedComposition = void 0;
+const memberName = (node) => !node.computed && node.property.type === 'Identifier'
+    ? node.property.name
+    : node.computed && node.property.type === 'Literal'
+        ? node.property.value
+        : null;
+exports.noUnresolvedComposition = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Warn when class names are composed outside css.use()',
+        },
+        schema: [],
+        messages: {
+            merge: 'Separate css.use() results cannot resolve conflicts with each other. Merge them into one css.use(a, b) call, passing conditional styles as css.use(a, active && b).',
+            wrapped: 'css.use() results cannot be passed to functions, including css.use() itself. Pass the styles directly to one css.use() call, e.g. css.use(a, active && b, [c, d]).',
+            external: 'css.use() cannot order external class names ({{values}}); their precedence is left to the CSS cascade. Rewrite them as styles with css.create() and pass them into the same css.use() call.',
+        },
+    },
+    create(context) {
+        const reported = new Set();
+        function variableOf(node) {
+            let scope = context.sourceCode.getScope(node);
+            while (scope) {
+                const variable = scope.set.get(node.name);
+                if (variable)
+                    return variable;
+                if (!scope.upper)
+                    break;
+                scope = scope.upper;
+            }
+            return null;
+        }
+        function imported(node, name) {
+            if (node.type !== 'Identifier')
+                return false;
+            {
+                const variable = variableOf(node);
+                if (variable) {
+                    return variable.defs.some((def) => {
+                        if (def.type !== 'ImportBinding' ||
+                            def.parent.source.value !== '@plumeria/core')
+                            return false;
+                        const specifier = def.node;
+                        return name === '*'
+                            ? specifier.type === 'ImportNamespaceSpecifier' ||
+                                specifier.type === 'ImportDefaultSpecifier'
+                            : specifier.type === 'ImportSpecifier' &&
+                                (specifier.imported.type === 'Identifier'
+                                    ? specifier.imported.name
+                                    : specifier.imported.value) === name;
+                    });
+                }
+            }
+            return false;
+        }
+        function resolve(node, seen) {
+            if (seen.has(node))
+                return [];
+            seen.add(node);
+            if (node.type === 'Identifier') {
+                const variable = variableOf(node);
+                if (!variable || variable.defs.some((def) => def.type !== 'Variable'))
+                    return [];
+                const start = node.range?.[0] ?? 0;
+                return variable.references.flatMap((reference) => reference.writeExpr && (reference.writeExpr.range?.[1] ?? 0) <= start
+                    ? [reference.writeExpr, ...resolve(reference.writeExpr, seen)]
+                    : []);
+            }
+            if (node.type === 'MemberExpression' && !isUse(node)) {
+                const name = memberName(node);
+                if (name === null)
+                    return [];
+                return resolve(node.object, seen).flatMap((object) => {
+                    if (object.type !== 'ObjectExpression')
+                        return [];
+                    return object.properties.flatMap((property) => property.type === 'Property' &&
+                        !property.computed &&
+                        (property.key.type === 'Identifier'
+                            ? property.key.name
+                            : property.key.type === 'Literal'
+                                ? property.key.value
+                                : null) === name
+                        ? [property.value, ...resolve(property.value, seen)]
+                        : []);
+                });
+            }
+            return [];
+        }
+        function stored(node, seen) {
+            return resolve(node, new Set(seen)).some((value) => value !== node && uses(value, new Set([...seen, node])).length > 0);
+        }
+        function isUse(node) {
+            if (node.type !== 'CallExpression')
+                return false;
+            const callee = node.callee;
+            return callee.type === 'MemberExpression'
+                ? memberName(callee) === 'use' && imported(callee.object, '*')
+                : callee.type === 'Identifier' && imported(callee, 'use');
+        }
+        function parts(node) {
+            if (node.type === 'BinaryExpression' && node.operator === '+') {
+                return [node.left, node.right];
+            }
+            if (node.type === 'TemplateLiteral') {
+                return [...node.expressions, ...node.quasis];
+            }
+            if (node.type === 'AssignmentExpression' && node.operator === '+=') {
+                return [node.left, node.right];
+            }
+            if (node.type === 'CallExpression' &&
+                node.callee.type === 'MemberExpression' &&
+                memberName(node.callee) === 'join') {
+                const object = node.callee.object;
+                const arrays = [object, ...resolve(object, new Set())].filter((value) => value.type === 'ArrayExpression');
+                if (arrays.length === 0)
+                    return null;
+                return arrays.flatMap((array) => array.elements.filter((item) => item !== null));
+            }
+            return null;
+        }
+        function meaningful(node) {
+            if (node.type === 'Literal' && typeof node.value === 'string') {
+                return node.value.trim().length > 0;
+            }
+            if (node.type === 'TemplateElement') {
+                return (node.value.cooked ?? node.value.raw).trim().length > 0;
+            }
+            return true;
+        }
+        function uses(node, seen = new Set()) {
+            if (isUse(node))
+                return [node];
+            if ((node.type === 'Identifier' || node.type === 'MemberExpression') &&
+                stored(node, seen))
+                return [node];
+            const children = parts(node);
+            if (children)
+                return children.flatMap((child) => uses(child, seen));
+            if (node.type === 'ConditionalExpression') {
+                return [...uses(node.consequent, seen), ...uses(node.alternate, seen)];
+            }
+            if (node.type === 'LogicalExpression') {
+                return [...uses(node.left, seen), ...uses(node.right, seen)];
+            }
+            return [];
+        }
+        function passed(node) {
+            if (node.type === 'SpreadElement')
+                return passed(node.argument);
+            const arrays = [node, ...resolve(node, new Set())].filter((value) => value.type === 'ArrayExpression');
+            if (arrays.length > 0) {
+                return arrays.flatMap((array) => array.elements.flatMap((element) => element && passed(element).length > 0 ? [node] : []));
+            }
+            return uses(node);
+        }
+        function check(node) {
+            if (node.type === 'CallExpression') {
+                const calls = node.arguments.flatMap(passed);
+                if (calls.some((call) => !reported.has(call))) {
+                    calls.forEach((call) => reported.add(call));
+                    context.report({ node, messageId: 'wrapped' });
+                    return;
+                }
+            }
+            const children = parts(node);
+            if (!children)
+                return;
+            const flatten = (child) => parts(child)?.flatMap(flatten) ?? [child];
+            const values = children.flatMap(flatten).filter(meaningful);
+            const calls = values.flatMap((value) => uses(value));
+            if (values.length < 2 || !calls.some((call) => !reported.has(call)))
+                return;
+            calls.forEach((call) => reported.add(call));
+            if (values.filter((value) => uses(value).length > 0).length > 1) {
+                context.report({ node, messageId: 'merge' });
+                return;
+            }
+            const label = (value) => {
+                const text = value.type === 'TemplateElement'
+                    ? JSON.stringify((value.value.cooked ?? value.value.raw).trim())
+                    : context.sourceCode.getText(value);
+                return text.length > 40 ? `${text.slice(0, 39)}…` : text;
+            };
+            context.report({
+                node,
+                messageId: 'external',
+                data: {
+                    values: values
+                        .filter((value) => uses(value).length === 0)
+                        .map(label)
+                        .join(', '),
+                },
+            });
+        }
+        return {
+            BinaryExpression: check,
+            TemplateLiteral: check,
+            CallExpression: check,
+            AssignmentExpression: check,
+        };
+    },
+};

package/oxlint.json

@@ -19,6 +19,7 @@
     "@plumeria/no-order-dependent-overlap": "warn",
     "@plumeria/no-unknown-css-properties": "error",
     "@plumeria/no-unused-keys": "warn",
+    "@plumeria/no-unresolved-composition": "warn",
     "@plumeria/sort-properties": "warn",
     "@plumeria/format-properties": "warn",
     "@plumeria/validate-values": "warn",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumeria/eslint-plugin",
-  "version": "19.5.1",
+  "version": "19.6.0",
   "description": "Plumeria ESLint plugin",
   "author": "Refirst 11",
   "license": "MIT",
@@ -55,7 +55,7 @@
   "dependencies": {
     "known-css-properties": "^0.37.0",
     "zss-engine": "2.8.0",
-    "@plumeria/compiler": "19.5.1"
+    "@plumeria/compiler": "19.6.0"
   },
   "scripts": {
     "build": "rimraf dist && pnpm cjs",