pasika 0.3.2 → 0.3.4

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

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,163 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,56 +0,0 @@
-/**
- * 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

@@ -1,5 +0,0 @@
-/**
- * @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

@@ -1,29 +0,0 @@
-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

@@ -1,5 +0,0 @@
-/**
- * @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

@@ -1,30 +0,0 @@
-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

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

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

@@ -1,99 +0,0 @@
-/**
- * @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

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

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

@@ -1,46 +0,0 @@
-/**
- * @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

@@ -1,5 +0,0 @@
-/**
- * @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

@@ -1,50 +0,0 @@
-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

@@ -1,5 +0,0 @@
-/**
- * @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

@@ -1,51 +0,0 @@
-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

@@ -1,5 +0,0 @@
-/**
- * @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

@@ -1,26 +0,0 @@
-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

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