pasika 0.3.1 → 0.3.3

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

@@ -9,6 +9,7 @@
  * @see docs/code-organization-guide/rules/smart-vs-dumb-component-rule.md
  */
 import path from "node:path";
+import { parseComponentInfo } from "./component-conventions.js";
 /**
  * Next.js App Router routing files that are exempt from filename-case checks.
  * https://nextjs.org/docs/app/getting-started/project-structure#routing-files
@@ -70,12 +71,34 @@ export const filenameCaseRule = {
         if (NEXT_ROUTING_FILES.has(base)) {
             return {};
         }
-        // .tsx components may be PascalCase (smart) or kebab-case (dumb)
+        // .tsx components use PascalCase when smart and kebab-case when dumb.
         if (ext === ".tsx") {
-            if (!(isPascalCase(base) || isKebabCase(base))) {
-                return report(context, filename, ext);
-            }
-            return {};
+            return {
+                Program(node) {
+                    const components = parseComponentInfo(context.sourceCode.text, filename);
+                    const component = components[0];
+                    if (component?.smart && !isPascalCase(base)) {
+                        context.report({
+                            node,
+                            message: `Smart component files must use PascalCase.tsx. Filename "${path.basename(filename)}" is not PascalCase.`,
+                        });
+                        return;
+                    }
+                    if (component && !component.smart && !isKebabCase(base)) {
+                        context.report({
+                            node,
+                            message: `Dumb component files must use kebab-case.tsx. Filename "${path.basename(filename)}" is not kebab-case.`,
+                        });
+                        return;
+                    }
+                    if (!component && !(isPascalCase(base) || isKebabCase(base))) {
+                        context.report({
+                            node,
+                            message: `Filename "${path.basename(filename)}" does not match pasika conventions. Component files must be PascalCase.tsx (smart) or kebab-case.tsx (dumb).`,
+                        });
+                    }
+                },
+            };
         }
         // Everything else must be kebab-case
         if (!isKebabCase(base)) {

package/dist/eslint/pasika/rules/hook-complexity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ESLint rule: pasika/hook-complexity
+ *
+ * - A custom hook with exactly one consumer MUST be extracted when it contains
+ *   two or more imperative categories.
+ * - A custom hook with one consumer that contains fewer than two imperative
+ *   categories MUST stay inline in its consumer file.
+ *
+ * @see docs/code-organization-guide/rules/hook-extraction-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const hookComplexityRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/hook-complexity.js

@@ -0,0 +1,114 @@
+/**
+ * ESLint rule: pasika/hook-complexity
+ *
+ * - A custom hook with exactly one consumer MUST be extracted when it contains
+ *   two or more imperative categories.
+ * - A custom hook with one consumer that contains fewer than two imperative
+ *   categories MUST stay inline in its consumer file.
+ *
+ * @see docs/code-organization-guide/rules/hook-extraction-rule.md
+ */
+import path from "node:path";
+import ts from "typescript";
+const REACT_HOOKS = new Set([
+    "useState",
+    "useEffect",
+    "useContext",
+    "useReducer",
+    "useCallback",
+    "useMemo",
+    "useRef",
+    "useLayoutEffect",
+    "useImperativeHandle",
+    "useDebugValue",
+    "useDeferredValue",
+    "useTransition",
+    "useId",
+    "useSyncExternalStore",
+    "useInsertionEffect",
+]);
+function isHookName(name) {
+    return /^use[A-Z]/.test(name);
+}
+/**
+ * Counts the distinct React hook categories called anywhere inside a hook body.
+ * Re-parses just the body's source slice with the TypeScript compiler so the
+ * walk stays fully typed instead of unrolling ESTree unions by hand.
+ */
+function countImperativeCategories(body, sourceText) {
+    const start = body.range?.[0] ?? 0;
+    const end = body.range?.[1] ?? sourceText.length;
+    const sourceFile = ts.createSourceFile("hook.ts", sourceText.slice(start, end), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const categories = new Set();
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && REACT_HOOKS.has(node.expression.text)) {
+            categories.add(node.expression.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return categories.size;
+}
+export const hookComplexityRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require extraction of complex single-consumer hooks and inline of simple ones.",
+        },
+    },
+    create(context) {
+        const filename = context.filename;
+        const sourceRoot = path.resolve("src");
+        const relative = path.relative(sourceRoot, filename);
+        if (relative.startsWith(".."))
+            return {};
+        const segments = relative.split(path.sep);
+        const sourceText = context.sourceCode.text;
+        function checkHook(node, name, body, exported) {
+            if (!exported)
+                return;
+            if (!name || !isHookName(name))
+                return;
+            if (!body)
+                return;
+            const imperativeCount = countImperativeCategories(body, sourceText);
+            const parentFolder = segments.length >= 2 ? segments[segments.length - 2] : undefined;
+            const inSupportFolder = parentFolder === "hooks";
+            if (imperativeCount >= 2 && !inSupportFolder) {
+                context.report({
+                    node,
+                    message: `Hook "${name}" has ${String(imperativeCount)} imperative categories and must be extracted to a hooks/ folder. ` +
+                        "See docs/code-organization-guide/rules/hook-extraction-rule.md",
+                });
+            }
+            else if (imperativeCount < 2 && inSupportFolder) {
+                context.report({
+                    node,
+                    message: `Hook "${name}" has fewer than two imperative categories and must stay inline in its consumer file. ` +
+                        "See docs/code-organization-guide/rules/hook-extraction-rule.md",
+                });
+            }
+        }
+        return {
+            FunctionDeclaration(node) {
+                const exported = node.parent?.type === "ExportNamedDeclaration";
+                checkHook(node, node.id?.name, node.body, exported);
+            },
+            VariableDeclarator(node) {
+                if (node.id.type !== "Identifier")
+                    return;
+                const exported = node.parent.parent?.type === "ExportNamedDeclaration";
+                if (!exported)
+                    return;
+                const init = node.init;
+                if (!init || (init.type !== "ArrowFunctionExpression" && init.type !== "FunctionExpression")) {
+                    return;
+                }
+                if (init.body.type !== "BlockStatement")
+                    return;
+                checkHook(node, node.id.name, init.body, true);
+            },
+        };
+    },
+};

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

@@ -0,0 +1,11 @@
+/**
+ * ESLint rule: pasika/hook-extraction
+ *
+ * A custom hook MUST be extracted to its own file when two or more consumers
+ * use it. The file must be read across the tree, because how many files import
+ * a hook is not visible from one file.
+ *
+ * @see docs/code-organization-guide/rules/hook-extraction-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const hookExtractionRule: Rule.RuleModule;

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

@@ -0,0 +1,55 @@
+/**
+ * ESLint rule: pasika/hook-extraction
+ *
+ * A custom hook MUST be extracted to its own file when two or more consumers
+ * use it. The file must be read across the tree, because how many files import
+ * a hook is not visible from one file.
+ *
+ * @see docs/code-organization-guide/rules/hook-extraction-rule.md
+ */
+import path from "node:path";
+import { getProjectIndex, symbolKey } from "../project/index.js";
+import { folderSegmentsOf, segmentsOf } from "../project/ccf.js";
+export const hookExtractionRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require a custom hook with two or more consumers to live in its own hooks/ file.",
+        },
+    },
+    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 folder = folderSegmentsOf(file, sourceRoot);
+        const alreadyInHooksFolder = folder.length > 0 && folder[folder.length - 1] === "hooks";
+        const reusedHooks = module.exports
+            .filter((exp) => exp.kind === "hook" && !alreadyInHooksFolder)
+            .map((exp) => ({ exp, consumers: index.symbolConsumers.get(symbolKey(file, exp.name)) }))
+            .filter(({ consumers }) => (consumers?.size ?? 0) >= 2);
+        if (reusedHooks.length === 0)
+            return {};
+        return {
+            Program(node) {
+                for (const { exp, consumers } of reusedHooks) {
+                    context.report({
+                        node,
+                        loc: { line: exp.line, column: 0 },
+                        message: `Hook "${exp.name}" has ${String(consumers?.size ?? 0)} consumers; ` +
+                            "extract it to its own file in a hooks/ folder. " +
+                            "See docs/code-organization-guide/rules/hook-extraction-rule.md",
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/import-through-index.d.ts

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

package/dist/eslint/pasika/rules/import-through-index.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { resolveSpecifier } from "../project/index.js";
+import { segmentsOf } from "../project/ccf.js";
+export const importThroughIndexRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require imports of support files to use their support-folder index.",
+        },
+    },
+    create(context) {
+        const filename = path.resolve(context.filename);
+        const sourceRoot = sourceRootOf(filename);
+        return {
+            Program(node) {
+                for (const specifier of importSpecifiers(context.sourceCode.text)) {
+                    const target = resolveSpecifier(filename, specifier, sourceRoot);
+                    if (!target)
+                        continue;
+                    const targetSegments = segmentsOf(target, sourceRoot);
+                    const supportFolderIndex = targetSegments.findIndex((segment) => ["constants", "types", "schemas"].includes(segment));
+                    const supportFolder = supportFolderIndex >= 0 ? targetSegments[supportFolderIndex] : undefined;
+                    if (!supportFolder || path.basename(target).startsWith("index."))
+                        continue;
+                    const folderIndex = targetSegments.slice(0, supportFolderIndex + 1);
+                    const expected = `@/${folderIndex.join("/")}`;
+                    context.report({
+                        node,
+                        message: `Import support files through ${expected} instead of "${specifier}". ` +
+                            "See the code-organization-guide exports and imports rules.",
+                    });
+                }
+            },
+        };
+    },
+};
+function importSpecifiers(source) {
+    const specifiers = [];
+    const pattern = /\bimport\s+(?:(?:type\s+)?[\s\S]*?\sfrom\s+)?["'](?<specifier>[^"']+)["']/g;
+    for (const match of source.matchAll(pattern)) {
+        const specifier = match.groups?.specifier;
+        if (specifier)
+            specifiers.push(specifier);
+    }
+    return specifiers;
+}
+function sourceRootOf(filename) {
+    const marker = `${path.sep}src${path.sep}`;
+    const srcIndex = filename.lastIndexOf(marker);
+    return srcIndex >= 0 ? filename.slice(0, srcIndex + marker.length - 1) : path.resolve("src");
+}

package/dist/eslint/pasika/rules/interactive-component.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule: pasika/interactive-component
+ *
+ * Interactive elements are component boundaries when they are mixed with other
+ * content in the same component. Standalone interactive components are valid.
+ *
+ * @see docs/code-organization-guide/rules/interactive-component-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const interactiveComponentRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/interactive-component.js

@@ -0,0 +1,76 @@
+/**
+ * ESLint rule: pasika/interactive-component
+ *
+ * Interactive elements are component boundaries when they are mixed with other
+ * content in the same component. Standalone interactive components are valid.
+ *
+ * @see docs/code-organization-guide/rules/interactive-component-rule.md
+ */
+const INTERACTIVE_TAGS = new Set([
+    "a",
+    "button",
+    "details",
+    "embed",
+    "iframe",
+    "input",
+    "label",
+    "select",
+    "textarea",
+    "video",
+]);
+function tagName(node) {
+    const name = node.openingElement?.name;
+    if (name?.type !== "JSXIdentifier")
+        return undefined;
+    return name.name;
+}
+function isInteractive(node) {
+    const name = tagName(node);
+    return name !== undefined && INTERACTIVE_TAGS.has(name);
+}
+function isComponentElement(node) {
+    const name = tagName(node);
+    return name !== undefined && /^[A-Z]/.test(name);
+}
+function isComponentReturn(node) {
+    const parent = node.parent;
+    if (parent.type === "ReturnStatement")
+        return true;
+    return parent.type === "ArrowFunctionExpression" && parent.body === node;
+}
+export const interactiveComponentRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require interactive HTML elements mixed with other content to be extracted into components.",
+        },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".tsx") && !context.filename.endsWith(".jsx"))
+            return {};
+        return {
+            JSXElement(node) {
+                if (!isInteractive(node))
+                    return;
+                if (isComponentElement(node.parent)) {
+                    return;
+                }
+                if (isInteractive(node.parent)) {
+                    return;
+                }
+                if (isComponentReturn(node)) {
+                    return;
+                }
+                const name = tagName(node);
+                if (name === undefined)
+                    return;
+                context.report({
+                    node,
+                    message: `Extract the interactive <${name}> into a descriptive component. ` +
+                        "See docs/code-organization-guide/rules/interactive-component-rule.md",
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/json/index.d.ts

@@ -0,0 +1,5 @@
+export declare const jsonRules: {
+    "no-cache-flag": import("@eslint/json").JSONRuleDefinition;
+    "no-vulyk-dependency": import("@eslint/json").JSONRuleDefinition;
+};
+export type JsonRuleName = keyof typeof jsonRules;

package/dist/eslint/pasika/rules/json/index.js

@@ -0,0 +1,9 @@
+/**
+ * All JSON rules for the package.json checks.
+ */
+import { noCacheFlagRule } from "./no-cache-flag.js";
+import { noVulykDependencyRule } from "./no-vulyk-dependency.js";
+export const jsonRules = {
+    "no-cache-flag": noCacheFlagRule,
+    "no-vulyk-dependency": noVulykDependencyRule,
+};

package/dist/eslint/pasika/rules/json/no-cache-flag.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule: pasika/no-cache-flag
+ *
+ * A lint command MUST NOT pass ESLint's --cache flag, because rules that
+ * compare a file against the rest of the tree need every file in the run.
+ *
+ * @see docs/agent-policy.md
+ */
+import type { JSONRuleDefinition } from "@eslint/json";
+export declare const noCacheFlagRule: JSONRuleDefinition;

package/dist/eslint/pasika/rules/json/no-cache-flag.js

@@ -0,0 +1,45 @@
+/**
+ * ESLint rule: pasika/no-cache-flag
+ *
+ * A lint command MUST NOT pass ESLint's --cache flag, because rules that
+ * compare a file against the rest of the tree need every file in the run.
+ *
+ * @see docs/agent-policy.md
+ */
+function memberName(member) {
+    return member.name.type === "String" ? member.name.value : member.name.name;
+}
+export const noCacheFlagRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require lint scripts to not pass ESLint's --cache flag.",
+        },
+    },
+    create(context) {
+        return {
+            Document(node) {
+                const root = node.body;
+                if (root.type !== "Object")
+                    return;
+                const scripts = root.members.find((member) => memberName(member) === "scripts");
+                if (scripts?.value.type !== "Object")
+                    return;
+                for (const member of scripts.value.members) {
+                    const name = memberName(member);
+                    if (name !== "lint" && name !== "fix")
+                        continue;
+                    if (member.value.type !== "String")
+                        continue;
+                    if (member.value.value.includes("--cache")) {
+                        context.report({
+                            node: member,
+                            message: "Lint scripts must not pass ESLint's --cache flag because cross-file rules require every file in the run.",
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/json/no-vulyk-dependency.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule: pasika/no-vulyk-dependency
+ *
+ * Vulyk MUST NOT be added to package.json in order to run its CLI; it MUST run
+ * as an ephemeral command such as npx vulyk@latest.
+ *
+ * @see docs/agent-policy.md
+ */
+import type { JSONRuleDefinition } from "@eslint/json";
+export declare const noVulykDependencyRule: JSONRuleDefinition;

package/dist/eslint/pasika/rules/json/no-vulyk-dependency.js

@@ -0,0 +1,41 @@
+/**
+ * ESLint rule: pasika/no-vulyk-dependency
+ *
+ * Vulyk MUST NOT be added to package.json in order to run its CLI; it MUST run
+ * as an ephemeral command such as npx vulyk@latest.
+ *
+ * @see docs/agent-policy.md
+ */
+function memberName(member) {
+    return member.name.type === "String" ? member.name.value : member.name.name;
+}
+export const noVulykDependencyRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require vulyk to run as an ephemeral command, not a package.json dependency.",
+        },
+    },
+    create(context) {
+        return {
+            Document(node) {
+                const root = node.body;
+                if (root.type !== "Object")
+                    return;
+                for (const key of ["dependencies", "devDependencies"]) {
+                    const section = root.members.find((member) => memberName(member) === key);
+                    if (section?.value.type !== "Object")
+                        continue;
+                    const vulyk = section.value.members.find((member) => memberName(member) === "vulyk");
+                    if (vulyk) {
+                        context.report({
+                            node: vulyk,
+                            message: 'Vulyk must not be a package.json dependency. Run it as "npx vulyk@latest" instead.',
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/json/rule-tester.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared RuleTester wiring for the package.json rule tests.
+ *
+ * Each `describe` title in a rule test is the exact text of the requirement the
+ * case pins, which is how `pasika coverage` verifies that a requirement recorded
+ * as lint-enforced has a test behind it.
+ */
+import { describe } from "node:test";
+import { RuleTester } from "eslint";
+export declare const jsonRuleTester: RuleTester;
+export { describe };

package/dist/eslint/pasika/rules/json/rule-tester.js

@@ -0,0 +1,21 @@
+/**
+ * Shared RuleTester wiring for the package.json rule tests.
+ *
+ * Each `describe` title in a rule test is the exact text of the requirement the
+ * case pins, which is how `pasika coverage` verifies that a requirement recorded
+ * as lint-enforced has a test behind it.
+ */
+import { describe, it } from "node:test";
+import { RuleTester } from "eslint";
+import jsonPlugin from "@eslint/json";
+import { jsonRules } from "../../index.js";
+RuleTester.describe = describe;
+RuleTester.it = it;
+export const jsonRuleTester = new RuleTester({
+    language: "json/json",
+    plugins: {
+        json: { languages: { json: jsonPlugin.languages.json } },
+        pasika: { rules: jsonRules },
+    },
+});
+export { describe };

package/dist/eslint/pasika/rules/jsx-hygiene.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ESLint rule: pasika/jsx-hygiene
+ *
+ * Keeps calculations and complex conditions out of JSX children and attributes.
+ *
+ * @see docs/code-organization-guide/rules/jsx-hygiene-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const jsxHygieneRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/jsx-hygiene.js

@@ -0,0 +1,108 @@
+/**
+ * ESLint rule: pasika/jsx-hygiene
+ *
+ * Keeps calculations and complex conditions out of JSX children and attributes.
+ *
+ * @see docs/code-organization-guide/rules/jsx-hygiene-rule.md
+ */
+import ts from "typescript";
+const ARITHMETIC_OPERATORS = new Set(["+", "-", "*", "/", "%"]);
+function isCallExpression(node) {
+    return node.type === "CallExpression";
+}
+function isMemberExpression(node) {
+    return ["MemberExpression", "OptionalMemberExpression"].includes(node.type);
+}
+function logicalOperatorCount(node) {
+    if (node.type !== "LogicalExpression")
+        return 0;
+    return 1 + logicalOperatorCount(node.left) + logicalOperatorCount(node.right);
+}
+/**
+ * Whether the parsed text of a node's subtree contains a conditional expression
+ * anywhere. Re-parses just the node's source slice with the TypeScript compiler
+ * so the walk stays fully typed, including inside JSX children.
+ */
+function containsConditionalIn(node, sourceText) {
+    const start = node.range?.[0] ?? 0;
+    const end = node.range?.[1] ?? sourceText.length;
+    const sourceFile = ts.createSourceFile("fragment.tsx", sourceText.slice(start, end), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    let found = false;
+    const visit = (child) => {
+        if (found)
+            return;
+        if (ts.isConditionalExpression(child)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(child, visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+function hasNestedTernary(node, sourceText) {
+    if (node.type !== "ConditionalExpression")
+        return false;
+    return containsConditionalIn(node.consequent, sourceText) || containsConditionalIn(node.alternate, sourceText);
+}
+function hasChainedCall(node) {
+    if (!isCallExpression(node) || !isMemberExpression(node.callee))
+        return false;
+    return isCallExpression(node.callee.object) || isMemberExpression(node.callee.object);
+}
+function hasExternalCall(node) {
+    if (!isCallExpression(node))
+        return false;
+    const callee = node.callee;
+    if (callee.type === "Identifier" && callee.name === "cn")
+        return false;
+    if (isMemberExpression(callee))
+        return false;
+    return callee.type === "Identifier";
+}
+function findViolation(node, sourceText) {
+    if (node.type === "BinaryExpression" && ARITHMETIC_OPERATORS.has(node.operator)) {
+        return "arithmetic";
+    }
+    if (hasChainedCall(node))
+        return "chained built-in method calls";
+    if (hasExternalCall(node))
+        return "calls to functions declared outside the component";
+    if (hasNestedTernary(node, sourceText))
+        return "nested ternaries";
+    if (logicalOperatorCount(node) >= 2)
+        return "conditions containing two or more logical operators";
+    return undefined;
+}
+export const jsxHygieneRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require complex JSX expressions to be extracted before return.",
+        },
+    },
+    create(context) {
+        if (!context.filename.endsWith(".tsx") && !context.filename.endsWith(".jsx"))
+            return {};
+        const sourceText = context.sourceCode.text;
+        function checkExpression(node) {
+            const violation = findViolation(node, sourceText);
+            if (!violation)
+                return;
+            context.report({
+                node,
+                message: `Extract ${violation} from JSX before return. ` +
+                    "See docs/code-organization-guide/rules/jsx-hygiene-rule.md",
+            });
+        }
+        return {
+            JSXExpressionContainer(node) {
+                const expression = node.expression;
+                if (!expression || expression.type === "JSXEmptyExpression")
+                    return;
+                checkExpression(expression);
+            },
+        };
+    },
+};