pasika 0.3.1 → 0.3.2

package/dist/eslint/pasika/rules/md/support-document-placement.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Rules must live in rules/, references must live in references/.
+ */
+import path from "node:path";
+import { getFilename } from "./helpers.js";
+export const supportDocumentPlacementRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Rules must live in rules/, references must live in references/.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith(".md"))
+                    return;
+                const parentFolder = path.basename(path.dirname(filename));
+                if (filename.endsWith("-rule.md") && parentFolder !== "rules") {
+                    context.report({
+                        node,
+                        message: `rule lives in "${parentFolder}/" instead of "rules/"`,
+                    });
+                }
+                if (filename.endsWith("-reference.md") && parentFolder !== "references") {
+                    context.report({
+                        node,
+                        message: `reference lives in "${parentFolder}/" instead of "references/"`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/title-matches-file-name.d.ts

@@ -0,0 +1,2 @@
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const titleMatchesFileNameRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/title-matches-file-name.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Document title must match the file name in kebab-case.
+ */
+import path from "node:path";
+import { getFilename, getTextContent } from "./helpers.js";
+function toExpectedFileName(title) {
+    return `${title
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")}.md`;
+}
+export const titleMatchesFileNameRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Document title must match the file name in kebab-case.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            heading(node) {
+                if (node.depth !== 1)
+                    return;
+                const filename = getFilename(context);
+                if (!filename.endsWith(".md"))
+                    return;
+                const title = getTextContent(node).trim();
+                const expectedFileName = toExpectedFileName(title);
+                const actualFileName = path.basename(filename);
+                if (!title) {
+                    context.report({
+                        node,
+                        message: "document has no `# Title` heading",
+                    });
+                }
+                else if (expectedFileName !== actualFileName) {
+                    context.report({
+                        node,
+                        message: `title "${title}" expects file name ${expectedFileName}`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/named-exports.d.ts

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

package/dist/eslint/pasika/rules/named-exports.js

@@ -0,0 +1,49 @@
+/**
+ * ESLint rule: pasika/named-exports
+ *
+ * Enforces named exports for application files while allowing framework routing
+ * files such as Next.js page.tsx and layout.tsx to use their required default
+ * export contract.
+ *
+ * @see docs/code-organization-guide/rules/exports-and-imports-rule.md
+ */
+import path from "node:path";
+const FRAMEWORK_DEFAULT_EXPORT_FILES = new Set([
+    "default",
+    "error",
+    "layout",
+    "loading",
+    "not-found",
+    "page",
+    "route",
+    "template",
+]);
+function isFrameworkDefaultExportFile(filename) {
+    const normalized = filename.replaceAll(path.sep, "/");
+    if (!normalized.includes("/src/app/"))
+        return false;
+    const basename = path.basename(filename, path.extname(filename));
+    return FRAMEWORK_DEFAULT_EXPORT_FILES.has(basename);
+}
+export const namedExportsRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require named exports except where a framework requires a default export.",
+        },
+    },
+    create(context) {
+        if (isFrameworkDefaultExportFile(context.filename))
+            return {};
+        return {
+            ExportDefaultDeclaration(node) {
+                context.report({
+                    node,
+                    message: "Files that export values must use named exports unless a framework or third-party package requires a different export style for that file. " +
+                        "See docs/code-organization-guide/rules/exports-and-imports-rule.md",
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/no-eslint-disable.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule: pasika/no-eslint-disable
+ *
+ * Code MUST NOT use eslint-disable directives, and a reported violation MUST
+ * be fixed instead.
+ *
+ * @see docs/agent-policy.md
+ */
+import type { Rule } from "eslint";
+export declare const noEslintDisableRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/no-eslint-disable.js

@@ -0,0 +1,33 @@
+/**
+ * ESLint rule: pasika/no-eslint-disable
+ *
+ * Code MUST NOT use eslint-disable directives, and a reported violation MUST
+ * be fixed instead.
+ *
+ * @see docs/agent-policy.md
+ */
+export const noEslintDisableRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Forbid eslint-disable directives.",
+        },
+    },
+    create(context) {
+        return {
+            Program() {
+                for (const comment of context.sourceCode.getAllComments()) {
+                    if (!comment.value.includes("eslint-disable"))
+                        continue;
+                    if (!comment.loc)
+                        continue;
+                    context.report({
+                        loc: comment.loc,
+                        message: "Do not use eslint-disable directives; fix the reported violation instead.",
+                    });
+                }
+            },
+        };
+    },
+};

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

@@ -5,32 +5,22 @@
  *
  * @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 === "FunctionDeclaration" && declaration.id) {
+        return declaration.id.name ?? null;
     }
-    if (declaration.type === "VariableDeclaration") {
-        const declarator = declaration.declarations[0];
-        if (declarator?.id.type === "Identifier" &&
+    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;
+            return declarator.id.name ?? null;
         }
     }
-    if (declaration.type === "ArrowFunctionExpression") {
+    if (declaration?.type === "ArrowFunctionExpression") {
         return "default";
     }
-    if (declaration.type === "FunctionExpression" && declaration.id) {
-        return declaration.id.name;
+    if (declaration?.type === "FunctionExpression" && declaration.id) {
+        return declaration.id.name ?? null;
     }
     return null;
 }
@@ -55,8 +45,6 @@ export const noMixedConcernsRule = {
         }
         return {
             ExportNamedDeclaration(node) {
-                if (!node.declaration)
-                    return;
                 const name = getExportName(node.declaration);
                 if (name)
                     registerExport(name);
@@ -81,4 +69,3 @@ export const noMixedConcernsRule = {
         };
     },
 };
-/* 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/no-util-barrel.d.ts

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

package/dist/eslint/pasika/rules/no-util-barrel.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { resolveSpecifier } from "../project/index.js";
+export const noUtilBarrelRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require utilities to be imported directly without a barrel.",
+        },
+    },
+    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 segments = target.replace(/\\/g, "/").split("/");
+                    const utilsIndex = segments.lastIndexOf("utils");
+                    if (utilsIndex < 0 || !path.basename(target).startsWith("index."))
+                        continue;
+                    context.report({
+                        node,
+                        message: `Import utilities directly instead of through "${specifier}". ` +
+                            "See docs/code-organization-guide/rules/utilities-rule.md",
+                    });
+                }
+            },
+        };
+    },
+};
+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/pure-function-extract.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 type { Rule } from "eslint";
+export declare const pureFunctionExtractRule: Rule.RuleModule;

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`,
+                });
+            },
+        };
+    },
+};