pasika 0.3.1 → 0.3.3

package/dist/eslint/pasika/rules/pure-function-extract.js

@@ -0,0 +1,92 @@
+/**
+ * ESLint rule: pasika/pure-function-extract
+ *
+ * A pure function MUST be extracted to utils/, even when it has one consumer.
+ *
+ * @see docs/code-organization-guide/rules/utilities-rule.md
+ */
+import path from "node:path";
+function isComponentLikeName(name) {
+    return /^[A-Z]/.test(name);
+}
+function isHookName(name) {
+    return /^use[A-Z]/.test(name);
+}
+function hasHookUsage(body) {
+    for (const stmt of body.body) {
+        if (stmt.type !== "ExpressionStatement")
+            continue;
+        const expr = stmt.expression;
+        if (expr.type === "CallExpression" && expr.callee.type === "Identifier" && isHookName(expr.callee.name)) {
+            return true;
+        }
+    }
+    return false;
+}
+export const pureFunctionExtractRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require pure functions declared in component files to be extracted to utils/.",
+        },
+    },
+    create(context) {
+        const filename = context.filename;
+        if (!filename.endsWith(".tsx") && !filename.endsWith(".jsx"))
+            return {};
+        const sourceRoot = path.resolve("src");
+        const relative = path.relative(sourceRoot, filename);
+        if (relative.startsWith(".."))
+            return {};
+        const segments = relative.split(path.sep);
+        // Already in utils/ or a support folder — fine
+        if (segments[0] === "utils")
+            return {};
+        if (segments[0] === "app")
+            return {};
+        const supportFolders = new Set(["hooks", "types", "schemas", "constants", "utils"]);
+        if (segments.length >= 2 && supportFolders.has(segments[segments.length - 1] ?? ""))
+            return {};
+        function report(node, name) {
+            context.report({
+                node,
+                message: `Extract pure function "${name}" to utils/. See docs/code-organization-guide/rules/utilities-rule.md`,
+            });
+        }
+        return {
+            FunctionDeclaration(node) {
+                const exported = node.parent?.type === "ExportNamedDeclaration";
+                if (!exported)
+                    return;
+                const name = node.id?.name;
+                if (!name)
+                    return;
+                if (isComponentLikeName(name) || isHookName(name))
+                    return;
+                if (!node.body || hasHookUsage(node.body))
+                    return;
+                report(node, name);
+            },
+            VariableDeclarator(node) {
+                if (node.id.type !== "Identifier")
+                    return;
+                const name = node.id.name;
+                if (!name)
+                    return;
+                const exported = node.parent.parent?.type === "ExportNamedDeclaration";
+                if (!exported)
+                    return;
+                if (isComponentLikeName(name) || isHookName(name))
+                    return;
+                const init = node.init;
+                if (!init || (init.type !== "ArrowFunctionExpression" && init.type !== "FunctionExpression")) {
+                    return;
+                }
+                if (init.body.type === "BlockStatement" && hasHookUsage(init.body))
+                    return;
+                report(node, name);
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/shared-style-dedup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ESLint rule: pasika/shared-style-dedup
+ *
+ * A style or group of styles that two or more components use together and
+ * should change together MUST become one named custom utility. Styling used by
+ * only one component MUST stay in that component file as static Tailwind
+ * utility classes. The rule compares className lists across the whole tree,
+ * because a single file cannot see what other components use.
+ *
+ * @see docs/styling-guide/rules/theme-and-utility-definition-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const sharedStyleDedupRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/shared-style-dedup.js

@@ -0,0 +1,91 @@
+/**
+ * ESLint rule: pasika/shared-style-dedup
+ *
+ * A style or group of styles that two or more components use together and
+ * should change together MUST become one named custom utility. Styling used by
+ * only one component MUST stay in that component file as static Tailwind
+ * utility classes. The rule compares className lists across the whole tree,
+ * because a single file cannot see what other components use.
+ *
+ * @see docs/styling-guide/rules/theme-and-utility-definition-rule.md
+ */
+import path from "node:path";
+import { readFileSync, statSync } from "node:fs";
+import { getProjectIndex } from "../project/index.js";
+import { segmentsOf } from "../project/ccf.js";
+/** Static className string literals; dynamic class lists are not comparable across files. */
+const CLASS_NAME = /className="(?<classes>[^"]+)"/g;
+let comboCache;
+/** className combinations used by each component file, memoized per tree. */
+function combosFor(index) {
+    const files = [...index.modules.keys()]
+        .filter((file) => file.endsWith(".tsx") || file.endsWith(".jsx"))
+        .sort((left, right) => left.localeCompare(right));
+    let fingerprint = "";
+    for (const file of files) {
+        try {
+            fingerprint += String(statSync(file).mtimeMs);
+        }
+        catch {
+            fingerprint += "0";
+        }
+    }
+    if (comboCache?.sourceRoot === index.sourceRoot && comboCache.fingerprint === fingerprint) {
+        return comboCache.combos;
+    }
+    const combos = new Map();
+    for (const file of files) {
+        const text = readFileSync(file, "utf8");
+        for (const match of text.matchAll(CLASS_NAME)) {
+            const classes = (match.groups?.classes ?? "").split(/\s+/).filter(Boolean);
+            if (classes.length < 2)
+                continue;
+            const key = [...classes].sort().join(" ");
+            const users = combos.get(key) ?? new Set();
+            users.add(file);
+            combos.set(key, users);
+        }
+    }
+    comboCache = { sourceRoot: index.sourceRoot, fingerprint, combos };
+    return combos;
+}
+export const sharedStyleDedupRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require a className combination used by two or more components to become a named custom utility.",
+        },
+    },
+    create(context) {
+        const sourceRoot = path.resolve("src");
+        const file = path.resolve(context.filename);
+        const segments = segmentsOf(file, sourceRoot);
+        if (segments.length === 0)
+            return {};
+        const index = getProjectIndex(sourceRoot);
+        if (!index)
+            return {};
+        // Report each shared combination once, on the alphabetically first file
+        // that uses it, so the whole tree produces one finding per combination.
+        const combos = combosFor(index);
+        const sharedHere = [...combos.entries()]
+            .filter(([, users]) => users.size >= 2 && users.has(file))
+            .filter(([, users]) => [...users].sort((left, right) => left.localeCompare(right))[0] === file);
+        if (sharedHere.length === 0)
+            return {};
+        return {
+            Program(node) {
+                for (const [combo, users] of sharedHere) {
+                    context.report({
+                        node,
+                        loc: { line: 1, column: 0 },
+                        message: `Class combination "${combo}" is used by ${String(users.size)} components and should change ` +
+                            "together; create a named custom Tailwind utility for it. " +
+                            "See docs/styling-guide/rules/theme-and-utility-definition-rule.md",
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/stay-flat.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ESLint rule: pasika/stay-flat
+ *
+ * A component MUST stay flat until it has one or more exclusive child
+ * components, then MUST be nested in a folder with the same name. An exclusive
+ * child is a sibling component that only this component uses, so a flat
+ * component that owns such children must move into a folder named after it.
+ *
+ * @see docs/code-organization-guide/rules/folder-nesting-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const stayFlatRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/stay-flat.js

@@ -0,0 +1,81 @@
+/**
+ * ESLint rule: pasika/stay-flat
+ *
+ * A component MUST stay flat until it has one or more exclusive child
+ * components, then MUST be nested in a folder with the same name. An exclusive
+ * child is a sibling component that only this component uses, so a flat
+ * component that owns such children must move into a folder named after it.
+ *
+ * @see docs/code-organization-guide/rules/folder-nesting-rule.md
+ */
+import path from "node:path";
+import { getProjectIndex } from "../project/index.js";
+import { segmentsOf } from "../project/ccf.js";
+export const stayFlatRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require a component with exclusive children to be nested in a folder with the same name.",
+        },
+    },
+    create(context) {
+        const sourceRoot = path.resolve("src");
+        const file = path.resolve(context.filename);
+        const segments = segmentsOf(file, sourceRoot);
+        // A component file directly inside a feature folder: src/features/<feature>/<file>
+        if (segments.length !== 3 || segments[0] !== "features")
+            return {};
+        const index = getProjectIndex(sourceRoot);
+        if (!index)
+            return {};
+        const module = index.modules.get(file);
+        if (!module?.exports.some((exp) => exp.kind === "component"))
+            return {};
+        const featureName = segments[1];
+        if (!featureName)
+            return {};
+        // A sibling component file is an exclusive child when every file that
+        // imports it is this component or a support file in the same feature folder.
+        const exclusiveChildren = [...index.modules.values()].filter((candidate) => {
+            if (candidate.file === file)
+                return false;
+            const candidateSegments = segmentsOf(candidate.file, sourceRoot);
+            if (candidateSegments.length !== 3)
+                return false;
+            if (candidateSegments[0] !== "features" || candidateSegments[1] !== featureName)
+                return false;
+            if (candidateSegments[2]?.startsWith("index."))
+                return false;
+            if (!candidate.exports.some((exp) => exp.kind === "component"))
+                return false;
+            const consumers = index.consumers.get(candidate.file) ?? new Set();
+            if (consumers.size === 0)
+                return false;
+            return [...consumers].every((consumer) => {
+                if (consumer === file)
+                    return true;
+                const consumerSegments = segmentsOf(consumer, sourceRoot);
+                if (consumerSegments[0] !== "features" || consumerSegments[1] !== featureName)
+                    return false;
+                return !(index.modules.get(consumer)?.exports.some((exp) => exp.kind === "component") ?? false);
+            });
+        });
+        if (exclusiveChildren.length === 0)
+            return {};
+        const childNames = exclusiveChildren
+            .map((child) => child.exports.find((exp) => exp.kind === "component")?.name)
+            .filter((name) => name !== undefined);
+        return {
+            Program(node) {
+                context.report({
+                    node,
+                    loc: { line: 1, column: 0 },
+                    message: `This component has exclusive child component(s) ${childNames.join(", ")}; ` +
+                        `nest it in a folder named after it inside src/features/${featureName}/. ` +
+                        "See docs/code-organization-guide/rules/folder-nesting-rule.md",
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/support-folder-shape.d.ts

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

package/dist/eslint/pasika/rules/support-folder-shape.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+const SUPPORT_FOLDERS = new Set(["constants", "types", "schemas"]);
+const INDEX_NAMES = new Set(["index.ts", "index.tsx", "index.mts", "index.cts"]);
+export const supportFolderShapeRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require support-folder exports to be defined in index.ts or named-re-exported by it.",
+        },
+    },
+    create(context) {
+        const filename = path.resolve(context.filename);
+        const baseName = path.basename(filename);
+        if (!INDEX_NAMES.has(baseName))
+            return {};
+        const folder = path.basename(path.dirname(filename));
+        if (!SUPPORT_FOLDERS.has(folder))
+            return {};
+        const directory = path.dirname(filename);
+        let entries;
+        try {
+            entries = fs.readdirSync(directory);
+        }
+        catch {
+            return {};
+        }
+        const siblingModules = entries.filter((entry) => entry !== baseName && /\.(?:[cm]?tsx?|jsx?)$/.test(entry));
+        if (siblingModules.length === 0)
+            return {};
+        return {
+            Program(node) {
+                const source = context.sourceCode.text;
+                const hasDirectExport = /export\s+(?:const|let|var|function|class|type|interface|enum)\b/.test(source);
+                if (hasDirectExport)
+                    return;
+                const exportedFiles = new Set();
+                const exportPattern = /export\s+(?:\{[^}]*\}|\*[^;]*)\s+from\s+["'](?<specifier>\.[^"']+)["']/g;
+                for (const match of source.matchAll(exportPattern)) {
+                    const specifier = match.groups?.specifier;
+                    if (specifier)
+                        exportedFiles.add(path.basename(specifier));
+                }
+                const missing = siblingModules.filter((entry) => {
+                    const stem = entry.replace(/\.(?:[cm]?tsx?|jsx?)$/, "");
+                    return !exportedFiles.has(stem);
+                });
+                if (missing.length === 0)
+                    return;
+                context.report({
+                    node,
+                    message: `${folder}/index.ts must named-re-export every support file: ${missing.join(", ")}. ` +
+                        `See docs/code-organization-guide/rules/${folder === "constants" ? "constants" : "types-and-schemas"}-rule.md`,
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/type-extraction.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ESLint rule: pasika/type-extraction
+ *
+ * A type or schema declared in a component MUST stay in that component file
+ * until another file imports it without the component where it is defined, and
+ * a type or schema declared outside a component MUST stay in its file until
+ * another file needs it without using the code in that file. Importing the
+ * type alongside the component that defines it never requires extraction.
+ *
+ * @see docs/code-organization-guide/rules/types-and-schemas-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const typeExtractionRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/type-extraction.js

@@ -0,0 +1,85 @@
+/**
+ * ESLint rule: pasika/type-extraction
+ *
+ * A type or schema declared in a component MUST stay in that component file
+ * until another file imports it without the component where it is defined, and
+ * a type or schema declared outside a component MUST stay in its file until
+ * another file needs it without using the code in that file. Importing the
+ * type alongside the component that defines it never requires extraction.
+ *
+ * @see docs/code-organization-guide/rules/types-and-schemas-rule.md
+ */
+import path from "node:path";
+import { getProjectIndex, symbolKey } from "../project/index.js";
+import { describeConsumers, segmentsOf } from "../project/ccf.js";
+export const typeExtractionRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require a type or schema imported without its defining code to be extracted.",
+        },
+    },
+    create(context) {
+        const sourceRoot = path.resolve("src");
+        const file = path.resolve(context.filename);
+        const segments = segmentsOf(file, sourceRoot);
+        if (segments.length === 0)
+            return {};
+        const index = getProjectIndex(sourceRoot);
+        if (!index)
+            return {};
+        const module = index.modules.get(file);
+        if (!module)
+            return {};
+        const componentExport = module.exports.find((exp) => exp.kind === "component");
+        // The code a consumer can use from this file besides types: hooks,
+        // schemas, constants, and functions.
+        const codeExports = module.exports.filter((exp) => exp.kind !== "type" && exp.kind !== "other");
+        const findings = [];
+        for (const exp of module.exports) {
+            if (exp.kind !== "type" && exp.kind !== "schema")
+                continue;
+            const consumers = [...(index.symbolConsumers.get(symbolKey(file, exp.name)) ?? [])];
+            if (consumers.length === 0)
+                continue;
+            if (componentExport) {
+                // A consumer that also imports the component uses the code alongside
+                // the type, so extraction is not required.
+                const componentConsumers = index.symbolConsumers.get(symbolKey(file, componentExport.name)) ?? new Set();
+                const independent = consumers.filter((consumer) => !componentConsumers.has(consumer));
+                if (independent.length === 0)
+                    continue;
+                findings.push({
+                    line: exp.line,
+                    message: `${exp.kind} "${exp.name}" is imported by ${describeConsumers(independent, sourceRoot)} without ` +
+                        `the component "${componentExport.name}" that defines it. Extract it to a types/ or schemas/ folder. ` +
+                        "See docs/code-organization-guide/rules/types-and-schemas-rule.md",
+                });
+                continue;
+            }
+            if (codeExports.length === 0)
+                continue;
+            // A consumer that imports any other code from this file uses the file as
+            // a whole; one that takes only the type needs it independently.
+            const independent = consumers.filter((consumer) => !codeExports.some((other) => index.symbolConsumers.get(symbolKey(file, other.name))?.has(consumer)));
+            if (independent.length === 0)
+                continue;
+            findings.push({
+                line: exp.line,
+                message: `${exp.kind} "${exp.name}" is imported by ${describeConsumers(independent, sourceRoot)} without using ` +
+                    "the code in this file. Extract it to a types/ or schemas/ folder. " +
+                    "See docs/code-organization-guide/rules/types-and-schemas-rule.md",
+            });
+        }
+        if (findings.length === 0)
+            return {};
+        return {
+            Program(node) {
+                for (const finding of findings) {
+                    context.report({ node, loc: { line: finding.line, column: 0 }, message: finding.message });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/ui-state.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ESLint rule: pasika/ui-state
+ *
+ * Enforces native or ARIA state expression and Tailwind state variants.
+ *
+ * @see docs/styling-guide/rules/component-ui-state-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const uiStateRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/ui-state.js

@@ -0,0 +1,99 @@
+/**
+ * ESLint rule: pasika/ui-state
+ *
+ * Enforces native or ARIA state expression and Tailwind state variants.
+ *
+ * @see docs/styling-guide/rules/component-ui-state-rule.md
+ */
+const STATE_PROPS = new Set([
+    "disabled",
+    "loading",
+    "selected",
+    "expanded",
+    "pressed",
+    "checked",
+    "busy",
+    "invalid",
+    "open",
+]);
+const STATE_ATTRIBUTES = new Set([
+    "disabled",
+    "aria-busy",
+    "aria-selected",
+    "aria-expanded",
+    "aria-pressed",
+    "aria-checked",
+    "aria-invalid",
+    "open",
+]);
+const STATE_CLASS_RE = /^(?:disabled|aria-(?:busy|selected|expanded|pressed|checked|invalid)|data-\[state)/;
+function isComponentElement(node) {
+    const name = node.openingElement?.name;
+    return name?.type === "JSXIdentifier" && /^[A-Z]/.test(name.name);
+}
+function expressionName(node) {
+    if (node?.type !== "JSXExpressionContainer")
+        return undefined;
+    if (node.expression?.type === "Identifier")
+        return node.expression.name;
+    return undefined;
+}
+export const uiStateRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require semantic UI states and Tailwind state variants.",
+        },
+    },
+    create(context) {
+        return {
+            JSXElement(node) {
+                if (!isComponentElement(node))
+                    return;
+                const attributes = node.openingElement?.attributes ?? [];
+                const names = new Set();
+                for (const attribute of attributes) {
+                    names.add(String(attribute.name?.name));
+                }
+                for (const attribute of attributes) {
+                    const name = String(attribute.name?.name);
+                    const stateName = expressionName(attribute.value);
+                    if (!stateName || !STATE_PROPS.has(stateName))
+                        continue;
+                    const hasNativeState = [...STATE_ATTRIBUTES].some((nativeName) => names.has(nativeName));
+                    if (!hasNativeState) {
+                        context.report({
+                            node: attribute,
+                            message: `UI state prop "${name}" should be expressed with a native or ARIA state attribute. ` +
+                                "See docs/styling-guide/rules/component-ui-state-rule.md",
+                        });
+                    }
+                }
+                for (const attribute of attributes) {
+                    if (String(attribute.name?.name) !== "className")
+                        continue;
+                    const value = attribute.value;
+                    const text = value?.type === "Literal" ? String(value.value) : "";
+                    if (value?.type === "JSXExpressionContainer" && value.expression.type === "ConditionalExpression") {
+                        const consequent = value.expression.consequent;
+                        const alternate = value.expression.alternate;
+                        const classes = [consequent, alternate]
+                            .filter((branch) => branch.type === "Literal" && typeof branch.value === "string")
+                            .flatMap((branch) => String(branch.value).split(/\s+/));
+                        if (classes.length > 0 && !classes.some((className) => STATE_CLASS_RE.test(className))) {
+                            context.report({
+                                node: attribute,
+                                message: "Use a Tailwind state variant for a UI state instead of conditional replacement classes. " +
+                                    "See docs/styling-guide/rules/component-ui-state-rule.md",
+                            });
+                        }
+                    }
+                    if (text.split(/\s+/).some((className) => className.includes("state-"))) {
+                        return;
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/util-file-name.d.ts

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

package/dist/eslint/pasika/rules/util-file-name.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { parseModule } from "../project/parse-module.js";
+function toKebabCase(value) {
+    return value
+        .replace(/(?<lower>[a-z0-9])(?<upper>[A-Z])/g, "$<lower>-$<upper>")
+        .replace(/(?<first>[A-Z])(?<rest>[A-Z][a-z])/g, "$<first>-$<rest>")
+        .toLowerCase();
+}
+export const utilFileNameRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require single-function utility files to use the function's kebab-case name.",
+        },
+    },
+    create(context) {
+        const filename = path.resolve(context.filename);
+        const segments = filename.replace(/\\/g, "/").split("/");
+        if (!segments.includes("utils"))
+            return {};
+        let module;
+        try {
+            module = parseModule(filename);
+        }
+        catch {
+            return {};
+        }
+        const functions = module.exports.filter((entry) => entry.kind === "function");
+        if (functions.length !== 1 || module.exports.length !== 1)
+            return {};
+        const functionName = functions[0]?.name;
+        if (!functionName)
+            return {};
+        const expected = toKebabCase(functionName);
+        const actual = path.basename(filename, path.extname(filename));
+        if (!expected || actual === expected)
+            return {};
+        return {
+            Program(node) {
+                context.report({
+                    node,
+                    message: `A utility file exporting ${functionName} must be named ${expected}.${path.extname(filename).slice(1)}.`,
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/value-extraction.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ESLint rule: pasika/value-extraction
+ *
+ * A value MUST remain in its declaring component or file until another file
+ * imports it independently; it MUST then be extracted as a constant. A file
+ * under src/app/ is supposed to hold only framework-convention files, so a
+ * consumer outside src/app/ reaching into one means a value has crossed the
+ * independence threshold.
+ *
+ * @see docs/code-organization-guide/rules/constants-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const valueExtractionRule: Rule.RuleModule;