pasika 0.3.1 → 0.3.3

package/dist/eslint/pasika/rules/application-structure.js

@@ -0,0 +1,152 @@
+/**
+ * ESLint rule: pasika/application-structure
+ *
+ * Enforces the path-based parts of the Application Structure, Configuration,
+ * and Component Placement rules. Questions about ownership or extraction stay
+ * with the cross-file rules because they need the project graph.
+ *
+ * @see docs/code-organization-guide/rules/application-structure-rule.md
+ * @see docs/code-organization-guide/rules/configuration-rule.md
+ * @see docs/code-organization-guide/rules/component-placement-rule.md
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseModule } from "../project/parse-module.js";
+import { segmentsOf, SUPPORT_FOLDERS } from "../project/ccf.js";
+const MODULE_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+const ROUTING_FILES = new Set([
+    "default",
+    "error",
+    "instrumentation",
+    "layout",
+    "loading",
+    "middleware",
+    "not-found",
+    "page",
+    "route",
+    "template",
+]);
+const EXPECTED_SUPPORT_FOLDER = {
+    hook: "hooks",
+    type: "types",
+    schema: "schemas",
+    constant: "constants",
+    function: "utils",
+};
+function report(context, message) {
+    return {
+        Program(node) {
+            context.report({ node, loc: { line: 1, column: 0 }, message });
+        },
+    };
+}
+function isCodeFile(filename) {
+    return MODULE_EXTENSIONS.has(path.extname(filename));
+}
+function isRootSupportFolder(folder) {
+    return SUPPORT_FOLDERS.has(folder);
+}
+function exportedKinds(filename) {
+    try {
+        return new Set(parseModule(filename).exports.map((moduleExport) => moduleExport.kind));
+    }
+    catch {
+        return new Set();
+    }
+}
+function expectedSupportFolder(kinds) {
+    for (const kind of ["component", "hook", "type", "schema", "constant", "function"]) {
+        if (kinds.has(kind))
+            return EXPECTED_SUPPORT_FOLDER[kind];
+    }
+    return undefined;
+}
+function configModuleRoot(filename, sourceRoot) {
+    const segments = segmentsOf(filename, sourceRoot);
+    if (segments[0] !== "config" || segments.length < 3)
+        return undefined;
+    return path.join(sourceRoot, "config", segments[1] ?? "");
+}
+export const applicationStructureRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Enforce the repository's application, configuration, and support-folder structure.",
+        },
+    },
+    create(context) {
+        const filename = path.resolve(context.filename);
+        const sourceRoot = path.resolve("src");
+        const segments = segmentsOf(filename, sourceRoot);
+        if (segments.length === 0)
+            return {};
+        const [topLevel, secondLevel] = segments;
+        if (topLevel === undefined)
+            return {};
+        if (segments.length > 1 &&
+            topLevel !== "app" &&
+            topLevel !== "compositions" &&
+            topLevel !== "features" &&
+            topLevel !== "shared" &&
+            topLevel !== "config" &&
+            topLevel !== "locales" &&
+            !isRootSupportFolder(topLevel)) {
+            return report(context, `Move this source file under an allowed src/ folder; "src/${topLevel}/" is not part of the application structure.`);
+        }
+        if (topLevel === "features" && segments.length >= 2 && secondLevel !== undefined) {
+            if (SUPPORT_FOLDERS.has(secondLevel)) {
+                return report(context, `Move this support folder inside a feature folder; "src/features/${secondLevel}/" does not belong to a feature.`);
+            }
+            if (segments.length === 2) {
+                return report(context, "src/features/ must contain only feature folders, not source files.");
+            }
+        }
+        if (topLevel === "config") {
+            if (segments.length === 2) {
+                return report(context, "A configuration module must be a src/config/<config-name>/ folder with index.ts as its entry point.");
+            }
+            const moduleRoot = configModuleRoot(filename, sourceRoot);
+            if (moduleRoot && !fs.existsSync(path.join(moduleRoot, "index.ts"))) {
+                return report(context, `Add src/config/${path.basename(moduleRoot)}/index.ts as the configuration module entry point.`);
+            }
+            if (moduleRoot && segments.length === 3 && path.basename(filename) !== "index.ts") {
+                const kinds = exportedKinds(filename);
+                const expected = expectedSupportFolder(kinds);
+                if (expected !== undefined) {
+                    return report(context, `Move this configuration support file into src/config/${path.basename(moduleRoot)}/${expected}/.`);
+                }
+            }
+        }
+        if (topLevel === "app" && isCodeFile(filename)) {
+            const basename = path.basename(filename, path.extname(filename));
+            const currentFolder = path.basename(path.dirname(filename));
+            if (SUPPORT_FOLDERS.has(currentFolder)) {
+                return report(context, "src/app/ may contain routing files and framework assets, but ordinary components and support files must live outside src/app/.");
+            }
+            if (!ROUTING_FILES.has(basename) && path.extname(filename) !== ".css") {
+                return report(context, "src/app/ may contain routing files and framework assets, but ordinary components and support files must live outside src/app/.");
+            }
+        }
+        const currentFolder = path.basename(path.dirname(filename));
+        const kinds = exportedKinds(filename);
+        const isConfigModuleRoot = topLevel === "config" && segments.length === 3 && path.basename(filename) === "index.ts";
+        if (isConfigModuleRoot)
+            return {};
+        if (!SUPPORT_FOLDERS.has(currentFolder)) {
+            const expected = expectedSupportFolder(kinds);
+            if (expected !== undefined && segments.length > 2) {
+                return report(context, `Move this file to a ${expected}/ folder; ${currentFolder}/ is not a recognized support folder.`);
+            }
+            return {};
+        }
+        if (kinds.has("component")) {
+            return report(context, `A support folder must not contain a component; move ${path.basename(filename)} beside ${currentFolder}/.`);
+        }
+        const expected = expectedSupportFolder(kinds);
+        if (expected !== undefined && expected !== currentFolder) {
+            return report(context, `Move this file to a ${expected}/ folder; ${currentFolder}/ is reserved for ${expected === "utils" ? "utilities" : expected}.`);
+        }
+        return {};
+    },
+};

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

@@ -0,0 +1,16 @@
+import ts from "typescript";
+export interface ComponentInfo {
+    name: string;
+    declaration: ts.FunctionDeclaration | ts.VariableDeclaration;
+    smart: boolean;
+}
+export declare function parseComponentInfo(text: string, filename: string): ComponentInfo[];
+export interface SimpleRoot {
+    tagName: string;
+    attributes: ts.JsxAttributeLike[];
+}
+export declare function findSimpleRoot(component: ComponentInfo, _text: string, _filename: string): SimpleRoot | undefined;
+export declare function getTestId(root: SimpleRoot): {
+    value?: string;
+    attribute?: ts.JsxAttribute;
+};

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

@@ -0,0 +1,145 @@
+import path from "node:path";
+import ts from "typescript";
+const isPascalCase = (name) => /^[A-Z][A-Za-z0-9]*$/.test(name);
+const isHookCallName = (name) => /^use[A-Z]/.test(name);
+function isExported(node) {
+    if (!ts.canHaveModifiers(node))
+        return false;
+    return (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+}
+function containsJsx(node) {
+    let found = false;
+    const visit = (child) => {
+        if (found)
+            return;
+        if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(child, visit);
+    };
+    ts.forEachChild(node, visit);
+    return found;
+}
+function containsSmartCall(node) {
+    let found = false;
+    const visit = (child) => {
+        if (found)
+            return;
+        if (ts.isCallExpression(child)) {
+            const expression = child.expression;
+            let name = "";
+            if (ts.isIdentifier(expression)) {
+                name = expression.text;
+            }
+            else if (ts.isPropertyAccessExpression(expression)) {
+                name = expression.name.text;
+            }
+            if (isHookCallName(name)) {
+                found = true;
+                return;
+            }
+        }
+        ts.forEachChild(child, visit);
+    };
+    ts.forEachChild(node, visit);
+    return found;
+}
+function componentFromFunction(node) {
+    const name = node.name?.text;
+    if (!name || !isPascalCase(name) || !containsJsx(node))
+        return undefined;
+    return { name, declaration: node, smart: containsSmartCall(node) };
+}
+function componentFromVariable(node) {
+    if (!ts.isIdentifier(node.name) || !isPascalCase(node.name.text))
+        return undefined;
+    const initializer = node.initializer;
+    if (!initializer || (!ts.isArrowFunction(initializer) && !ts.isFunctionExpression(initializer)))
+        return undefined;
+    if (!containsJsx(initializer))
+        return undefined;
+    return {
+        name: node.name.text,
+        declaration: node,
+        smart: containsSmartCall(initializer),
+    };
+}
+export function parseComponentInfo(text, filename) {
+    const sourceFile = ts.createSourceFile(path.resolve(filename), text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const components = [];
+    for (const statement of sourceFile.statements) {
+        if (!isExported(statement))
+            continue;
+        if (ts.isFunctionDeclaration(statement)) {
+            const component = componentFromFunction(statement);
+            if (component)
+                components.push(component);
+            continue;
+        }
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                const component = componentFromVariable(declaration);
+                if (component)
+                    components.push(component);
+            }
+        }
+    }
+    return components;
+}
+function jsxTagName(element) {
+    const tagName = ts.isJsxElement(element) ? element.openingElement.tagName : element.tagName;
+    return ts.isIdentifier(tagName) ? tagName.text : undefined;
+}
+function rootFromExpression(expression) {
+    if (ts.isJsxSelfClosingElement(expression)) {
+        const tagName = jsxTagName(expression);
+        if (!tagName?.startsWith(tagName[0]?.toLowerCase() ?? ""))
+            return undefined;
+        return { tagName, attributes: [...expression.attributes.properties] };
+    }
+    if (ts.isJsxElement(expression)) {
+        const tagName = jsxTagName(expression);
+        if (!tagName?.startsWith(tagName[0]?.toLowerCase() ?? ""))
+            return undefined;
+        return { tagName, attributes: [...expression.openingElement.attributes.properties] };
+    }
+    return undefined;
+}
+export function findSimpleRoot(component, _text, _filename) {
+    const declaration = component.declaration;
+    let body;
+    if (ts.isFunctionDeclaration(declaration))
+        body = declaration.body;
+    else if (declaration.initializer && ts.isArrowFunction(declaration.initializer))
+        body = declaration.initializer.body;
+    else if (declaration.initializer && ts.isFunctionExpression(declaration.initializer)) {
+        body = declaration.initializer.body;
+    }
+    if (!body)
+        return undefined;
+    if (!ts.isBlock(body))
+        return rootFromExpression(body);
+    const returns = [];
+    const visit = (node) => {
+        if (node !== body && (ts.isFunctionLike(node) || ts.isClassLike(node)))
+            return;
+        if (ts.isReturnStatement(node))
+            returns.push(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    if (returns.length !== 1)
+        return undefined;
+    const expression = returns[0]?.expression;
+    return expression && ts.isExpression(expression) ? rootFromExpression(expression) : undefined;
+}
+export function getTestId(root) {
+    const attribute = root.attributes.find((candidate) => ts.isJsxAttribute(candidate) && ts.isIdentifier(candidate.name) && candidate.name.text === "data-testid");
+    if (!attribute)
+        return {};
+    const value = attribute.initializer;
+    if (!value || !ts.isStringLiteral(value))
+        return { attribute };
+    return { value: value.text, attribute };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * ESLint rule: pasika/component-nesting
+ *
+ * A component MUST NOT be nested only because it has support files. Nesting is
+ * justified by exclusive child components, so a nested component folder whose
+ * only contents are the component, its index, and support folders must be
+ * flattened.
+ *
+ * @see docs/code-organization-guide/rules/folder-nesting-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const componentNestingRule: Rule.RuleModule;

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

@@ -0,0 +1,69 @@
+/**
+ * ESLint rule: pasika/component-nesting
+ *
+ * A component MUST NOT be nested only because it has support files. Nesting is
+ * justified by exclusive child components, so a nested component folder whose
+ * only contents are the component, its index, and support folders must be
+ * flattened.
+ *
+ * @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 componentNestingRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require a nested component to have exclusive child components, not only support files.",
+        },
+    },
+    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 subfolder:
+        // src/features/<feature>/<folder>/<file>
+        if (segments.length !== 4 || 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 folder = segments.slice(0, 3);
+        // Another component file in the same folder is an exclusive child and makes
+        // the nesting real; an index barrel does not count.
+        const hasChildComponent = [...index.modules.values()].some((candidate) => {
+            if (candidate.file === file)
+                return false;
+            const candidateSegments = segmentsOf(candidate.file, sourceRoot);
+            if (candidateSegments.length !== 4)
+                return false;
+            if (candidateSegments[0] !== folder[0] ||
+                candidateSegments[1] !== folder[1] ||
+                candidateSegments[2] !== folder[2]) {
+                return false;
+            }
+            if (candidateSegments[3]?.startsWith("index."))
+                return false;
+            return candidate.exports.some((exp) => exp.kind === "component");
+        });
+        if (hasChildComponent)
+            return {};
+        const flatFolder = segments.slice(0, 2).join("/");
+        return {
+            Program(node) {
+                context.report({
+                    node,
+                    loc: { line: 1, column: 0 },
+                    message: `This component is nested in src/${folder.join("/")}/ but its folder has no exclusive ` +
+                        `child components — only support files. Flatten it back into src/${flatFolder}/. ` +
+                        "See docs/code-organization-guide/rules/folder-nesting-rule.md",
+                });
+            },
+        };
+    },
+};

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

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule: pasika/config-extraction
+ *
+ * A type, schema, or utility used only to implement one configuration module
+ * MUST be extracted even with one consumer. A configuration module is a
+ * src/config/<name>/ folder with index.ts as its entry point, so any type or
+ * schema still declared in a module file that is not a support file belongs in
+ * the module's types/ or schemas/ folder — or, once a consumer outside the
+ * module imports it, in the matching root support folder.
+ *
+ * @see docs/code-organization-guide/rules/configuration-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const configExtractionRule: Rule.RuleModule;

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

@@ -0,0 +1,74 @@
+/**
+ * ESLint rule: pasika/config-extraction
+ *
+ * A type, schema, or utility used only to implement one configuration module
+ * MUST be extracted even with one consumer. A configuration module is a
+ * src/config/<name>/ folder with index.ts as its entry point, so any type or
+ * schema still declared in a module file that is not a support file belongs in
+ * the module's types/ or schemas/ folder — or, once a consumer outside the
+ * module imports it, in the matching root support folder.
+ *
+ * @see docs/code-organization-guide/rules/configuration-rule.md
+ */
+import path from "node:path";
+import { getProjectIndex, symbolKey } from "../project/index.js";
+import { describeConsumers, segmentsOf, SUPPORT_FOLDERS } from "../project/ccf.js";
+export const configExtractionRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require config-only types and schemas to be extracted into the module's support folder.",
+        },
+    },
+    create(context) {
+        const sourceRoot = path.resolve("src");
+        const file = path.resolve(context.filename);
+        const segments = segmentsOf(file, sourceRoot);
+        // A configuration module file: src/config/<name>/<file>. Support folders are
+        // already the extraction destination, so they are not candidates.
+        if (segments.length < 3 || segments[0] !== "config")
+            return {};
+        if (SUPPORT_FOLDERS.has(segments[2] ?? ""))
+            return {};
+        const index = getProjectIndex(sourceRoot);
+        if (!index)
+            return {};
+        const module = index.modules.get(file);
+        if (!module)
+            return {};
+        const suspects = module.exports.filter((exp) => exp.kind === "type" || exp.kind === "schema");
+        if (suspects.length === 0)
+            return {};
+        const findings = [];
+        for (const exp of suspects) {
+            const consumers = [...(index.symbolConsumers.get(symbolKey(file, exp.name)) ?? [])];
+            const outsideConfig = consumers.filter((consumer) => segmentsOf(consumer, sourceRoot)[0] !== "config");
+            if (outsideConfig.length > 0) {
+                findings.push({
+                    line: exp.line,
+                    message: `${exp.kind} "${exp.name}" in a configuration module is imported by ` +
+                        `${describeConsumers(outsideConfig, sourceRoot)} outside src/config/. Move it to the ` +
+                        "matching root support folder. See docs/code-organization-guide/rules/configuration-rule.md",
+                });
+            }
+            else if (consumers.length > 0) {
+                findings.push({
+                    line: exp.line,
+                    message: `${exp.kind} "${exp.name}" is used only to implement this configuration module; ` +
+                        `extract it to the module's ${exp.kind === "schema" ? "schemas/" : "types/"} folder even with one consumer. ` +
+                        "See docs/code-organization-guide/rules/configuration-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/cross-feature-import.d.ts

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

package/dist/eslint/pasika/rules/cross-feature-import.js

@@ -0,0 +1,75 @@
+/**
+ * ESLint rule: pasika/cross-feature-import
+ *
+ * A component that imports from two or more feature folders MUST live in
+ * src/compositions/.
+ *
+ * @see docs/code-organization-guide/rules/component-placement-rule.md
+ */
+import path from "node:path";
+const FEATURES_SEGMENT = "features";
+function featureNameOf(resolvedPath, sourceRoot) {
+    const relative = path.relative(sourceRoot, resolvedPath);
+    if (relative.startsWith(".."))
+        return undefined;
+    const segments = relative.split(path.sep);
+    if (segments[0] !== FEATURES_SEGMENT || segments.length < 2)
+        return undefined;
+    return segments[1];
+}
+export const crossFeatureImportRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require non-composition files that import from two or more feature folders to live in src/compositions/.",
+        },
+    },
+    create(context) {
+        const filename = context.filename;
+        if (!filename.endsWith(".tsx") && !filename.endsWith(".jsx"))
+            return {};
+        const sourceRoot = path.resolve("src");
+        const fileRelative = path.relative(sourceRoot, filename);
+        if (fileRelative.startsWith(".."))
+            return {};
+        const fileSegments = fileRelative.split(path.sep);
+        const isInCompositions = fileSegments[0] === "compositions";
+        const isInApp = fileSegments[0] === "app";
+        const isConfig = fileSegments[0] === "config";
+        if (isInCompositions || isInApp || isConfig)
+            return {};
+        const importedFeatures = new Set();
+        let alreadyReported = false;
+        return {
+            ImportDeclaration(node) {
+                if (alreadyReported)
+                    return;
+                const source = node.source;
+                if (typeof source.value !== "string")
+                    return;
+                let resolved;
+                if (source.value.startsWith("@/")) {
+                    resolved = path.resolve(sourceRoot, source.value.slice(2));
+                }
+                else if (source.value.startsWith(".")) {
+                    resolved = path.resolve(path.dirname(filename), source.value);
+                }
+                if (!resolved)
+                    return;
+                const feature = featureNameOf(resolved, sourceRoot);
+                if (feature)
+                    importedFeatures.add(feature);
+                if (importedFeatures.size >= 2) {
+                    alreadyReported = true;
+                    const names = [...importedFeatures].sort().join(", ");
+                    context.report({
+                        node,
+                        message: `This component imports from two or more feature folders (${names}) and must live in src/compositions/. ` +
+                            "See docs/code-organization-guide/rules/component-placement-rule.md",
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/css/apply-usage.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule: pasika/apply-usage
+ *
+ * Style declarations added by the project inside global selectors MUST use
+ * @apply.
+ *
+ * @see docs/styling-guide/rules/global-stylesheet-rule.md
+ */
+import type { CSSRuleDefinition } from "@eslint/css";
+export declare const applyUsageRule: CSSRuleDefinition;

package/dist/eslint/pasika/rules/css/apply-usage.js

@@ -0,0 +1,45 @@
+/**
+ * ESLint rule: pasika/apply-usage
+ *
+ * Style declarations added by the project inside global selectors MUST use
+ * @apply.
+ *
+ * @see docs/styling-guide/rules/global-stylesheet-rule.md
+ */
+import { blockChildren } from "./helpers.js";
+export const applyUsageRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require @apply for project style declarations inside global selectors.",
+        },
+    },
+    create(context) {
+        return {
+            "StyleSheet:exit"(node) {
+                // Project style declarations inside global selectors are the ones in
+                // @layer base rules. Each rule's declarations must go through @apply,
+                // not raw CSS properties.
+                const layers = node.children.filter((child) => child.type === "Atrule" && child.name === "layer");
+                for (const layer of layers) {
+                    for (const child of blockChildren(layer)) {
+                        if (child.type !== "Rule")
+                            continue;
+                        for (const declaration of blockChildren(child)) {
+                            if (declaration.type !== "Declaration")
+                                continue;
+                            // @apply itself arrives as an Atrule, so a raw Declaration means
+                            // the project wrote a property by hand instead of applying a
+                            // utility.
+                            context.report({
+                                node: declaration,
+                                message: `Style declaration "${declaration.property}" inside a global selector must use @apply.`,
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/css/base-layer-pair.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule: pasika/base-layer-pair
+ *
+ * The global base layer MUST apply base-canvas and base-ink to the document
+ * body as the default page pair.
+ *
+ * @see docs/styling-guide/rules/global-stylesheet-rule.md
+ */
+import type { CSSRuleDefinition } from "@eslint/css";
+export declare const baseLayerPairRule: CSSRuleDefinition;