pasika 0.3.0 → 0.3.2

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

@@ -0,0 +1,30 @@
+import { getFilename, getTextContent } from "./helpers.js";
+export const exampleHeadingDescriptionRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Example headings must have an em-dash description.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            heading(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-rule.md"))
+                    return;
+                if (node.depth !== 2)
+                    return;
+                const text = getTextContent(node).trim();
+                if (!/^(?:Incorrect|Correct)\b/.test(text))
+                    return;
+                if (!/^(?:Incorrect|Correct) — .+/.test(text)) {
+                    context.report({
+                        node,
+                        message: `example heading has no em-dash description: ${text}`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/glossary-term-linking.d.ts

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

package/dist/eslint/pasika/rules/md/glossary-term-linking.js

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview A Guide whose steps use terms that a glossary Reference defines
+ * must link that Reference from its first step.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { getFilename, getTextContent } from "./helpers.js";
+import { findDocsRoot, getProjectDocs } from "./project-index.js";
+/** Extract glossary terms from a reference document. */
+function extractGlossaryTerms(filePath) {
+    const content = readFileSync(filePath, "utf8");
+    const terms = [];
+    // Look for definition-style patterns: "## Term" headings
+    const headingPattern = /^## (?<term>.+)$/gm;
+    let match;
+    while ((match = headingPattern.exec(content)) !== null) {
+        const term = match.groups?.term?.trim();
+        if (term)
+            terms.push(term);
+    }
+    return terms;
+}
+/** Collect the text of every step, and the doc links of the first step. */
+function collectSteps(node) {
+    const texts = [];
+    const firstStepLinks = [];
+    if (node.type === "list" && node.ordered) {
+        for (const item of node.children) {
+            texts.push(getTextContent(item));
+            if (firstStepLinks.length === 0) {
+                collectDocLinks(item, firstStepLinks);
+            }
+        }
+    }
+    if ("children" in node) {
+        for (const child of node.children) {
+            const nested = collectSteps(child);
+            texts.push(...nested.texts);
+            if (firstStepLinks.length === 0)
+                firstStepLinks.push(...nested.firstStepLinks);
+        }
+    }
+    return { texts, firstStepLinks };
+}
+function collectDocLinks(node, out) {
+    if (node.type === "link" && node.url.endsWith(".md"))
+        out.push(node.url);
+    if ("children" in node) {
+        for (const child of node.children)
+            collectDocLinks(child, out);
+    }
+}
+export const glossaryTermLinkingRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "A Guide whose steps use glossary terms must link that Reference from its first step.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-guide.md"))
+                    return;
+                const docsRoot = findDocsRoot(filename);
+                if (!docsRoot)
+                    return;
+                const docs = getProjectDocs(docsRoot);
+                const guideDir = path.dirname(filename);
+                // Find reference documents owned by this guide
+                const guideReferences = docs.filter((doc) => doc.kind === "reference" && path.dirname(doc.filePath) === guideDir);
+                if (guideReferences.length === 0)
+                    return;
+                // Collect glossary terms from owned references
+                const glossaryTerms = [];
+                for (const ref of guideReferences) {
+                    glossaryTerms.push(...extractGlossaryTerms(ref.filePath));
+                }
+                if (glossaryTerms.length === 0)
+                    return;
+                const { texts: stepTexts, firstStepLinks } = collectSteps(node);
+                // Check if any step uses glossary terms
+                const usedTerms = glossaryTerms.filter((term) => stepTexts.some((text) => text.includes(term)));
+                if (usedTerms.length === 0)
+                    return;
+                // Check if the first step links to any owned reference
+                const hasRefLink = firstStepLinks.some((link) => guideReferences.some((ref) => link.includes(ref.fileName)));
+                if (!hasRefLink) {
+                    context.report({
+                        node,
+                        message: `guide uses glossary terms (${usedTerms.join(", ")}) but first step does not link the reference`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/guide-folder-entry-point.d.ts

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

package/dist/eslint/pasika/rules/md/guide-folder-entry-point.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Guide folders must have an entry point.
+ */
+import path from "node:path";
+import { getFilename } from "./helpers.js";
+import { findDocsRoot, getProjectDocs } from "./project-index.js";
+export const guideFolderEntryPointRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Guide folders must have an entry point.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith(".md"))
+                    return;
+                const docsRoot = findDocsRoot(filename);
+                if (!docsRoot)
+                    return;
+                const docs = getProjectDocs(docsRoot);
+                // Find guide folders: folders that hold rules/ or references/
+                const guideFolders = new Set(docs
+                    .filter((doc) => ["rules", "references"].includes(path.basename(path.dirname(doc.filePath))))
+                    .map((doc) => path.dirname(path.dirname(doc.filePath)))
+                    // A rules/ or references/ folder directly under docs root belongs to no guide
+                    .filter((folder) => path.resolve(folder) !== path.resolve(docsRoot)));
+                // Check if current file is in a guide folder that needs an entry point
+                const currentDir = path.dirname(filename);
+                if (guideFolders.has(currentDir)) {
+                    const expectedEntryPoint = `${path.basename(currentDir)}.md`;
+                    const hasEntryPoint = docs.some((doc) => doc.kind === "guide" && path.dirname(doc.filePath) === currentDir && doc.fileName === expectedEntryPoint);
+                    if (!hasEntryPoint) {
+                        context.report({
+                            node,
+                            message: `folder holds support documents but has no ${expectedEntryPoint} entry point`,
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/guide-link-anchors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview A step that links another Guide must link directly to a How To section.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const guideLinkAnchorsRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/guide-link-anchors.js

@@ -0,0 +1,50 @@
+import { getFilename } from "./helpers.js";
+/** Visit every ordered-list item and run a check. */
+function visitSteps(node, check) {
+    if (node.type === "list" && node.ordered) {
+        for (const child of node.children)
+            check(child);
+    }
+    if ("children" in node) {
+        for (const child of node.children)
+            visitSteps(child, check);
+    }
+}
+/** Collect guide links in a subtree. */
+function collectGuideLinks(node) {
+    if (node.type === "link" && node.url.endsWith("-guide.md"))
+        return [node];
+    if ("children" in node) {
+        return node.children.flatMap(collectGuideLinks);
+    }
+    return [];
+}
+export const guideLinkAnchorsRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "A step that links another Guide must link directly to a How To section.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-guide.md"))
+                    return;
+                visitSteps(node, (item) => {
+                    for (const link of collectGuideLinks(item)) {
+                        // A guide link should have an anchor (#) pointing to a section.
+                        if (!link.url.includes("#")) {
+                            context.report({
+                                node: link,
+                                message: `guide link ${link.url} does not point to a specific section`,
+                            });
+                        }
+                    }
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/guide-overview-no-links.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Guide overview must not link to other documents.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const guideOverviewNoLinksRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/guide-overview-no-links.js

@@ -0,0 +1,51 @@
+import { getFilename, getLine, getTextContent } from "./helpers.js";
+function containsLink(node) {
+    if (node.type === "link")
+        return true;
+    if ("children" in node) {
+        return node.children.some(containsLink);
+    }
+    return false;
+}
+export const guideOverviewNoLinksRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Guide overview must not link to other documents.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-guide.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;
+                // Find 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;
+                    if (containsLink(child)) {
+                        context.report({
+                            node: child,
+                            message: "guide overview links another document",
+                        });
+                    }
+                    break;
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/guide-states-no-requirement.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Guide must not state requirements with RFC 2119 vocabulary.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const guideStatesNoRequirementRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/guide-states-no-requirement.js

@@ -0,0 +1,26 @@
+import { containsRfcKeyword, getFilename, getTextContent } from "./helpers.js";
+export const guideStatesNoRequirementRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Guide must not state requirements with RFC 2119 vocabulary.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            listItem(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-guide.md"))
+                    return;
+                const text = getTextContent(node);
+                if (containsRfcKeyword(text)) {
+                    context.report({
+                        node,
+                        message: "guide states a requirement with RFC 2119 vocabulary",
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/guide-step-single-link.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Each guide step must link at most one document total.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const guideStepSingleLinkRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/guide-step-single-link.js

@@ -0,0 +1,48 @@
+import { getFilename } from "./helpers.js";
+/** Count document links in a subtree. */
+function countDocLinks(node) {
+    if (node.type === "link" && node.url.endsWith(".md"))
+        return 1;
+    if ("children" in node) {
+        return node.children.reduce((sum, child) => sum + countDocLinks(child), 0);
+    }
+    return 0;
+}
+/** Visit every ordered-list item and run a check. */
+function visitSteps(node, check) {
+    if (node.type === "list" && node.ordered) {
+        for (const child of node.children)
+            check(child);
+    }
+    if ("children" in node) {
+        for (const child of node.children)
+            visitSteps(child, check);
+    }
+}
+export const guideStepSingleLinkRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Each guide step must link at most one document total.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            root(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-guide.md"))
+                    return;
+                visitSteps(node, (item) => {
+                    const links = countDocLinks(item);
+                    if (links > 1) {
+                        context.report({
+                            node: item,
+                            message: `step links ${String(links)} documents`,
+                        });
+                    }
+                });
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/guide-step-single-sentence.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Each guide step must be concise and use one sentence.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const guideStepSingleSentenceRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/guide-step-single-sentence.js

@@ -0,0 +1,42 @@
+import { getFilename, getTextContent } from "./helpers.js";
+function countSentences(text) {
+    return text.split(/[.!?](?:\s+|$)/).filter((part) => part.trim() !== "").length;
+}
+export const guideStepSingleSentenceRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Each guide step must be concise and use one sentence.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        // Walked list context, tracked via enter/exit so listItem can see its
+        // enclosing list without relying on a second visitor argument.
+        const listsOnPath = [];
+        return {
+            list(node) {
+                listsOnPath.push(node);
+            },
+            "list:exit"() {
+                listsOnPath.pop();
+            },
+            listItem(node) {
+                const filename = getFilename(context);
+                if (!filename.endsWith("-guide.md"))
+                    return;
+                // Steps are ordered list items.
+                if (!listsOnPath.at(-1)?.ordered)
+                    return;
+                const text = getTextContent(node).trim();
+                const sentenceCount = countSentences(text);
+                if (sentenceCount > 1) {
+                    context.report({
+                        node,
+                        message: `step uses ${String(sentenceCount)} sentences`,
+                    });
+                }
+            },
+        };
+    },
+};

package/dist/eslint/pasika/rules/md/helpers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Helpers for markdown ESLint rules operating on @eslint/markdown's AST.
+ */
+import type { Nodes } from "mdast";
+/**
+ * Check if text contains RFC 2119 vocabulary.
+ * Returns the first keyword found, or null.
+ */
+export declare function containsRfcKeyword(text: string): string | null;
+/**
+ * Get the file path being linted.
+ *
+ * Accepts the rule context structurally so any language plugin can pass it.
+ */
+export declare function getFilename(context: {
+    filename: string;
+}): string;
+/**
+ * Get the text content of an mdast node.
+ */
+export declare function getTextContent(node: Nodes): string;
+/**
+ * Get the line number from a node's position.
+ */
+export declare function getLine(node: Nodes): number;

package/dist/eslint/pasika/rules/md/helpers.js

@@ -0,0 +1,37 @@
+/**
+ * RFC 2119 keywords matched by word-boundary regex, longest first.
+ */
+const RFC_PATTERN = /\b(?<keyword>MUST NOT|MUST|SHALL NOT|SHALL|SHOULD NOT|SHOULD|MAY|RECOMMENDED|NOT RECOMMENDED|OPTIONAL|REQUIRED)\b/;
+/**
+ * Check if text contains RFC 2119 vocabulary.
+ * Returns the first keyword found, or null.
+ */
+export function containsRfcKeyword(text) {
+    const match = RFC_PATTERN.exec(text);
+    return match?.groups?.keyword ?? null;
+}
+/**
+ * Get the file path being linted.
+ *
+ * Accepts the rule context structurally so any language plugin can pass it.
+ */
+export function getFilename(context) {
+    return context.filename;
+}
+/**
+ * Get the text content of an mdast node.
+ */
+export function getTextContent(node) {
+    if ("value" in node && typeof node.value === "string")
+        return node.value;
+    if ("children" in node) {
+        return node.children.map(getTextContent).join("");
+    }
+    return "";
+}
+/**
+ * Get the line number from a node's position.
+ */
+export function getLine(node) {
+    return node.position?.start.line ?? 0;
+}

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

@@ -0,0 +1,27 @@
+export declare const mdRules: {
+    "doc-kind-suffix": import("@eslint/markdown").MarkdownRuleDefinition;
+    "title-matches-file-name": import("@eslint/markdown").MarkdownRuleDefinition;
+    "overview-present": import("@eslint/markdown").MarkdownRuleDefinition;
+    "overview-length": import("@eslint/markdown").MarkdownRuleDefinition;
+    "guide-overview-no-links": import("@eslint/markdown").MarkdownRuleDefinition;
+    "guide-step-single-sentence": import("@eslint/markdown").MarkdownRuleDefinition;
+    "guide-step-single-link": import("@eslint/markdown").MarkdownRuleDefinition;
+    "guide-states-no-requirement": import("@eslint/markdown").MarkdownRuleDefinition;
+    "requirement-present": import("@eslint/markdown").MarkdownRuleDefinition;
+    "rule-paired-examples": import("@eslint/markdown").MarkdownRuleDefinition;
+    "example-heading-description": import("@eslint/markdown").MarkdownRuleDefinition;
+    "policy-no-examples": import("@eslint/markdown").MarkdownRuleDefinition;
+    "policy-single-document": import("@eslint/markdown").MarkdownRuleDefinition;
+    "no-cross-document-link": import("@eslint/markdown").MarkdownRuleDefinition;
+    "reference-no-rfc-vocabulary": import("@eslint/markdown").MarkdownRuleDefinition;
+    "reference-block-headings": import("@eslint/markdown").MarkdownRuleDefinition;
+    "support-document-placement": import("@eslint/markdown").MarkdownRuleDefinition;
+    "no-template-prompt": import("@eslint/markdown").MarkdownRuleDefinition;
+    "guide-folder-entry-point": import("@eslint/markdown").MarkdownRuleDefinition;
+    "rfc-only-in-bullets": import("@eslint/markdown").MarkdownRuleDefinition;
+    "policy-subject-headings": import("@eslint/markdown").MarkdownRuleDefinition;
+    "guide-link-anchors": import("@eslint/markdown").MarkdownRuleDefinition;
+    "no-nested-how-to": import("@eslint/markdown").MarkdownRuleDefinition;
+    "glossary-term-linking": import("@eslint/markdown").MarkdownRuleDefinition;
+};
+export type MdRuleName = keyof typeof mdRules;

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

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview All markdown ESLint rules for documentation checks.
+ */
+import { docKindSuffixRule } from "./doc-kind-suffix.js";
+import { titleMatchesFileNameRule } from "./title-matches-file-name.js";
+import { overviewPresentRule } from "./overview-present.js";
+import { overviewLengthRule } from "./overview-length.js";
+import { guideOverviewNoLinksRule } from "./guide-overview-no-links.js";
+import { guideStepSingleSentenceRule } from "./guide-step-single-sentence.js";
+import { guideStepSingleLinkRule } from "./guide-step-single-link.js";
+import { guideStatesNoRequirementRule } from "./guide-states-no-requirement.js";
+import { requirementPresentRule } from "./requirement-present.js";
+import { rulePairedExamplesRule } from "./rule-paired-examples.js";
+import { exampleHeadingDescriptionRule } from "./example-heading-description.js";
+import { policyNoExamplesRule } from "./policy-no-examples.js";
+import { policySingleDocumentRule } from "./policy-single-document.js";
+import { noCrossDocumentLinkRule } from "./no-cross-document-link.js";
+import { referenceNoRfcVocabularyRule } from "./reference-no-rfc-vocabulary.js";
+import { referenceBlockHeadingsRule } from "./reference-block-headings.js";
+import { supportDocumentPlacementRule } from "./support-document-placement.js";
+import { noTemplatePromptRule } from "./no-template-prompt.js";
+import { guideFolderEntryPointRule } from "./guide-folder-entry-point.js";
+import { rfcOnlyInBulletsRule } from "./rfc-only-in-bullets.js";
+import { policySubjectHeadingsRule } from "./policy-subject-headings.js";
+import { guideLinkAnchorsRule } from "./guide-link-anchors.js";
+import { noNestedHowToRule } from "./no-nested-how-to.js";
+import { glossaryTermLinkingRule } from "./glossary-term-linking.js";
+export const mdRules = {
+    "doc-kind-suffix": docKindSuffixRule,
+    "title-matches-file-name": titleMatchesFileNameRule,
+    "overview-present": overviewPresentRule,
+    "overview-length": overviewLengthRule,
+    "guide-overview-no-links": guideOverviewNoLinksRule,
+    "guide-step-single-sentence": guideStepSingleSentenceRule,
+    "guide-step-single-link": guideStepSingleLinkRule,
+    "guide-states-no-requirement": guideStatesNoRequirementRule,
+    "requirement-present": requirementPresentRule,
+    "rule-paired-examples": rulePairedExamplesRule,
+    "example-heading-description": exampleHeadingDescriptionRule,
+    "policy-no-examples": policyNoExamplesRule,
+    "policy-single-document": policySingleDocumentRule,
+    "no-cross-document-link": noCrossDocumentLinkRule,
+    "reference-no-rfc-vocabulary": referenceNoRfcVocabularyRule,
+    "reference-block-headings": referenceBlockHeadingsRule,
+    "support-document-placement": supportDocumentPlacementRule,
+    "no-template-prompt": noTemplatePromptRule,
+    "guide-folder-entry-point": guideFolderEntryPointRule,
+    "rfc-only-in-bullets": rfcOnlyInBulletsRule,
+    "policy-subject-headings": policySubjectHeadingsRule,
+    "guide-link-anchors": guideLinkAnchorsRule,
+    "no-nested-how-to": noNestedHowToRule,
+    "glossary-term-linking": glossaryTermLinkingRule,
+};

package/dist/eslint/pasika/rules/md/no-cross-document-link.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview Rules, references, and policy must not link to other documents.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const noCrossDocumentLinkRule: MarkdownRuleDefinition;

package/dist/eslint/pasika/rules/md/no-cross-document-link.js

@@ -0,0 +1,36 @@
+import { getFilename } from "./helpers.js";
+/** The document kind for a filename, when the no-link rule applies to it. */
+function linkedKind(filename) {
+    if (filename.endsWith("-rule.md"))
+        return "rule";
+    if (filename.endsWith("-reference.md"))
+        return "reference";
+    if (filename.endsWith("-policy.md"))
+        return "policy";
+    return undefined;
+}
+export const noCrossDocumentLinkRule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Rules, references, and policy must not link to other documents.",
+            recommended: true,
+        },
+    },
+    create(context) {
+        return {
+            link(node) {
+                const filename = getFilename(context);
+                const kind = linkedKind(filename);
+                if (!kind)
+                    return;
+                if (node.url.endsWith(".md")) {
+                    context.report({
+                        node,
+                        message: `${kind} links another document: ${node.url}`,
+                    });
+                }
+            },
+        };
+    },
+};

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

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview How To sections must not nest inside other How To sections.
+ */
+import type { MarkdownRuleDefinition } from "@eslint/markdown";
+export declare const noNestedHowToRule: MarkdownRuleDefinition;