pasika 0.3.1 → 0.3.3

package/dist/eslint/pasika/rules/md/project-index.d.ts

@@ -0,0 +1,17 @@
+export interface DocMeta {
+    /** Absolute path on disk. */
+    filePath: string;
+    /** Path relative to docs root. */
+    doc: string;
+    fileName: string;
+    kind?: "guide" | "rule" | "reference" | "policy";
+    title: string;
+}
+/**
+ * Get all documents in the docs folder. Results are cached per docsRoot.
+ */
+export declare function getProjectDocs(docsRoot: string): DocMeta[];
+/**
+ * Try to find the docsRoot from a file path by walking up to find the docs/ directory.
+ */
+export declare function findDocsRoot(filePath: string): string | undefined;

package/dist/eslint/pasika/rules/md/project-index.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Shared project index for cross-document markdown rules.
+ * Scans the docs folder and caches document metadata.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+const KIND_BY_SUFFIX = [
+    ["-rule.md", "rule"],
+    ["-guide.md", "guide"],
+    ["-reference.md", "reference"],
+    ["-policy.md", "policy"],
+];
+function listMarkdownFiles(dir) {
+    return readdirSync(dir).flatMap((entry) => {
+        const entryPath = path.join(dir, entry);
+        if (statSync(entryPath).isDirectory()) {
+            return entry.startsWith("_") ? [] : listMarkdownFiles(entryPath);
+        }
+        return entry.endsWith(".md") ? [entryPath] : [];
+    });
+}
+function extractTitle(filePath) {
+    const content = readFileSync(filePath, "utf8");
+    const match = /^# (?<title>.+)$/m.exec(content);
+    return match?.groups?.title?.trim() ?? "";
+}
+// Memoized cache keyed by docsRoot
+const cache = new Map();
+/**
+ * Get all documents in the docs folder. Results are cached per docsRoot.
+ */
+export function getProjectDocs(docsRoot) {
+    const cached = cache.get(docsRoot);
+    if (cached)
+        return cached;
+    const files = listMarkdownFiles(docsRoot);
+    const docs = files
+        .sort((a, b) => a.localeCompare(b))
+        .map((filePath) => {
+        const fileName = path.basename(filePath);
+        const kind = KIND_BY_SUFFIX.find(([suffix]) => fileName.endsWith(suffix))?.[1];
+        return {
+            filePath,
+            doc: path.relative(docsRoot, filePath).split(path.sep).join("/"),
+            fileName,
+            kind,
+            title: extractTitle(filePath),
+        };
+    });
+    cache.set(docsRoot, docs);
+    return docs;
+}
+/**
+ * Try to find the docsRoot from a file path by walking up to find the docs/ directory.
+ */
+export function findDocsRoot(filePath) {
+    let dir = path.dirname(filePath);
+    for (;;) {
+        if (path.basename(dir) === "docs" && statSync(dir).isDirectory()) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}

package/dist/eslint/pasika/rules/md/reference-block-headings.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Reference block headings rule.
+ * A Reference with a single lookup block must not add a section heading for it.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const referenceBlockHeadingsRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/reference-block-headings.js

@@ -0,0 +1,31 @@
+import { getFilename } from "./helpers.js";
+export const referenceBlockHeadingsRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Reference block headings rule.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-reference.md"))
+                    return;
+                const sectionHeadings = [];
+                for (const child of node.children) {
+                    if (child.type === "heading" && child.depth >= 2) {
+                        sectionHeadings.push(child);
+                    }
+                }
+                if (sectionHeadings.length === 1) {
+                    context.report({
+                        node: node.children[0] ?? node,
+                        message: "reference has exactly one section heading, so either a single block is headed or a first block is not",
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/reference-no-rfc-vocabulary.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Reference documents must not use RFC 2119 vocabulary in prose.
+ * Only naming a keyword in code spans is permitted.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const referenceNoRfcVocabularyRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/reference-no-rfc-vocabulary.js

@@ -0,0 +1,26 @@
+import { containsRfcKeyword, getFilename } from "./helpers.js";
+export const referenceNoRfcVocabularyRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Reference documents must not use RFC 2119 vocabulary (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY) in prose.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            text(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-reference.md"))
+                    return;
+                const keyword = containsRfcKeyword(node.value);
+                if (keyword) {
+                    context.report({
+                        node,
+                        message: `reference uses RFC 2119 vocabulary: ${keyword}`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/requirement-present.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Rule and policy documents must state at least one requirement.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const requirementPresentRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/requirement-present.js

@@ -0,0 +1,41 @@
+import { containsRfcKeyword, getFilename, getTextContent } from "./helpers.js";
+/** Check whether a subtree contains a bullet with RFC vocabulary. */
+function hasRequirement(node) {
+    if (node.type === "listItem") {
+        if (containsRfcKeyword(getTextContent(node)))
+            return true;
+    }
+    if ("children" in node) {
+        for (const child of node.children) {
+            if (hasRequirement(child))
+                return true;
+        }
+    }
+    return false;
+}
+export const requirementPresentRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Rule and policy documents must state at least one requirement.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-rule.md") && !filename.endsWith("-policy.md")) {
+                    return;
+                }
+                if (!hasRequirement(node)) {
+                    const kind = filename.endsWith("-rule.md") ? "rule" : "policy";
+                    context.report({
+                        node,
+                        message: `${kind} document states no requirement`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/rfc-only-in-bullets.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview RFC 2119 vocabulary must appear only in bullet points.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const rfcOnlyInBulletsRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/rfc-only-in-bullets.js

@@ -0,0 +1,46 @@
+import { containsRfcKeyword, getFilename } from "./helpers.js";
+/** Check whether a subtree contains a text node outside a bullet using RFC vocabulary. */
+function checkOutsideBullets(node, context, insideBullet) {
+    if (node.type === "listItem") {
+        // Everything under a list item is a bullet; stop descending for the
+        // outside-bullet check, but nested lists still need walking.
+        for (const child of node.children) {
+            checkOutsideBullets(child, context, true);
+        }
+        return;
+    }
+    if (node.type === "text") {
+        const keyword = containsRfcKeyword(node.value);
+        if (keyword && !insideBullet) {
+            context.report({
+                node,
+                message: `RFC 2119 vocabulary "${keyword}" appears outside a bullet point`,
+            });
+        }
+        return;
+    }
+    if ("children" in node) {
+        for (const child of node.children) {
+            checkOutsideBullets(child, context, insideBullet);
+        }
+    }
+}
+export const rfcOnlyInBulletsRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "RFC 2119 vocabulary must appear only in bullet points.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-rule.md"))
+                    return;
+                checkOutsideBullets(node, context, false);
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/rule-paired-examples.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Rule must have paired Incorrect/Correct examples.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const rulePairedExamplesRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/rule-paired-examples.js

@@ -0,0 +1,36 @@
+import { getFilename, getLine, getTextContent } from "./helpers.js";
+export const rulePairedExamplesRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Rule must have paired Incorrect/Correct examples.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-rule.md"))
+                    return;
+                const exampleHeadings = [];
+                for (const child of node.children) {
+                    if (child.type === "heading" && child.depth === 2) {
+                        const text = getTextContent(child).trim();
+                        if (/^(?:Incorrect|Correct)\b/.test(text)) {
+                            exampleHeadings.push({ line: getLine(child), text });
+                        }
+                    }
+                }
+                const incorrect = exampleHeadings.filter((h) => h.text.startsWith("Incorrect"));
+                const correct = exampleHeadings.filter((h) => h.text.startsWith("Correct"));
+                if (incorrect.length === 0 || incorrect.length !== correct.length) {
+                    context.report({
+                        node,
+                        message: `${String(incorrect.length)} Incorrect and ${String(correct.length)} Correct examples`,
+                    });
+                }
+            },
+        };
+    },
+};

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

@@ -0,0 +1,11 @@
+/**
+ * Shared RuleTester wiring for the markdown 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 mdRuleTester: RuleTester;
+export { describe };

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

@@ -0,0 +1,21 @@
+/**
+ * Shared RuleTester wiring for the markdown 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 markdown from "@eslint/markdown";
+import { mdRules } from "../../index.js";
+RuleTester.describe = describe;
+RuleTester.it = it;
+export const mdRuleTester = new RuleTester({
+    language: "markdown/gfm",
+    plugins: {
+        markdown,
+        pasika: { rules: mdRules },
+    },
+});
+export { describe };

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

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

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;