pasika 0.3.0 → 0.3.2

package/dist/eslint/pasika/rules/md/no-nested-how-to.js

@@ -0,0 +1,39 @@
+import { getFilename, getLine, getTextContent } from "./helpers.js";
+export const noNestedHowToRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "How To sections must not nest inside other How To sections.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-guide.md"))
+                    return;
+                const howToHeadings = [];
+                for (const child of node.children) {
+                    if (child.type !== "heading")
+                        continue;
+                    const text = getTextContent(child).trim();
+                    if (!/^How To\b/.test(text))
+                        continue;
+                    howToHeadings.push({ line: getLine(child), depth: child.depth, text });
+                }
+                // A How To heading at greater depth than the previous How To heading nests inside it.
+                for (let i = 1; i < howToHeadings.length; i++) {
+                    const prev = howToHeadings[i - 1];
+                    const current = howToHeadings[i];
+                    if (prev && current && current.depth > prev.depth) {
+                        context.report({
+                            node,
+                            message: `How To section "${current.text}" nests inside another How To section`,
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/no-template-prompt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview No leftover bracketed template prompts.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const noTemplatePromptRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/no-template-prompt.js

@@ -0,0 +1,22 @@
+const TEMPLATE_PROMPT = /^\s*\[[A-Z0-9].*\]\s*$/;
+export const noTemplatePromptRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "No leftover bracketed template prompts.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            text(node) {
+                if (TEMPLATE_PROMPT.test(node.value)) {
+                    context.report({
+                        node,
+                        message: "leftover bracketed template prompt",
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/overview-length.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Overview must contain at most two sentences.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const overviewLengthRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/overview-length.js

@@ -0,0 +1,47 @@
+import { getFilename, getLine, getTextContent } from "./helpers.js";
+function countSentences(text) {
+    return text.split(/[.!?](?:\s+|$)/).filter((part) => part.trim() !== "").length;
+}
+export const overviewLengthRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Overview must contain at most two sentences.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith(".md"))
+                    return;
+                let titleLine = 0;
+                for (const child of node.children) {
+                    if (child.type === "heading" && child.depth === 1) {
+                        titleLine = getLine(child);
+                        break;
+                    }
+                }
+                if (!titleLine)
+                    return;
+                // Check only the first content paragraph after the title (the overview).
+                for (const child of node.children) {
+                    if (child.type !== "paragraph" || getLine(child) <= titleLine)
+                        continue;
+                    const text = getTextContent(child).trim();
+                    if (!text || text.startsWith("#"))
+                        continue;
+                    const sentenceCount = countSentences(text);
+                    if (sentenceCount > 2) {
+                        context.report({
+                            node: child,
+                            message: `overview uses ${String(sentenceCount)} sentences, at most two are allowed`,
+                        });
+                    }
+                    break;
+                }
+            },
+        };
+    },
+};

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

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Overview must follow the title in a documentation file.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const overviewPresentRule: MarkdownRuleDefinition;

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

@@ -0,0 +1,41 @@
+import { getFilename, getLine, getTextContent } from "./helpers.js";
+export const overviewPresentRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Overview must follow the title in a documentation file.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith(".md"))
+                    return;
+                let titleLine = 0;
+                for (const child of node.children) {
+                    if (child.type === "heading" && child.depth === 1) {
+                        titleLine = getLine(child);
+                        break;
+                    }
+                }
+                if (!titleLine)
+                    return;
+                let hasOverview = false;
+                for (const child of node.children) {
+                    if (child.type === "paragraph" && getLine(child) > titleLine && getTextContent(child).trim()) {
+                        hasOverview = true;
+                        break;
+                    }
+                }
+                if (!hasOverview) {
+                    context.report({
+                        node,
+                        message: "no overview follows the title",
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/policy-no-examples.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Policy document must not contain Incorrect/Correct examples.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const policyNoExamplesRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/policy-no-examples.js

@@ -0,0 +1,28 @@
+import { getFilename, getTextContent } from "./helpers.js";
+export const policyNoExamplesRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Policy document must not contain Incorrect/Correct examples.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            heading(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-policy.md"))
+                    return;
+                if (node.depth !== 2)
+                    return;
+                const text = getTextContent(node).trim();
+                if (/^(?:Incorrect|Correct)\b/.test(text)) {
+                    context.report({
+                        node,
+                        message: `policy document contains an example: ${text}`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/policy-single-document.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview A repository must not have more than one Policy document.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const policySingleDocumentRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/policy-single-document.js

@@ -0,0 +1,34 @@
+import { getFilename } from "./helpers.js";
+import { findDocsRoot, getProjectDocs } from "./project-index.js";
+export const policySingleDocumentRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "A repository must not have more than one Policy document.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-policy.md"))
+                    return;
+                const docsRoot = findDocsRoot(filename);
+                if (!docsRoot)
+                    return;
+                const docs = getProjectDocs(docsRoot);
+                const policyDocs = docs.filter((d) => d.kind === "policy");
+                if (policyDocs.length > 1) {
+                    // Only report on the first policy doc, so the issue is reported once.
+                    if (policyDocs[0]?.filePath === filename) {
+                        context.report({
+                            node,
+                            message: `${String(policyDocs.length)} policy documents exist`,
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/policy-subject-headings.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Policy document must group its bullets under a heading per subject.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const policySubjectHeadingsRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/policy-subject-headings.js

@@ -0,0 +1,58 @@
+import { getFilename, getLine } from "./helpers.js";
+export const policySubjectHeadingsRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Policy document must group its bullets under a heading per subject.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-policy.md"))
+                    return;
+                // Collect headings and list items with their line numbers, in document order.
+                let titleLine = 0;
+                let firstSubjectLine = 0;
+                let overviewLine = 0;
+                let foundTitle = false;
+                let foundOverview = false;
+                for (const child of node.children) {
+                    const line = getLine(child);
+                    if (!foundTitle && child.type === "heading" && child.depth === 1) {
+                        titleLine = line;
+                        foundTitle = true;
+                        continue;
+                    }
+                    if (!foundTitle)
+                        continue;
+                    if (!foundOverview && child.type === "paragraph" && line > titleLine) {
+                        overviewLine = line;
+                        foundOverview = true;
+                        continue;
+                    }
+                    if (!firstSubjectLine && child.type === "heading" && child.depth === 2 && line > titleLine) {
+                        firstSubjectLine = line;
+                    }
+                }
+                if (!titleLine || !firstSubjectLine)
+                    return;
+                // Any bullet before the first subject heading (and after the overview) is ungrouped.
+                const hasUngroupedBullet = node.children.some((child) => {
+                    if (child.type !== "list")
+                        return false;
+                    const line = getLine(child);
+                    return line > overviewLine && line < firstSubjectLine;
+                });
+                if (hasUngroupedBullet) {
+                    context.report({
+                        node,
+                        message: "policy bullet appears before the first subject heading",
+                    });
+                }
+            },
+        };
+    },
+};

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;