pasika 0.1.6 → 0.3.0

package/dist/eslint/pasika/rules/enforce-cn-merge.js

@@ -0,0 +1,84 @@
+/**
+ * ESLint rule: pasika/enforce-cn-merge
+ *
+ * Enforces the "Class Composition Rule".
+ *
+ * @see docs/styling-guide/rules/class-composition-rule.md
+ */
+function classCount(str) {
+    return str.split(/\s+/).filter(Boolean).length;
+}
+export const enforceCnMergeRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Enforce cn() for conditional class merging.",
+        },
+    },
+    create(context) {
+        return {
+            JSXAttribute(node) {
+                if (node.name.name !== "className" && node.name.name !== "class")
+                    return;
+                const valueNode = node.value;
+                if (!valueNode)
+                    return;
+                if (valueNode.type === "Literal" && typeof valueNode.value === "string") {
+                    if (classCount(valueNode.value) > 5) {
+                        context.report({
+                            node,
+                            message: "Static className with more than 5 classes must use cn() with grouped string literals. " +
+                                "See docs/styling-guide/rules/class-composition-rule.md",
+                        });
+                    }
+                    return;
+                }
+                if (valueNode.type !== "JSXExpressionContainer" || !valueNode.expression)
+                    return;
+                const expr = valueNode.expression;
+                if (expr.type === "BinaryExpression" && expr.operator === "+") {
+                    context.report({
+                        node,
+                        message: "Use cn() instead of + operator for className. " +
+                            "See docs/styling-guide/rules/class-composition-rule.md",
+                    });
+                    return;
+                }
+                if (expr.type === "TemplateLiteral" && expr.expressions.length > 0) {
+                    context.report({
+                        node,
+                        message: "Use cn() instead of template literals with conditionals for className. " +
+                            "See docs/styling-guide/rules/class-composition-rule.md",
+                    });
+                    return;
+                }
+                if (expr.type === "Literal" && typeof expr.value === "string") {
+                    if (classCount(expr.value) > 5) {
+                        context.report({
+                            node,
+                            message: "Static className with more than 5 classes must use cn() with grouped string literals. " +
+                                "See docs/styling-guide/rules/class-composition-rule.md",
+                        });
+                    }
+                    return;
+                }
+                if (expr.type === "CallExpression" && expr.callee.type === "Identifier" && expr.callee.name === "cn") {
+                    for (const arg of expr.arguments) {
+                        if (arg.type === "Literal" && typeof arg.value === "string") {
+                            if (classCount(arg.value) > 5) {
+                                context.report({
+                                    node: arg,
+                                    message: "Each cn() string argument must contain at most 5 class names. " +
+                                        "Group by styling concern. " +
+                                        "See docs/styling-guide/rules/class-composition-rule.md",
+                                });
+                            }
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+/* eslint-enable  -- re-enable rules disabled for AST access @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument */

package/dist/eslint/pasika/rules/enforce-cva-variant-props.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ESLint rule: pasika/enforce-cva-variant-props
+ *
+ * Enforces the "Component Variant Rule" — VariantProps from CVA.
+ *
+ * @see docs/styling-guide/rules/component-variant-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const enforceCvaVariantPropsRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/enforce-cva-variant-props.js

@@ -0,0 +1,81 @@
+/**
+ * ESLint rule: pasika/enforce-cva-variant-props
+ *
+ * Enforces the "Component Variant Rule" — VariantProps from CVA.
+ *
+ * @see docs/styling-guide/rules/component-variant-rule.md
+ */
+export const enforceCvaVariantPropsRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Enforce VariantProps from CVA instead of manual variant union types.",
+        },
+    },
+    create(context) {
+        const cvaDefinitions = new Map();
+        return {
+            VariableDeclarator(node) {
+                if (node.init?.type === "CallExpression" &&
+                    node.init.callee.type === "Identifier" &&
+                    node.init.callee.name === "cva" &&
+                    node.id.type === "Identifier") {
+                    const args = node.init.arguments;
+                    if (args.length < 2)
+                        return;
+                    const options = args[1];
+                    if (options?.type === "ObjectExpression") {
+                        for (const prop of options.properties) {
+                            if (prop.type === "Property" &&
+                                prop.key.type === "Identifier" &&
+                                prop.key.name === "variants" &&
+                                prop.value.type === "ObjectExpression") {
+                                const variantNames = prop.value.properties
+                                    .filter((p) => p.type === "Property" && p.key.type === "Identifier")
+                                    .map((p) => p.key.name);
+                                if (variantNames.length > 0) {
+                                    cvaDefinitions.set(node.id.name, variantNames);
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            TSTypeAliasDeclaration(node) {
+                if (!node.id.name.endsWith("Props"))
+                    return;
+                if (node.typeAnnotation.type !== "TSTypeLiteral")
+                    return;
+                for (const member of node.typeAnnotation.members) {
+                    if (member.type === "TSPropertySignature" &&
+                        member.key.type === "Identifier" &&
+                        member.typeAnnotation?.typeAnnotation?.type === "TSUnionType") {
+                        const keyName = String(member.key.name);
+                        const typeAnn = member.typeAnnotation.typeAnnotation;
+                        // typescript-eslint emits ESTree `Literal` nodes; other TypeScript
+                        // parsers emit `StringLiteral`. Accept both so the rule works
+                        // whichever parser the consuming config installs.
+                        const allStringLiterals = typeAnn.types.every((t) => t.type === "TSLiteralType" &&
+                            (t.literal?.type === "StringLiteral" ||
+                                (t.literal?.type === "Literal" && typeof t.literal.value === "string")));
+                        if (allStringLiterals && typeAnn.types.length >= 2) {
+                            for (const [, variantNames] of cvaDefinitions) {
+                                if (variantNames.includes(keyName)) {
+                                    context.report({
+                                        node: member,
+                                        message: `Variant prop "${keyName}" duplicates CVA variant values. ` +
+                                            "Use VariantProps<typeof variants> instead of manually writing union types. " +
+                                            "See docs/styling-guide/rules/component-variant-rule.md",
+                                    });
+                                    return;
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+/* eslint-enable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-explicit-any -- re-enable after AST node access block */

package/dist/eslint/pasika/rules/filename-case.js

@@ -1,3 +1,13 @@
+/**
+ * ESLint rule: pasika/filename-case
+ *
+ * Enforces the naming conventions from the "Smart vs Dumb Component Rule":
+ *  - Smart components: PascalCase.tsx
+ *  - Dumb components: kebab-case.tsx
+ *  - Non-component files: kebab-case
+ *
+ * @see docs/code-organization-guide/rules/smart-vs-dumb-component-rule.md
+ */
 import path from "node:path";
 /**
  * Next.js App Router routing files that are exempt from filename-case checks.

package/dist/eslint/pasika/rules/import-boundaries.d.ts

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

package/dist/eslint/pasika/rules/{organization-imports.js → import-boundaries.js}

@@ -1,3 +1,13 @@
+/**
+ * ESLint rule: pasika/import-boundaries
+ *
+ * Enforces the import conventions from the "Exports and Imports Rule":
+ *  - Whichever of the relative path and the @/* alias has fewer segments, with
+ *    a tie going to the relative path.
+ *  - Layer boundary enforcement (app → compositions → features → shared → root).
+ *
+ * @see docs/code-organization-guide/rules/exports-and-imports-rule.md
+ */
 import path from "node:path";
 const sourceRoot = path.resolve("src");
 const rootSupportFolders = new Set(["config", "constants", "hooks", "locales", "schemas", "types", "utils"]);
@@ -19,14 +29,35 @@ function sourceSegments(absolutePath) {
     }
     return relativePath.split(path.sep);
 }
-function isNearbyImport(filename, resolvedPath) {
-    const relativePath = path.relative(path.dirname(filename), resolvedPath);
-    const segments = relativePath.split(path.sep).filter((segment) => segment !== ".");
-    const parentTraversals = segments.filter((segment) => segment === "..").length;
-    const nonParentSegments = segments.length - parentTraversals;
-    return (parentTraversals === 0 && nonParentSegments <= 2) || (parentTraversals === 1 && nonParentSegments <= 1);
+/** The relative form of an import, always prefixed so it reads as a path. */
+function relativeSpecifier(filename, resolvedPath) {
+    const relativePath = path.relative(path.dirname(filename), resolvedPath).split(path.sep).join("/");
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
 }
-export const organizationImportsRule = {
+/** The `@/*` form of an import. */
+function aliasSpecifier(resolvedPath) {
+    return `@/${(sourceSegments(resolvedPath) ?? []).join("/")}`;
+}
+/** Segments in a specifier: one per `../` step and one per name, ignoring a leading `./`. */
+function segmentCount(specifier) {
+    return specifier
+        .replace(/^@\//, "")
+        .split("/")
+        .filter((segment) => segment !== "." && segment !== "").length;
+}
+function describeSegments(count) {
+    return `${String(count)} segment${count === 1 ? "" : "s"}`;
+}
+/**
+ * Whether the relative form is the one to use. Shorter wins, and a tie goes to
+ * the relative form. Because crossing a layer always costs at least one `../`
+ * while the alias spells the same tail, the alias always wins for a
+ * cross-layer import without this needing to know what a layer is.
+ */
+function prefersRelative(filename, resolvedPath) {
+    return segmentCount(relativeSpecifier(filename, resolvedPath)) <= segmentCount(aliasSpecifier(resolvedPath));
+}
+export const importBoundariesRule = {
     meta: {
         schema: [],
         type: "problem",
@@ -50,18 +81,6 @@ export const organizationImportsRule = {
             if (!importer || !imported || importer.length === 0 || imported.length === 0) {
                 return;
             }
-            if (isNearbyImport(filename, resolvedPath) && importPath.startsWith("@/")) {
-                context.report({
-                    node: source,
-                    message: "Use a relative path for imports in the same folder, a descendant, or one folder up.",
-                });
-            }
-            if (!isNearbyImport(filename, resolvedPath) && importPath.startsWith(".")) {
-                context.report({
-                    node: source,
-                    message: "Use the @/* alias for imports beyond one folder up.",
-                });
-            }
             const [importerLayer = "", importerFeature] = importer;
             const [importedLayer = "", importedFeature] = imported;
             const extension = path.extname(importPath);
@@ -97,6 +116,30 @@ export const organizationImportsRule = {
                     node: source,
                     message: "This import violates the src layer boundary.",
                 });
+                // The fix is to move the file, so how the specifier is spelled does not matter yet.
+                return;
+            }
+            const relativeForm = relativeSpecifier(filename, resolvedPath);
+            const aliasForm = aliasSpecifier(resolvedPath);
+            const relativeSegments = segmentCount(relativeForm);
+            const aliasSegments = segmentCount(aliasForm);
+            function describeChoice(preferred, preferredSegments, other, otherSegments) {
+                const tie = preferredSegments === otherSegments ? ", and a tie goes to the relative path" : "";
+                return (`Use "${preferred}" (${describeSegments(preferredSegments)}) ` +
+                    `instead of "${other}" (${describeSegments(otherSegments)})${tie}.`);
+            }
+            if (prefersRelative(filename, resolvedPath) && importPath.startsWith("@/")) {
+                context.report({
+                    node: source,
+                    message: describeChoice(relativeForm, relativeSegments, aliasForm, aliasSegments),
+                });
+                return;
+            }
+            if (!prefersRelative(filename, resolvedPath) && importPath.startsWith(".")) {
+                context.report({
+                    node: source,
+                    message: describeChoice(aliasForm, aliasSegments, relativeForm, relativeSegments),
+                });
             }
         }
         return {

package/dist/eslint/pasika/rules/no-arbitrary-tailwind.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ESLint rule: pasika/no-arbitrary-tailwind
+ *
+ * Enforces the "Arbitrary Value Rule" — no arbitrary-value Tailwind classes.
+ *
+ * @see docs/styling-guide/rules/arbitrary-value-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const noArbitraryTailwindRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/no-arbitrary-tailwind.js

@@ -0,0 +1,97 @@
+/**
+ * ESLint rule: pasika/no-arbitrary-tailwind
+ *
+ * Enforces the "Arbitrary Value Rule" — no arbitrary-value Tailwind classes.
+ *
+ * @see docs/styling-guide/rules/arbitrary-value-rule.md
+ */
+/**
+ * Matches Tailwind arbitrary-value utility classes like rounded-[13px], text-[#fff].
+ *
+ * Does NOT match variant prefixes like min-[400px]:flex-row or md:flex.
+ * The negative lookahead (?![-\w]*:) excludes anything followed by a colon + more.
+ *
+ * Note: Tailwind breakpoint variants (sm:, md:, lg:, etc.) don't use brackets,
+ * so they're never matched. Only bracket-based variants like min-[400px]: need
+ * the lookahead exclusion.
+ */
+const ARBITRARY_VALUE_RE = /(?:^|(?<=\s))(?:[a-z]+(?:-[a-z]+)*)-\[[^\]]+\](?![-\w]*:)/g;
+const CLASS_HELPERS = new Set(["cn", "clsx", "twMerge", "twJoin"]);
+export const noArbitraryTailwindRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Disallow Tailwind arbitrary-value classes like rounded-[13px].",
+        },
+    },
+    create(context) {
+        function reportClassString(node, value) {
+            ARBITRARY_VALUE_RE.lastIndex = 0;
+            const match = ARBITRARY_VALUE_RE.exec(value);
+            if (!match)
+                return;
+            context.report({
+                node,
+                message: `Tailwind arbitrary-value class "${match[0]}" is not allowed. ` +
+                    "Use a named token or custom utility. " +
+                    "See docs/styling-guide/rules/arbitrary-value-rule.md",
+            });
+        }
+        /** Walks every expression a class name can hide in: conditionals, arrays, and object keys. */
+        function checkExpression(node, expression) {
+            if (!expression)
+                return;
+            if (expression.type === "Literal") {
+                if (typeof expression.value === "string")
+                    reportClassString(node, expression.value);
+                return;
+            }
+            if (expression.type === "TemplateLiteral") {
+                for (const quasi of expression.quasis)
+                    reportClassString(node, quasi.value.raw);
+                return;
+            }
+            if (expression.type === "LogicalExpression") {
+                checkExpression(node, expression.left);
+                checkExpression(node, expression.right);
+                return;
+            }
+            if (expression.type === "ConditionalExpression") {
+                checkExpression(node, expression.consequent);
+                checkExpression(node, expression.alternate);
+                return;
+            }
+            if (expression.type === "ArrayExpression") {
+                for (const element of expression.elements)
+                    checkExpression(node, element);
+                return;
+            }
+            if (expression.type === "ObjectExpression") {
+                // clsx and cn accept `{ "px-[3px]": isActive }`, so the keys carry classes.
+                for (const property of expression.properties) {
+                    if (property.type === "Property")
+                        checkExpression(node, property.key);
+                }
+            }
+        }
+        return {
+            JSXAttribute(node) {
+                const attributeName = node.name?.name;
+                if (attributeName !== "className" && attributeName !== "class")
+                    return;
+                const value = node.value;
+                if (!value)
+                    return;
+                checkExpression(node, value.type === "JSXExpressionContainer" ? value.expression : value);
+            },
+            CallExpression(node) {
+                if (node.callee.type !== "Identifier" || !CLASS_HELPERS.has(node.callee.name))
+                    return;
+                for (const argument of node.arguments) {
+                    checkExpression(node, argument);
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/no-mixed-concerns.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ESLint rule: pasika/no-mixed-concerns
+ *
+ * Enforces the "No Mixed Concerns Rule" — one React component per .tsx file.
+ *
+ * @see docs/code-organization-guide/rules/no-mixed-concerns-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const noMixedConcernsRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/no-mixed-concerns.js

@@ -0,0 +1,84 @@
+/**
+ * ESLint rule: pasika/no-mixed-concerns
+ *
+ * Enforces the "No Mixed Concerns Rule" — one React component per .tsx file.
+ *
+ * @see docs/code-organization-guide/rules/no-mixed-concerns-rule.md
+ */
+/**
+ * Return the name of an export node so we can report it clearly.
+ * Handles:
+ *   export function Foo() { }
+ *   export const Foo = () => { }
+ *   export const Foo = function () { }
+ *   export default function Foo() { }
+ *   export default () => { }
+ */
+// biome-ignore lint/suspicious/noExplicitAny: AST node type from ESLint with dynamic property access
+function getExportName(declaration) {
+    if (declaration.type === "FunctionDeclaration" && declaration.id) {
+        return declaration.id.name;
+    }
+    if (declaration.type === "VariableDeclaration") {
+        const declarator = declaration.declarations[0];
+        if (declarator?.id.type === "Identifier" &&
+            (declarator.init?.type === "ArrowFunctionExpression" || declarator.init?.type === "FunctionExpression")) {
+            return declarator.id.name;
+        }
+    }
+    if (declaration.type === "ArrowFunctionExpression") {
+        return "default";
+    }
+    if (declaration.type === "FunctionExpression" && declaration.id) {
+        return declaration.id.name;
+    }
+    return null;
+}
+export const noMixedConcernsRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Enforce one exported React component per .tsx file.",
+        },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".tsx"))
+            return {};
+        let exportedComponentCount = 0;
+        const extraExports = [];
+        function registerExport(name) {
+            exportedComponentCount++;
+            if (exportedComponentCount > 1) {
+                extraExports.push({ name });
+            }
+        }
+        return {
+            ExportNamedDeclaration(node) {
+                if (!node.declaration)
+                    return;
+                const name = getExportName(node.declaration);
+                if (name)
+                    registerExport(name);
+            },
+            ExportDefaultDeclaration(node) {
+                const name = getExportName(node.declaration);
+                if (name)
+                    registerExport(name);
+            },
+            "Program:exit"() {
+                if (exportedComponentCount > 1) {
+                    for (const extra of extraExports) {
+                        context.report({
+                            loc: { line: 1, column: 0 },
+                            message: `File exports multiple components. "${extra.name}" is an extra component export. ` +
+                                "Move it to its own file. Each .tsx file MUST contain exactly one component. " +
+                                "See docs/code-organization-guide/rules/no-mixed-concerns-rule.md",
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+/* eslint-enable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-explicit-any -- re-enable after AST node access block */

package/dist/eslint/pasika/rules/support-file-placement.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ESLint rule: pasika/support-file-placement
+ *
+ * Enforces where a hook, type, schema, constant, or utility lives, which depends
+ * on the files that import it and so cannot be decided from one file.
+ *
+ * @see docs/code-organization-guide/rules/types-and-schemas-rule.md
+ * @see docs/code-organization-guide/rules/constants-rule.md
+ * @see docs/code-organization-guide/rules/utilities-rule.md
+ * @see docs/code-organization-guide/rules/hook-extraction-rule.md
+ * @see docs/code-organization-guide/rules/configuration-rule.md
+ * @see docs/code-organization-guide/rules/folder-nesting-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const supportFilePlacementRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/support-file-placement.js

@@ -0,0 +1,70 @@
+/**
+ * ESLint rule: pasika/support-file-placement
+ *
+ * Enforces where a hook, type, schema, constant, or utility lives, which depends
+ * on the files that import it and so cannot be decided from one file.
+ *
+ * @see docs/code-organization-guide/rules/types-and-schemas-rule.md
+ * @see docs/code-organization-guide/rules/constants-rule.md
+ * @see docs/code-organization-guide/rules/utilities-rule.md
+ * @see docs/code-organization-guide/rules/hook-extraction-rule.md
+ * @see docs/code-organization-guide/rules/configuration-rule.md
+ * @see docs/code-organization-guide/rules/folder-nesting-rule.md
+ */
+import path from "node:path";
+import { getProjectIndex } from "../project/index.js";
+import { describeConsumers, folderSegmentsOf, formatFolder, isConfigModule, resolveSupportPlacement, segmentsOf, SUPPORT_FOLDERS, } from "../project/ccf.js";
+/**
+ * Support folders a configuration module keeps regardless of who imports them: a
+ * constant or type whose meaning is derived from the configuration stays beside
+ * it even when consumers exist outside the module.
+ */
+const CONFIG_OWNED_FOLDERS = new Set(["types", "constants"]);
+const REASON_TEXT = {
+    "app-consumer": "a file under src/app/ imports it, so it belongs to the app-wide support folder",
+    "config-module": "every file that imports it belongs to that configuration module",
+    ccf: "that is the closest folder its consumers share",
+    "across-features": "its consumers span more than one feature, so no feature can own it",
+    "across-layers": "its consumers span more than one layer, so no layer can own it",
+};
+const sameFolder = (left, right) => left.length === right.length && left.every((segment, depth) => segment === right[depth]);
+export const supportFilePlacementRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Enforce that a support file lives in the folder its consumers imply.",
+        },
+    },
+    create(context) {
+        const sourceRoot = path.resolve("src");
+        const supportFile = path.resolve(context.filename);
+        const currentFolder = folderSegmentsOf(supportFile, sourceRoot);
+        const supportFolder = currentFolder[currentFolder.length - 1];
+        // Only a file already inside a support folder is placed by this rule; a
+        // declaration still sitting beside its consumer is an extraction question.
+        if (supportFolder === undefined || !SUPPORT_FOLDERS.has(supportFolder))
+            return {};
+        // A type or constant whose meaning comes from a configuration may stay with
+        // it however widely it is used, so its consumers cannot place it.
+        if (isConfigModule(segmentsOf(supportFile, sourceRoot)) && CONFIG_OWNED_FOLDERS.has(supportFolder))
+            return {};
+        const index = getProjectIndex(sourceRoot);
+        if (!index)
+            return {};
+        const placement = resolveSupportPlacement(supportFile, supportFolder, index);
+        if (!placement || sameFolder(currentFolder, placement.expectedFolder))
+            return {};
+        return {
+            Program(node) {
+                context.report({
+                    node,
+                    loc: { line: 1, column: 0 },
+                    message: `Move this file to ${formatFolder(placement.expectedFolder)} — ` +
+                        `${REASON_TEXT[placement.reason] ?? "that is where its consumers place it"}. ` +
+                        `Imported by ${describeConsumers(placement.countedConsumers, sourceRoot)}.`,
+                });
+            },
+        };
+    },
+};