pasika 0.3.1 → 0.3.2

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

package/dist/eslint/pasika/rules/locale-dotted-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule: pasika/locale-dotted-path
+ *
+ * A namespaced locale MUST be read through its full dotted path
+ * (locales.stream.watchLiveStream) rather than destructured.
+ *
+ * @see docs/code-organization-guide/rules/locales-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const localeDottedPathRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/locale-dotted-path.js

@@ -0,0 +1,65 @@
+/**
+ * ESLint rule: pasika/locale-dotted-path
+ *
+ * A namespaced locale MUST be read through its full dotted path
+ * (locales.stream.watchLiveStream) rather than destructured.
+ *
+ * @see docs/code-organization-guide/rules/locales-rule.md
+ */
+import path from "node:path";
+function isInLocalesDir(filename) {
+    const segments = path.resolve(filename).split(path.sep);
+    const srcIdx = segments.lastIndexOf("src");
+    return srcIdx !== -1 && segments[srcIdx + 1] === "locales";
+}
+function isLocalesAccess(node) {
+    if (node.type === "Identifier" && node.name === "locales") {
+        return true;
+    }
+    if (node.type === "MemberExpression" &&
+        node.object.type === "Identifier" &&
+        node.object.name === "locales" &&
+        node.property.type === "Identifier") {
+        return true;
+    }
+    return false;
+}
+export const localeDottedPathRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require reading namespaced locales through their full dotted path.",
+        },
+    },
+    create(context) {
+        if (isInLocalesDir(context.filename))
+            return {};
+        return {
+            VariableDeclarator(node) {
+                if (node.id.type !== "ObjectPattern")
+                    return;
+                const init = node.init;
+                if (!init || !isLocalesAccess(init))
+                    return;
+                for (const prop of node.id.properties) {
+                    if (prop.type !== "Property")
+                        continue;
+                    let valueName;
+                    if (prop.value.type === "Identifier") {
+                        valueName = prop.value.name;
+                    }
+                    else if (prop.key.type === "Identifier") {
+                        valueName = prop.key.name;
+                    }
+                    if (valueName) {
+                        context.report({
+                            node,
+                            message: `Destructuring locales.${valueName} loses the namespace; read through the full dotted path instead.`,
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/locale-placement.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ESLint rule: pasika/locale-placement
+ *
+ * Locales read by files in more than one feature folder or by src/shared/,
+ * src/compositions/, src/app/, or root support folders MUST live at the top
+ * level of locales. Locales read only by files in one feature folder MUST live
+ * in an object with the camelCase form of its feature folder name. The rule
+ * reads which keys the tree uses, because a single file cannot see them.
+ *
+ * @see docs/code-organization-guide/rules/locales-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const localePlacementRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/locale-placement.js

@@ -0,0 +1,163 @@
+/**
+ * ESLint rule: pasika/locale-placement
+ *
+ * Locales read by files in more than one feature folder or by src/shared/,
+ * src/compositions/, src/app/, or root support folders MUST live at the top
+ * level of locales. Locales read only by files in one feature folder MUST live
+ * in an object with the camelCase form of its feature folder name. The rule
+ * reads which keys the tree uses, because a single file cannot see them.
+ *
+ * @see docs/code-organization-guide/rules/locales-rule.md
+ */
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+import { getProjectIndex, resolveSpecifier } from "../project/index.js";
+import { describeConsumers, segmentsOf, SUPPORT_FOLDERS } from "../project/ccf.js";
+/** The first segment of a `locales.<key>` read. */
+const LOCALE_ACCESS = /\blocales\.(?<key>[A-Za-z_$][\w$]*)/g;
+const camelCase = (name) => name.replace(/-[a-z]/g, (match) => match.slice(1).toUpperCase());
+const FORCED_TOP_LEVEL = new Set(["app", "shared", "compositions", "config"]);
+/** A file whose own folder decides the locale scope: app/shared/compositions/config or a root support folder. */
+function forcesTopLevel(segments) {
+    return FORCED_TOP_LEVEL.has(segments[0] ?? "") || SUPPORT_FOLDERS.has(segments[0] ?? "");
+}
+/**
+ * Where each top-level key of the exported `locales` object lives: directly on
+ * the object ("top") or as a namespaced object ("nested").
+ */
+function localePlacement(text) {
+    const sourceFile = ts.createSourceFile("locales.ts", text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        const isExported = (ts.getModifiers(statement) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+        if (!isExported)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "locales")
+                continue;
+            if (!declaration.initializer || !ts.isObjectLiteralExpression(declaration.initializer))
+                continue;
+            const placement = new Map();
+            for (const property of declaration.initializer.properties) {
+                if (!ts.isPropertyAssignment(property))
+                    continue;
+                let name;
+                if (ts.isIdentifier(property.name))
+                    name = property.name.text;
+                else if (ts.isStringLiteral(property.name))
+                    name = property.name.text;
+                if (name === undefined)
+                    continue;
+                const line = sourceFile.getLineAndCharacterOfPosition(property.getStart(sourceFile)).line + 1;
+                placement.set(name, {
+                    kind: ts.isObjectLiteralExpression(property.initializer) ? "nested" : "top",
+                    line,
+                });
+            }
+            return placement;
+        }
+    }
+    return undefined;
+}
+export const localePlacementRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require shared locales at the top level and single-feature locales in a namespaced object.",
+        },
+    },
+    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 {};
+        // The named locales object lives in src/locales/index.ts; the rule reports
+        // on that file, because the fix is in the definition.
+        const localesFile = [...index.modules.keys()].find((candidate) => {
+            const candidateSegments = segmentsOf(candidate, sourceRoot);
+            return candidateSegments.length === 2 && candidateSegments[0] === "locales" && candidateSegments[1]?.startsWith("index.");
+        });
+        if (!localesFile || file !== localesFile)
+            return {};
+        const placement = localePlacement(readFileSync(localesFile, "utf8"));
+        if (!placement)
+            return {};
+        const keyReaders = new Map();
+        const keyFeatures = new Map();
+        const keyForcedTopLevel = new Set();
+        for (const [candidateFile, module] of index.modules) {
+            if (candidateFile === localesFile)
+                continue;
+            const importsLocales = module.imports.some((moduleImport) => resolveSpecifier(candidateFile, moduleImport.specifier, sourceRoot) === localesFile);
+            if (!importsLocales)
+                continue;
+            const candidateSegments = segmentsOf(candidateFile, sourceRoot);
+            for (const match of readFileSync(candidateFile, "utf8").matchAll(LOCALE_ACCESS)) {
+                const key = match.groups?.key;
+                if (key === undefined)
+                    continue;
+                const readers = keyReaders.get(key) ?? new Set();
+                readers.add(candidateFile);
+                keyReaders.set(key, readers);
+                if (candidateSegments[0] === "features" && candidateSegments.length >= 2) {
+                    const features = keyFeatures.get(key) ?? new Set();
+                    features.add(candidateSegments[1] ?? "");
+                    keyFeatures.set(key, features);
+                }
+                else if (forcesTopLevel(candidateSegments)) {
+                    keyForcedTopLevel.add(key);
+                }
+            }
+        }
+        const findings = [];
+        for (const [key, readers] of keyReaders) {
+            const features = keyFeatures.get(key) ?? new Set();
+            const shared = features.size > 1 || keyForcedTopLevel.has(key);
+            const current = placement.get(key);
+            if (shared) {
+                if (current?.kind === "nested") {
+                    findings.push({
+                        line: current.line,
+                        message: `Locale "${key}" is read by ${describeConsumers([...readers], sourceRoot)} and must live ` +
+                            "at the top level of locales. See docs/code-organization-guide/rules/locales-rule.md",
+                    });
+                }
+                continue;
+            }
+            if (features.size !== 1)
+                continue;
+            const featureName = [...features][0] ?? "";
+            const expected = camelCase(featureName);
+            if (current?.kind === "top") {
+                findings.push({
+                    line: current.line,
+                    message: `Locale "${key}" is read only by the ${featureName} feature; it must live in an object ` +
+                        `named "${expected}". See docs/code-organization-guide/rules/locales-rule.md`,
+                });
+            }
+            else if (current?.kind === "nested" && key !== expected) {
+                findings.push({
+                    line: current.line,
+                    message: `Locale "${key}" is read only by the ${featureName} feature; it must live in an object ` +
+                        `named "${expected}", not "${key}". See docs/code-organization-guide/rules/locales-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/locales-location.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ESLint rule: pasika/locales-location
+ *
+ * All locales MUST live in the named locales object exported from
+ * src/locales/index.ts. User-facing strings defined outside the locales
+ * directory are reported.
+ *
+ * @see docs/code-organization-guide/rules/locales-rule.md
+ */
+import type { Rule } from "eslint";
+export declare const localesLocationRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/locales-location.js

@@ -0,0 +1,56 @@
+/**
+ * ESLint rule: pasika/locales-location
+ *
+ * All locales MUST live in the named locales object exported from
+ * src/locales/index.ts. User-facing strings defined outside the locales
+ * directory are reported.
+ *
+ * @see docs/code-organization-guide/rules/locales-rule.md
+ */
+import path from "node:path";
+function isLocalesFile(filename) {
+    const segments = path.resolve(filename).split(path.sep);
+    const srcIdx = segments.lastIndexOf("src");
+    return srcIdx !== -1 && segments[srcIdx + 1] === "locales";
+}
+const LOCALE_NAME_RE = /^[a-z][a-zA-Z0-9]*$/;
+function looksLikeLocaleKey(name) {
+    return LOCALE_NAME_RE.test(name);
+}
+export const localesLocationRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Require all locales to live in the named locales object.",
+        },
+    },
+    create(context) {
+        if (isLocalesFile(context.filename))
+            return {};
+        const filename = context.filename;
+        const segments = path.resolve(filename).split(path.sep);
+        const srcIdx = segments.lastIndexOf("src");
+        if (srcIdx === -1)
+            return {};
+        const folder = segments[srcIdx + 1];
+        if (folder === "app" || folder === "config")
+            return {};
+        return {
+            VariableDeclarator(node) {
+                if (node.id.type === "Identifier" &&
+                    node.init?.type === "ObjectExpression" &&
+                    node.init.properties.length > 0 &&
+                    looksLikeLocaleKey(node.id.name)) {
+                    const hasStringValues = node.init.properties.some((p) => p.type === "Property" && p.value.type === "Literal");
+                    if (hasStringValues) {
+                        context.report({
+                            node,
+                            message: "User-facing strings must live in src/locales/, not inline in component files.",
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/doc-kind-suffix.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Documentation files must have a kind suffix in their filename.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const docKindSuffixRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/doc-kind-suffix.js

@@ -0,0 +1,29 @@
+import { getFilename } from "./helpers.js";
+export const docKindSuffixRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Documentation files must have a -guide, -rule, -reference, or -policy suffix.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith(".md"))
+                    return;
+                if (filename.endsWith("-guide.md") ||
+                    filename.endsWith("-rule.md") ||
+                    filename.endsWith("-reference.md") ||
+                    filename.endsWith("-policy.md")) {
+                    return;
+                }
+                context.report({
+                    node,
+                    message: "file name carries no -guide, -rule, -reference, or -policy suffix",
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/example-heading-description.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Example headings must have an em-dash description.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const exampleHeadingDescriptionRule: MarkdownRuleDefinition;