pasika 0.3.1 → 0.3.3

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;

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