@diphyx/eslint-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DiPhyx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @diphyx/eslint-plugin
+
+Opinionated ESLint rules and a ready-to-use flat config that capture DiPhyx's Nuxt/Vue + [Harlemify](https://github.com/diphyx/harlemify) conventions — so every DiPhyx app lints the same way from a single dependency.
+
+A stock `eslint-plugin-vue` setup checks general Vue style; this plugin adds the project-specific patterns it can't know about — where template directives belong, how `<script setup>` is ordered and written, the exact shape of a Harlemify `createStore`, composable naming, and reaching for radash / VueUse instead of hand-rolled code.
+
+## Highlights
+
+- **32 custom rules** covering SFC templates, `<script setup>` structure, Harlemify stores, composable naming, and radash / VueUse usage.
+- **One-line preset** — `configs.recommended` wires up the TypeScript + Vue parsers, the relevant `eslint-plugin-vue` rules, file-naming, and every custom rule.
+- **No extra peer deps** — the parsers and plugins ship inside this package; you only install `eslint` itself.
+- **Guidance, not gates** — every rule reports as a warning and none auto-fix, so it nudges without blocking commits.
+- **Modern toolchain** — flat config, ESLint 9+, ESM only.
+
+## Install
+
+```bash
+pnpm add -D @diphyx/eslint-plugin eslint
+```
+
+The plugin ships its own parser/plugin dependencies (`@typescript-eslint/*`, `vue-eslint-parser`, `eslint-plugin-vue`, `eslint-plugin-check-file`), so you only need `eslint` itself as a peer.
+
+## Usage
+
+`eslint.config.mjs`:
+
+```js
+import diphyx from "@diphyx/eslint-plugin";
+
+export default [
+    ...diphyx.configs.recommended,
+
+    // project-specific overrides / ignores
+    {
+        ignores: ["node_modules/**", ".nuxt/**", ".output/**", "dist/**", "**/*.d.ts"],
+    },
+];
+```
+
+### Picking rules à la carte
+
+If you don't want the preset, register the plugin and turn on rules yourself:
+
+```js
+import diphyx from "@diphyx/eslint-plugin";
+
+export default [
+    {
+        files: ["**/*.vue"],
+        plugins: { "@diphyx": diphyx },
+        rules: {
+            "@diphyx/template-v-if": "warn",
+            "@diphyx/template-text": "warn",
+        },
+    },
+];
+```
+
+## Rules
+
+All rules are report-only (warnings); none auto-fix. Each rule has its own page
+under [`docs/rules/`](./docs/rules) (also linked from the rule's `meta.docs.url`).
+
+### Template (`*.vue`)
+
+| Rule              | Enforces                                                 |
+| ----------------- | -------------------------------------------------------- |
+| `template-v-if`   | `v-if` must be on a `<template>` wrapper                 |
+| `template-v-else` | `v-else` / `v-else-if` must be on a `<template>` wrapper |
+| `template-v-for`  | `v-for` must be on a `<template>` wrapper                |
+| `template-text`   | bare text must be wrapped in an HTML tag                 |
+
+### Script (`*.vue`)
+
+| Rule                   | Enforces                                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `script-section-order` | script-setup section order: import → props → model → emit → composable → state → computed → watch → method → lifecycle → expose |
+| `script-define-object` | `define*` macros must declare their shape with a runtime object, not the type-only form                                         |
+
+### Store — Harlemify `createStore`
+
+| Rule                                                                  | Enforces                                                   |
+| --------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `store-require-name`                                                  | config has a required `name` property                      |
+| `store-require-model` / `store-require-view` / `store-require-action` | required sections are present                              |
+| `store-section-function`                                              | sections are functions                                     |
+| `store-section-method`                                                | sections use method shorthand (not arrow functions)        |
+| `store-section-return-shorthand`                                      | sections return a shorthand object of named consts         |
+| `store-config-order`                                                  | key order: name → model → view → action → compose → lazy   |
+| `store-no-unknown-key`                                                | no unknown config keys                                     |
+| `store-suffix`                                                        | store variable ends in `Store`                             |
+| `store-name-match`                                                    | `name` matches the variable (`accountStore` → `"account"`) |
+| `store-shape-suffix`                                                  | `shape()` result is named `*Shape`                         |
+| `store-mode-enum`                                                     | `mode` uses a `ModelMode` enum, not a string literal       |
+
+### Composable (`app/composables/*.ts`)
+
+| Rule                | Enforces                             |
+| ------------------- | ------------------------------------ |
+| `composable-naming` | exported composables follow `useXxx` |
+
+### Radash preferences (`*.ts`, `*.vue`)
+
+Prefer radash helpers over hand-rolled equivalents.
+
+| Rule                   | Enforces                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `radash-prefer-is`     | prefer radash `is*` helpers over `typeof` comparisons                           |
+| `radash-prefer-call`   | prefer radash helpers over native global calls (`Promise.all`, `Array.isArray`) |
+| `radash-prefer-clone`  | prefer `clone()` over `JSON.parse(JSON.stringify())`                            |
+| `radash-prefer-unique` | prefer `unique()` over spreading a `new Set()`                                  |
+| `radash-prefer-sum`    | prefer `sum()` over a `reduce` that adds values                                 |
+| `radash-prefer-sleep`  | prefer `sleep()` over wrapping `setTimeout` in a Promise                        |
+
+### VueUse preferences (`*.ts`, `*.vue`)
+
+Prefer VueUse composables (with automatic lifecycle cleanup) over raw browser APIs.
+
+| Rule                        | Enforces                                                                                             |
+| --------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `vueuse-prefer-storage`     | prefer `useLocalStorage` / `useSessionStorage` over raw Web Storage                                  |
+| `vueuse-prefer-member-call` | prefer VueUse composables over raw DOM/window method calls (`addEventListener`, `matchMedia`)        |
+| `vueuse-prefer-timer`       | prefer VueUse timer composables over native timers (`setInterval`)                                   |
+| `vueuse-prefer-observer`    | prefer VueUse observer composables over raw observers                                                |
+| `vueuse-prefer-clipboard`   | prefer `useClipboard()` over `navigator.clipboard`                                                   |
+| `vueuse-prefer-route`       | prefer `useRouteQuery` / `useRouteParams` / `useRouteHash` over `useRoute().query`/`.params`/`.hash` |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+    "name": "@diphyx/eslint-plugin",
+    "version": "1.0.0",
+    "description": "Shared ESLint plugin and flat config for DiPhyx Nuxt/Vue + Harlemify projects",
+    "license": "MIT",
+    "type": "module",
+    "exports": {
+        ".": "./src/index.mjs"
+    },
+    "files": [
+        "src"
+    ],
+    "scripts": {
+        "lint": "eslint .",
+        "format": "prettier --write .",
+        "format:check": "prettier --check ."
+    },
+    "keywords": [
+        "eslint",
+        "eslintplugin",
+        "eslint-plugin",
+        "diphyx",
+        "nuxt",
+        "vue",
+        "harlemify"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/diphyx/eslint-plugin.git"
+    },
+    "homepage": "https://github.com/diphyx/eslint-plugin#readme",
+    "bugs": {
+        "url": "https://github.com/diphyx/eslint-plugin/issues"
+    },
+    "dependencies": {
+        "@typescript-eslint/eslint-plugin": "^8.61.0",
+        "@typescript-eslint/parser": "^8.61.0",
+        "eslint-plugin-check-file": "^3.3.1",
+        "eslint-plugin-vue": "^10.9.2",
+        "vue-eslint-parser": "^10.4.1"
+    },
+    "peerDependencies": {
+        "eslint": ">=9"
+    },
+    "devDependencies": {
+        "eslint": "^10.5.0",
+        "prettier": "^3.4.2"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/configs/index.mjs

@@ -0,0 +1,11 @@
+// Ready-to-use flat config presets. `createConfigs(plugin)` is called from the
+// package entry so each preset can register the plugin under the "@diphyx"
+// namespace.
+
+import { createRecommended } from "./recommended.mjs";
+
+export function createConfigs(plugin) {
+    return {
+        recommended: createRecommended(plugin),
+    };
+}

package/src/configs/recommended.mjs

@@ -0,0 +1,184 @@
+// The `recommended` flat-config preset: wires the TypeScript and Vue parsers,
+// the relevant eslint-plugin-vue rules, file-naming, and every custom rule.
+// `createRecommended(plugin)` takes the plugin so the preset can register it
+// under the "@diphyx" namespace.
+
+import tsParser from "@typescript-eslint/parser";
+import vueParser from "vue-eslint-parser";
+
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+import vuePlugin from "eslint-plugin-vue";
+import checkFilePlugin from "eslint-plugin-check-file";
+
+const namingConvention = [
+    "warn",
+    {
+        selector: "enum",
+        format: ["PascalCase"],
+    },
+    {
+        selector: "enumMember",
+        format: ["UPPER_CASE"],
+    },
+    {
+        selector: "typeAlias",
+        format: ["PascalCase"],
+    },
+    {
+        selector: "interface",
+        format: ["PascalCase"],
+    },
+];
+
+export function createRecommended(plugin) {
+    return [
+        // TypeScript files
+        {
+            files: ["**/*.ts"],
+            languageOptions: {
+                parser: tsParser,
+                parserOptions: {
+                    ecmaVersion: "latest",
+                    sourceType: "module",
+                },
+            },
+            plugins: {
+                "@typescript-eslint": tsPlugin,
+            },
+            rules: {
+                "no-unused-vars": "off",
+                "no-undef": "off",
+                "@typescript-eslint/naming-convention": namingConvention,
+                "arrow-body-style": ["warn", "always"],
+            },
+        },
+
+        // Vue files
+        {
+            files: ["**/*.vue"],
+            languageOptions: {
+                parser: vueParser,
+                parserOptions: {
+                    parser: tsParser,
+                    ecmaVersion: "latest",
+                    sourceType: "module",
+                    extraFileExtensions: [".vue"],
+                },
+            },
+            plugins: {
+                vue: vuePlugin,
+                "@typescript-eslint": tsPlugin,
+                "@diphyx": plugin,
+            },
+            rules: {
+                "no-unused-vars": "off",
+                "no-undef": "off",
+                "@typescript-eslint/naming-convention": namingConvention,
+                "arrow-body-style": ["warn", "always"],
+
+                // Vue rules
+                "vue/block-lang": ["warn", { script: { lang: "ts" } }],
+                "vue/component-api-style": ["warn", ["script-setup"]],
+                "vue/define-macros-order": "off",
+                "vue/attributes-order": [
+                    "warn",
+                    {
+                        order: [
+                            "DEFINITION",
+                            "LIST_RENDERING",
+                            "CONDITIONALS",
+                            "RENDER_MODIFIERS",
+                            "GLOBAL",
+                            "UNIQUE",
+                            "SLOT",
+                            "TWO_WAY_BINDING",
+                            "OTHER_DIRECTIVES",
+                            "ATTR_DYNAMIC",
+                            "ATTR_STATIC",
+                            "EVENTS",
+                            "CONTENT",
+                            "ATTR_SHORTHAND_BOOL",
+                        ],
+                        alphabetical: false,
+                    },
+                ],
+
+                // Template + script rules
+                "@diphyx/template-v-if": "warn",
+                "@diphyx/template-v-else": "warn",
+                "@diphyx/template-v-for": "warn",
+                "@diphyx/template-text": "warn",
+                "@diphyx/script-section-order": "warn",
+                "@diphyx/script-define-object": "warn",
+            },
+        },
+
+        // Component file naming
+        {
+            files: ["app/components/**/*.vue"],
+            ignores: ["**/index.vue"],
+            plugins: {
+                "check-file": checkFilePlugin,
+            },
+            rules: {
+                "check-file/filename-naming-convention": ["warn", { "**/*.vue": "PASCAL_CASE" }],
+            },
+        },
+
+        // Store pattern
+        {
+            files: ["app/stores/*.ts", "app/composables/*.ts"],
+            plugins: {
+                "@diphyx": plugin,
+            },
+            rules: {
+                "@diphyx/store-require-name": "warn",
+                "@diphyx/store-require-model": "warn",
+                "@diphyx/store-require-view": "warn",
+                "@diphyx/store-require-action": "warn",
+                "@diphyx/store-section-function": "warn",
+                "@diphyx/store-section-method": "warn",
+                "@diphyx/store-section-return-shorthand": "warn",
+                "@diphyx/store-config-order": "warn",
+                "@diphyx/store-no-unknown-key": "warn",
+                "@diphyx/store-suffix": "warn",
+                "@diphyx/store-name-match": "warn",
+                "@diphyx/store-shape-suffix": "warn",
+                "@diphyx/store-mode-enum": "warn",
+            },
+        },
+
+        // Composable naming
+        {
+            files: ["app/composables/*.ts"],
+            plugins: {
+                "@diphyx": plugin,
+            },
+            rules: {
+                "@diphyx/composable-naming": "warn",
+            },
+        },
+
+        // Utility preferences (radash / vueuse) — all app code
+        {
+            files: ["**/*.ts", "**/*.vue"],
+            plugins: {
+                "@diphyx": plugin,
+            },
+            rules: {
+                "@diphyx/radash-prefer-is": "warn",
+                "@diphyx/radash-prefer-call": "warn",
+                "@diphyx/radash-prefer-clone": "warn",
+                "@diphyx/radash-prefer-unique": "warn",
+                "@diphyx/radash-prefer-sum": "warn",
+                "@diphyx/radash-prefer-sleep": "warn",
+                "@diphyx/vueuse-prefer-storage": "warn",
+                "@diphyx/vueuse-prefer-member-call": "warn",
+                "@diphyx/vueuse-prefer-timer": "warn",
+                "@diphyx/vueuse-prefer-observer": "warn",
+                "@diphyx/vueuse-prefer-clipboard": "warn",
+                "@diphyx/vueuse-prefer-route": "warn",
+            },
+        },
+    ];
+}

package/src/index.mjs

@@ -0,0 +1,22 @@
+// @diphyx/eslint-plugin — shared ESLint plugin + flat config for DiPhyx
+// Nuxt/Vue + Harlemify projects.
+
+import { createRequire } from "node:module";
+
+import { rules } from "./rules/index.mjs";
+import { createConfigs } from "./configs/index.mjs";
+
+const require = createRequire(import.meta.url);
+const { name, version } = require("../package.json");
+
+const plugin = {
+    meta: {
+        name,
+        version,
+    },
+    rules,
+};
+
+plugin.configs = createConfigs(plugin);
+
+export default plugin;

package/src/rules/composable-naming.mjs

@@ -0,0 +1,63 @@
+// Exported composable functions must follow the useXxx naming pattern.
+//
+// The main composable is the module-level export; its returned methods
+// (load/set/get/reset/start/stop) live inside it and are not linted here.
+
+const ALLOWED_PATTERN = /^use[A-Z]/;
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "exported composable functions must follow useXxx naming pattern",
+        },
+        messages: {
+            invalidName: "Exported composable function '{{name}}' should follow useXxx naming pattern.",
+        },
+        schema: [],
+    },
+    create(context) {
+        function check(idNode) {
+            const name = idNode?.name;
+            if (!name) {
+                return;
+            }
+
+            if (!ALLOWED_PATTERN.test(name)) {
+                context.report({
+                    node: idNode,
+                    messageId: "invalidName",
+                    data: {
+                        name,
+                    },
+                });
+            }
+        }
+
+        return {
+            ExportNamedDeclaration(node) {
+                const declaration = node.declaration;
+                if (!declaration) {
+                    return;
+                }
+
+                // export function useXxx() {}
+                if (declaration.type === "FunctionDeclaration") {
+                    check(declaration.id);
+
+                    return;
+                }
+
+                // export const useXxx = () => {} | function () {}
+                if (declaration.type === "VariableDeclaration") {
+                    for (const declarator of declaration.declarations) {
+                        const init = declarator.init;
+                        if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) {
+                            check(declarator.id);
+                        }
+                    }
+                }
+            },
+        };
+    },
+};

package/src/rules/index.mjs

@@ -0,0 +1,105 @@
+// All custom rules, keyed by their kebab-case name (one rule per file). The key
+// is the name a config references as @diphyx/<key>, and it also drives the rule's
+// generated docs URL, so the two never drift.
+
+import { docsUrl } from "../utils/docs.mjs";
+
+import templateVIf from "./template-v-if.mjs";
+import templateVElse from "./template-v-else.mjs";
+import templateVFor from "./template-v-for.mjs";
+import templateText from "./template-text.mjs";
+
+import scriptSectionOrder from "./script-section-order.mjs";
+import scriptDefineObject from "./script-define-object.mjs";
+
+import storeRequireName from "./store-require-name.mjs";
+import storeRequireModel from "./store-require-model.mjs";
+import storeRequireView from "./store-require-view.mjs";
+import storeRequireAction from "./store-require-action.mjs";
+import storeSectionFunction from "./store-section-function.mjs";
+import storeSectionMethod from "./store-section-method.mjs";
+import storeSectionReturnShorthand from "./store-section-return-shorthand.mjs";
+import storeConfigOrder from "./store-config-order.mjs";
+import storeNoUnknownKey from "./store-no-unknown-key.mjs";
+import storeSuffix from "./store-suffix.mjs";
+import storeNameMatch from "./store-name-match.mjs";
+import storeShapeSuffix from "./store-shape-suffix.mjs";
+import storeModeEnum from "./store-mode-enum.mjs";
+
+import composableNaming from "./composable-naming.mjs";
+
+import radashPreferIs from "./radash-prefer-is.mjs";
+import radashPreferCall from "./radash-prefer-call.mjs";
+import radashPreferClone from "./radash-prefer-clone.mjs";
+import radashPreferUnique from "./radash-prefer-unique.mjs";
+import radashPreferSum from "./radash-prefer-sum.mjs";
+import radashPreferSleep from "./radash-prefer-sleep.mjs";
+
+import vueusePreferStorage from "./vueuse-prefer-storage.mjs";
+import vueusePreferMemberCall from "./vueuse-prefer-member-call.mjs";
+import vueusePreferTimer from "./vueuse-prefer-timer.mjs";
+import vueusePreferObserver from "./vueuse-prefer-observer.mjs";
+import vueusePreferClipboard from "./vueuse-prefer-clipboard.mjs";
+import vueusePreferRoute from "./vueuse-prefer-route.mjs";
+
+export const rules = {
+    // Template
+    "template-v-if": templateVIf,
+    "template-v-else": templateVElse,
+    "template-v-for": templateVFor,
+    "template-text": templateText,
+
+    // Script
+    "script-section-order": scriptSectionOrder,
+    "script-define-object": scriptDefineObject,
+
+    // Store — required keys
+    "store-require-name": storeRequireName,
+    "store-require-model": storeRequireModel,
+    "store-require-view": storeRequireView,
+    "store-require-action": storeRequireAction,
+
+    // Store — section shape
+    "store-section-function": storeSectionFunction,
+    "store-section-method": storeSectionMethod,
+    "store-section-return-shorthand": storeSectionReturnShorthand,
+
+    // Store — config integrity
+    "store-config-order": storeConfigOrder,
+    "store-no-unknown-key": storeNoUnknownKey,
+
+    // Store — naming
+    "store-suffix": storeSuffix,
+    "store-name-match": storeNameMatch,
+    "store-shape-suffix": storeShapeSuffix,
+
+    // Store — values
+    "store-mode-enum": storeModeEnum,
+
+    // Composable
+    "composable-naming": composableNaming,
+
+    // Radash
+    "radash-prefer-is": radashPreferIs,
+    "radash-prefer-call": radashPreferCall,
+    "radash-prefer-clone": radashPreferClone,
+    "radash-prefer-unique": radashPreferUnique,
+    "radash-prefer-sum": radashPreferSum,
+    "radash-prefer-sleep": radashPreferSleep,
+
+    // VueUse
+    "vueuse-prefer-storage": vueusePreferStorage,
+    "vueuse-prefer-member-call": vueusePreferMemberCall,
+    "vueuse-prefer-timer": vueusePreferTimer,
+    "vueuse-prefer-observer": vueusePreferObserver,
+    "vueuse-prefer-clipboard": vueusePreferClipboard,
+    "vueuse-prefer-route": vueusePreferRoute,
+};
+
+// Backfill each rule's docs metadata from its registered name so every rule
+// exposes a valid `meta.docs.url` and `recommended` flag without repeating the
+// name in the rule file itself.
+for (const [name, rule] of Object.entries(rules)) {
+    rule.meta = rule.meta || {};
+    rule.meta.docs = { recommended: true, ...rule.meta.docs, url: docsUrl(name) };
+}

package/src/rules/radash-prefer-call.mjs

@@ -0,0 +1,33 @@
+// Prefer radash helpers over native global calls.
+
+import { staticMemberName } from "../utils/ast.mjs";
+
+// `<Global>.<method>(...)` → radash helper
+const GLOBAL_CALLS = {
+    "Promise.all": "all",
+    "Array.isArray": "isArray",
+};
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer radash helpers over native global calls",
+        },
+        messages: {
+            preferCall: "Use radash '{{helper}}()' instead of '{{native}}()'.",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                const name = staticMemberName(node.callee);
+                const helper = name && GLOBAL_CALLS[name];
+                if (helper) {
+                    context.report({ node: node.callee, messageId: "preferCall", data: { helper, native: name } });
+                }
+            },
+        };
+    },
+};

package/src/rules/radash-prefer-clone.mjs

@@ -0,0 +1,33 @@
+// Prefer radash clone() over JSON.parse(JSON.stringify()).
+
+import { staticMemberName } from "../utils/ast.mjs";
+
+function isJsonStringifyCall(node) {
+    return node.type === "CallExpression" && staticMemberName(node.callee) === "JSON.stringify";
+}
+
+export default {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "prefer radash clone() over JSON.parse(JSON.stringify())",
+        },
+        messages: {
+            preferClone: "Use radash 'clone()' instead of JSON.parse(JSON.stringify(...)).",
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                if (
+                    staticMemberName(node.callee) === "JSON.parse" &&
+                    node.arguments[0] &&
+                    isJsonStringifyCall(node.arguments[0])
+                ) {
+                    context.report({ node, messageId: "preferClone" });
+                }
+            },
+        };
+    },
+};