@diphyx/eslint-plugin 1.0.0

package/src/rules/store-section-method.mjs

@@ -0,0 +1,53 @@
+// createStore sections must use method shorthand — model({ many }) { ... } —
+// not arrow functions or plain function expressions. Whether a section is a
+// function at all is left to store-section-function.
+
+import { FUNCTION_SECTIONS, getCreateStoreConfig, getKeyedProperties, isCreateStoreCall } from "../utils/store.mjs";
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "createStore sections must use method shorthand, not arrow functions",
+        },
+        messages: {
+            useMethod:
+                "createStore '{{section}}' must use method shorthand, e.g. {{section}}() { ... }, not an arrow function.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (!isCreateStoreCall(node)) {
+                    return;
+                }
+
+                const config = getCreateStoreConfig(node);
+                if (!config) {
+                    return;
+                }
+
+                for (const property of getKeyedProperties(config)) {
+                    if (!FUNCTION_SECTIONS.has(property.key.name)) {
+                        continue;
+                    }
+
+                    // property.method is only true for method shorthand. Arrow functions
+                    // and `model: function () {}` are functions but not shorthand.
+                    const value = property.value;
+                    const isFunction = value.type === "ArrowFunctionExpression" || value.type === "FunctionExpression";
+                    if (isFunction && !property.method) {
+                        context.report({
+                            node: property.key,
+                            messageId: "useMethod",
+                            data: {
+                                section: property.key.name,
+                            },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/src/rules/store-section-return-shorthand.mjs

@@ -0,0 +1,81 @@
+// createStore sections must return a shorthand object of named consts —
+// `const list = many(shape); return { list };` — rather than returning inline
+// expressions like `return { list: many(shape) }`.
+
+import { FUNCTION_SECTIONS, getCreateStoreConfig, getKeyedProperties, isCreateStoreCall } from "../utils/store.mjs";
+
+// The object(s) a section function returns: an arrow concise body, or the
+// top-level `return { ... }` statements of a block body (returns nested inside
+// inner functions/branches are left alone).
+function getReturnedObjects(fn) {
+    const body = fn.body;
+
+    if (body.type === "ObjectExpression") {
+        return [body];
+    }
+
+    if (body.type !== "BlockStatement") {
+        return [];
+    }
+
+    return body.body
+        .filter((statement) => statement.type === "ReturnStatement")
+        .map((statement) => statement.argument)
+        .filter((argument) => argument && argument.type === "ObjectExpression");
+}
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "createStore sections must return a shorthand object of named consts",
+        },
+        messages: {
+            useShorthand:
+                "Assign '{{key}}' to a const and return it as a shorthand property ({ {{key}} }) from '{{section}}'.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (!isCreateStoreCall(node)) {
+                    return;
+                }
+
+                const config = getCreateStoreConfig(node);
+                if (!config) {
+                    return;
+                }
+
+                for (const property of getKeyedProperties(config)) {
+                    if (!FUNCTION_SECTIONS.has(property.key.name)) {
+                        continue;
+                    }
+
+                    const value = property.value;
+                    if (value.type !== "ArrowFunctionExpression" && value.type !== "FunctionExpression") {
+                        continue;
+                    }
+
+                    for (const returned of getReturnedObjects(value)) {
+                        for (const member of returned.properties) {
+                            if (member.type !== "Property" || member.computed || member.shorthand) {
+                                continue;
+                            }
+
+                            context.report({
+                                node: member,
+                                messageId: "useShorthand",
+                                data: {
+                                    section: property.key.name,
+                                    key: member.key.type === "Identifier" ? member.key.name : "value",
+                                },
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};

package/src/rules/store-shape-suffix.mjs

@@ -0,0 +1,37 @@
+// shape() result must be named with a 'Shape' suffix, e.g.
+//   export const collectionShape = shape(collectionSchema)
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "shape() result must use a 'Shape' suffix",
+        },
+        messages: {
+            invalidName: "shape() assigned to '{{name}}' should use a 'Shape' suffix (e.g. collectionShape).",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            VariableDeclarator(node) {
+                if (
+                    node.init &&
+                    node.init.type === "CallExpression" &&
+                    node.init.callee.type === "Identifier" &&
+                    node.init.callee.name === "shape" &&
+                    node.id.type === "Identifier" &&
+                    !/Shape$/.test(node.id.name)
+                ) {
+                    context.report({
+                        node: node.id,
+                        messageId: "invalidName",
+                        data: {
+                            name: node.id.name,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/store-suffix.mjs

@@ -0,0 +1,39 @@
+// A store assigned from createStore must use a `Store` suffix.
+
+import { isCreateStoreCall } from "../utils/store.mjs";
+
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "store assigned from createStore must use a 'Store' suffix",
+        },
+        messages: {
+            invalidName: "Store assigned to '{{name}}' should use a 'Store' suffix (e.g. accountStore).",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (!isCreateStoreCall(node)) {
+                    return;
+                }
+
+                // const accountStore = createStore({ ... })
+                const parent = node.parent;
+                if (parent && parent.type === "VariableDeclarator" && parent.id.type === "Identifier") {
+                    if (!/Store$/.test(parent.id.name)) {
+                        context.report({
+                            node: parent.id,
+                            messageId: "invalidName",
+                            data: {
+                                name: parent.id.name,
+                            },
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/src/rules/template-text.mjs

@@ -0,0 +1,80 @@
+// Bare template text should be wrapped in an HTML tag.
+
+import { defineTemplateRule } from "../utils/vue.mjs";
+
+const TEXT_ELEMENTS = new Set([
+    "span",
+    "p",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "a",
+    "li",
+    "td",
+    "th",
+    "dt",
+    "dd",
+    "label",
+    "legend",
+    "caption",
+    "figcaption",
+    "summary",
+    "em",
+    "strong",
+    "b",
+    "i",
+    "u",
+    "s",
+    "small",
+    "mark",
+    "q",
+    "cite",
+    "dfn",
+    "abbr",
+    "time",
+    "code",
+    "pre",
+    "blockquote",
+]);
+
+const TEXT_PATTERN = /^[A-Za-z][A-Za-z .,]*$/;
+
+export default defineTemplateRule(
+    {
+        type: "suggestion",
+        docs: {
+            description: "text content should be wrapped in an HTML tag",
+        },
+        messages: {
+            wrapText: "Text content '{{text}}' should be wrapped in an HTML tag like <span>.",
+        },
+        schema: [],
+    },
+    (context) => ({
+        VText(node) {
+            const value = node.value.trim();
+            if (value.length <= 1) {
+                return;
+            }
+
+            if (!TEXT_PATTERN.test(value)) {
+                return;
+            }
+
+            const isWrapped = node.parent.type === "VElement" && TEXT_ELEMENTS.has(node.parent.name);
+            if (isWrapped) {
+                return;
+            }
+
+            const label = value.length > 40 ? value.substring(0, 40) + "..." : value;
+            context.report({
+                node,
+                messageId: "wrapText",
+                data: { text: label },
+            });
+        },
+    }),
+);

package/src/rules/template-v-else.mjs

@@ -0,0 +1,8 @@
+// `v-else` / `v-else-if` must live on a <template> wrapper.
+
+import { createDirectiveWrapperRule } from "../utils/vue.mjs";
+
+export default createDirectiveWrapperRule({
+    directives: ["else-if", "else"],
+    label: "v-else / v-else-if",
+});

package/src/rules/template-v-for.mjs

@@ -0,0 +1,8 @@
+// `v-for` must live on a <template> wrapper.
+
+import { createDirectiveWrapperRule } from "../utils/vue.mjs";
+
+export default createDirectiveWrapperRule({
+    directives: ["for"],
+    label: "v-for",
+});

package/src/rules/template-v-if.mjs

@@ -0,0 +1,8 @@
+// `v-if` must live on a <template> wrapper.
+
+import { createDirectiveWrapperRule } from "../utils/vue.mjs";
+
+export default createDirectiveWrapperRule({
+    directives: ["if"],
+    label: "v-if",
+});

package/src/rules/vueuse-prefer-clipboard.mjs

@@ -0,0 +1,29 @@
+// Prefer VueUse useClipboard over navigator.clipboard.
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer VueUse useClipboard over navigator.clipboard",
+        },
+        messages: {
+            preferClipboard: "Use VueUse 'useClipboard()' instead of navigator.clipboard.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            MemberExpression(node) {
+                if (
+                    !node.computed &&
+                    node.object.type === "Identifier" &&
+                    node.object.name === "navigator" &&
+                    node.property.type === "Identifier" &&
+                    node.property.name === "clipboard"
+                ) {
+                    context.report({ node, messageId: "preferClipboard" });
+                }
+            },
+        };
+    },
+};

package/src/rules/vueuse-prefer-member-call.mjs

@@ -0,0 +1,39 @@
+// Prefer VueUse composables over raw DOM/window method calls.
+
+// `<any>.<method>(...)`
+const MEMBER_CALLS = {
+    addEventListener: "useEventListener",
+    matchMedia: "useMediaQuery",
+};
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer VueUse composables over raw DOM/window method calls",
+        },
+        messages: {
+            preferMemberCall: "Use VueUse '{{helper}}()' instead of '{{native}}()' for auto-cleanup.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== "MemberExpression" || callee.computed || callee.property.type !== "Identifier") {
+                    return;
+                }
+
+                const helper = MEMBER_CALLS[callee.property.name];
+                if (helper) {
+                    context.report({
+                        node: callee.property,
+                        messageId: "preferMemberCall",
+                        data: { helper, native: callee.property.name },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/vueuse-prefer-observer.mjs

@@ -0,0 +1,34 @@
+// Prefer VueUse observer composables over raw observers.
+
+// `new <Observer>(...)`
+const CONSTRUCTORS = {
+    ResizeObserver: "useResizeObserver",
+    IntersectionObserver: "useIntersectionObserver",
+    MutationObserver: "useMutationObserver",
+};
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer VueUse observer composables over raw observers",
+        },
+        messages: {
+            preferObserver: "Use VueUse '{{helper}}()' instead of 'new {{native}}()' for auto-cleanup.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            NewExpression(node) {
+                if (node.callee.type === "Identifier" && CONSTRUCTORS[node.callee.name]) {
+                    context.report({
+                        node: node.callee,
+                        messageId: "preferObserver",
+                        data: { helper: CONSTRUCTORS[node.callee.name], native: node.callee.name },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/vueuse-prefer-route.mjs

@@ -0,0 +1,64 @@
+// Prefer VueUse route composables (useRouteQuery / useRouteParams / useRouteHash)
+// over reading query / params / hash from a raw useRoute() result. Other route
+// properties (name, path, meta, ...) have no VueUse equivalent and are left alone.
+
+// route property → VueUse composable
+const ROUTE_PROPERTIES = {
+    query: "useRouteQuery",
+    params: "useRouteParams",
+    hash: "useRouteHash",
+};
+
+function isUseRouteCall(node) {
+    return node.type === "CallExpression" && node.callee.type === "Identifier" && node.callee.name === "useRoute";
+}
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer VueUse route composables over raw useRoute() query/params/hash access",
+        },
+        messages: {
+            preferRoute: "Use VueUse '{{helper}}()' instead of reading '{{property}}' from useRoute().",
+        },
+        schema: [],
+    },
+    create(context) {
+        // Names bound to a useRoute() result, e.g. `const route = useRoute()`.
+        const routeBindings = new Set();
+
+        return {
+            VariableDeclarator(node) {
+                if (node.init && isUseRouteCall(node.init) && node.id.type === "Identifier") {
+                    routeBindings.add(node.id.name);
+                }
+            },
+            MemberExpression(node) {
+                if (node.computed || node.property.type !== "Identifier") {
+                    return;
+                }
+
+                const helper = ROUTE_PROPERTIES[node.property.name];
+                if (!helper) {
+                    return;
+                }
+
+                // useRoute().query  |  const route = useRoute(); route.query
+                const object = node.object;
+                const fromRoute =
+                    isUseRouteCall(object) || (object.type === "Identifier" && routeBindings.has(object.name));
+                if (fromRoute) {
+                    context.report({
+                        node,
+                        messageId: "preferRoute",
+                        data: {
+                            helper,
+                            property: node.property.name,
+                        },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/vueuse-prefer-storage.mjs

@@ -0,0 +1,44 @@
+// Prefer VueUse useLocalStorage/useSessionStorage over raw Web Storage.
+
+// Bare/qualified identifier access, e.g. localStorage / window.localStorage
+const MEMBER_ACCESS = {
+    localStorage: "useLocalStorage",
+    sessionStorage: "useSessionStorage",
+};
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer VueUse useLocalStorage/useSessionStorage over raw Web Storage",
+        },
+        messages: {
+            preferStorage: "Use VueUse '{{helper}}()' instead of accessing {{native}} directly.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            MemberExpression(node) {
+                // localStorage.getItem(...)
+                if (node.object.type === "Identifier" && MEMBER_ACCESS[node.object.name]) {
+                    context.report({
+                        node: node.object,
+                        messageId: "preferStorage",
+                        data: { helper: MEMBER_ACCESS[node.object.name], native: node.object.name },
+                    });
+                    return;
+                }
+
+                // window.localStorage / globalThis.sessionStorage
+                if (!node.computed && node.property.type === "Identifier" && MEMBER_ACCESS[node.property.name]) {
+                    context.report({
+                        node: node.property,
+                        messageId: "preferStorage",
+                        data: { helper: MEMBER_ACCESS[node.property.name], native: node.property.name },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/rules/vueuse-prefer-timer.mjs

@@ -0,0 +1,32 @@
+// Prefer VueUse timer composables over native timers.
+
+// `<global>(...)`
+const GLOBAL_CALLS = {
+    setInterval: "useIntervalFn",
+};
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer VueUse timer composables over native timers",
+        },
+        messages: {
+            preferTimer: "Use VueUse '{{helper}}()' instead of '{{native}}()' for auto-cleanup.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (node.callee.type === "Identifier" && GLOBAL_CALLS[node.callee.name]) {
+                    context.report({
+                        node: node.callee,
+                        messageId: "preferTimer",
+                        data: { helper: GLOBAL_CALLS[node.callee.name], native: node.callee.name },
+                    });
+                }
+            },
+        };
+    },
+};

package/src/utils/ast.mjs

@@ -0,0 +1,24 @@
+// Generic AST helpers shared across rules.
+
+// `<Object>.<prop>` for a non-computed static member expression → "Object.prop",
+// otherwise null.
+export function staticMemberName(node) {
+    if (!node || node.type !== "MemberExpression" || node.computed) {
+        return null;
+    }
+
+    if (node.object.type !== "Identifier" || node.property.type !== "Identifier") {
+        return null;
+    }
+
+    return `${node.object.name}.${node.property.name}`;
+}
+
+// Callee name for `foo(...)` where the callee is a bare identifier, otherwise null.
+export function getCallName(node) {
+    if (node && node.type === "CallExpression" && node.callee.type === "Identifier") {
+        return node.callee.name;
+    }
+
+    return null;
+}

package/src/utils/docs.mjs

@@ -0,0 +1,8 @@
+// Builds the `meta.docs.url` for a rule from its name. Kept in one place so the
+// URL scheme matches the docs/rules/<name>.md layout.
+
+const DOCS_BASE = "https://github.com/diphyx/eslint-plugin/blob/main/docs/rules";
+
+export function docsUrl(name) {
+    return `${DOCS_BASE}/${name}.md`;
+}

package/src/utils/store.mjs

@@ -0,0 +1,66 @@
+// Helpers for the Harlemify createStore rules.
+//
+// Grounded in harlemify's StoreConfig (src/runtime/core/types/store.ts):
+//   { name: string; model: fn; view: fn; action: fn; compose?: fn; lazy?: boolean }
+// name/model/view/action are required; model/view/action/compose are factory functions.
+
+export const SECTION_ORDER = ["name", "model", "view", "action", "compose", "lazy"];
+
+export const ALLOWED_KEYS = new Set(SECTION_ORDER);
+
+export const FUNCTION_SECTIONS = new Set(["model", "view", "action", "compose"]);
+
+export function isCreateStoreCall(node) {
+    return node.callee && node.callee.type === "Identifier" && node.callee.name === "createStore";
+}
+
+export function getCreateStoreConfig(node) {
+    return node.arguments.find((argument) => argument.type === "ObjectExpression") || null;
+}
+
+export function getKeyedProperties(objectExpression) {
+    return objectExpression.properties.filter(
+        (property) => property.type === "Property" && property.key.type === "Identifier",
+    );
+}
+
+export function findProperty(objectExpression, key) {
+    return getKeyedProperties(objectExpression).find((property) => property.key.name === key) || null;
+}
+
+// Factory for "config must include <key>" rules.
+export function requireKey(key, message) {
+    return {
+        meta: {
+            type: "problem",
+            docs: {
+                description: `createStore config must include '${key}'`,
+            },
+            messages: {
+                missing: message,
+            },
+            schema: [],
+        },
+        create(context) {
+            return {
+                CallExpression(node) {
+                    if (!isCreateStoreCall(node)) {
+                        return;
+                    }
+
+                    const config = getCreateStoreConfig(node);
+                    if (!config) {
+                        return;
+                    }
+
+                    if (!findProperty(config, key)) {
+                        context.report({
+                            node,
+                            messageId: "missing",
+                        });
+                    }
+                },
+            };
+        },
+    };
+}