@medusajs/eslint-plugin 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +52 -0
  2. package/README.md +72 -17
  3. package/package.json +5 -1
package/AGENTS.md ADDED
@@ -0,0 +1,52 @@
1
+ # @medusajs/eslint-plugin
2
+
3
+ Official ESLint plugin (flat config) that turns Medusa framework conventions into lint rules for API routes, workflows, modules, data models, links, subscribers, jobs, and admin extensions. It powers `medusa lint` and the lint step of `medusa develop` / `medusa build`, and also lints this monorepo.
4
+
5
+ ## Using this package
6
+
7
+ ```ts
8
+ // eslint.config.ts
9
+ import { defineConfig } from "eslint/config"
10
+ import medusa from "@medusajs/eslint-plugin"
11
+
12
+ export default defineConfig([...medusa.configs.recommended])
13
+ ```
14
+
15
+ - Presets (`src/configs/`):
16
+ - `recommended`: path-scoped rules (`src/api/**`, `src/modules/**`, `src/admin/**`, `src/links/**`, `src/subscribers/*`, `src/jobs/*`, workflows everywhere), no type info needed.
17
+ - `strict`: `recommended` + type-aware rules (sets `parserOptions.project: true`, so a tsconfig must include the linted files) + the cross-file `scheduled-job-name-unique`.
18
+ - `modules`: for a standalone module/provider package (services anywhere, `module-name-snake-case` on `src/index.{ts,js}`, model rules on `**/models/**`).
19
+ - Rule ids are `@medusajs/<rule-name>`; override after the preset spread.
20
+ - Peer deps: `eslint` `^8.57.0 || ^9.0.0` (v8 needs `ESLINT_USE_FLAT_CONFIG=true` outside the Medusa CLI), `typescript >=4.8.0`. `jiti` is needed to load `eslint.config.ts`.
21
+ - Docs: https://docs.medusajs.com/resources/lint.md and per-rule pages at https://docs.medusajs.com/resources/lint/rules.md/<rule-name> (this URL is also emitted as `meta.docs.url` by `src/create-rule.ts`).
22
+
23
+ ## Architecture
24
+
25
+ - `src/index.ts`: plugin object `{ meta, rules, configs }`; configs are built after the object exists because each preset embeds the plugin itself.
26
+ - `src/rules/<rule-name>/{index.ts,rule.ts,__tests__/rule.spec.ts}`; `index.ts` re-exports `rule`. Every rule is registered in `src/rules/index.ts`.
27
+ - `src/create-rule.ts`: `createRule` (`ESLintUtils.RuleCreator`) with `MedusaRuleDocs` (`description`, `recommended?`, `strict?`, `requiresTypeChecking?`).
28
+ - `src/constants.ts`: `PLUGIN_NAMESPACE` (`@medusajs`), `ruleId()`, import sources rules match on (`@medusajs/framework/utils`, `.../workflows-sdk`, `.../http`, `.../types`, `@medusajs/admin-sdk`), and `MODULES_BY_VALUE`, a hand-copied map of `Modules` enum values from `packages/core/utils/src/modules-sdk/definition.ts`.
29
+ - `src/util/`: shared detectors (`api-route.ts`, `workflow-scope.ts`, `service-scope.ts`, `admin-scope.ts`, `middlewares.ts`, `link.ts`, `container.ts`, `filename.ts`, `ast.ts`). Rules gate themselves on filename (e.g. `isUnderApiDir`) in addition to the preset `files` globs, and return `{}` for virtual filenames starting with `<`.
30
+ - `src/configs/shared.ts`: `ignoresBlock` (dist, `.medusa`, tests, `integration-tests`, `apps/storefront`, ...), `pluginBlock` (global, no `files`), `tsParserBlock(withProject)`.
31
+
32
+ ## Development
33
+
34
+ - `yarn build`, `yarn watch`, `yarn test` (jest over `src`).
35
+ - Single rule: `../../node_modules/.bin/jest src/rules/<rule-name>` from this directory (`yarn test <path>` ignores the path because the script already sets `--testPathPattern=src`).
36
+ - Tests use `createRuleTester()` from `src/test-utils.ts`. Cross-file rules (`scheduled-job-name-unique`, `loader-must-be-exported-in-module-definition`, `use-validated-body-or-query`) need real files: use `createFixtureWorkspace(subPath, files)`, lint with the absolute path from `resolve(rel)`, and `afterAll(cleanupFixtureWorkspaces)`.
37
+ - Adding a rule:
38
+ 1. `src/rules/<name>/` with `rule.ts`, `index.ts`, `__tests__/rule.spec.ts`
39
+ 2. register it in `src/rules/index.ts`
40
+ 3. enable it in the right preset block(s) in `src/configs/` with the right `files` scope
41
+ 4. add the docs page `www/apps/resources/app/lint/rules/<name>/page.mdx` (the sidebar autogenerates from `lint/rules` in `www/apps/resources/sidebars/tools.mjs`)
42
+ - The monorepo dogfoods the plugin: root `.eslintrc.js` requires the built package and `eslint.medusa.cjs` / `yarn lint:medusa` (run in CI) apply only the `@medusajs/*` rules. A new `error` rule can fail CI on existing framework code.
43
+
44
+ ## Gotchas
45
+
46
+ - Root `.eslintrc.js` and `www` (`link:../packages/eslint-plugin`) load `dist/`, so run `yarn workspace @medusajs/eslint-plugin build` before linting the repo or www after changing a rule (CI does this explicitly).
47
+ - Keep the plugin registration block free of `files`; scoping it to TS breaks `.js` files with `Could not find plugin "@medusajs"`.
48
+ - Only `strict` may contain rules that need type information; `recommended` and `modules` must stay zero-config.
49
+ - `subscribers/*` and `jobs/*` globs intentionally match direct children only (Medusa only loads those); nested files are utilities.
50
+ - Admin rules are scoped to `src/admin/**` specifically so they don't hit `src/api/admin/**` server routes.
51
+ - Messages that mention `allowFields` quote `ALLOW_FIELDS_MIN_MEDUSA_VERSION` (`2.21.0`) because the plugin and project Medusa versions can differ.
52
+ - `README.md` still says the plugin ships no rules; it is stale.
package/README.md CHANGED
@@ -1,34 +1,89 @@
1
- # @medusajs/eslint-plugin
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/eslint-plugin
12
+ </h1>
2
13
 
3
- Official ESLint plugin for Medusa projects. Codifies Medusa's framework conventions into automatically-enforced static checks across API routes, modules, workflows, subscribers, scheduled jobs, admin extensions, and module links.
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
4
18
 
5
- > Status: pre-release. The plugin currently ships with no rules — only the package scaffold and `recommended` / `strict` config shapes. Rules will land incrementally; see `MEDUSA_LINT_RULES_CATALOG.md` at the repo root for the planned set.
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ `@medusajs/eslint-plugin` is the official ESLint plugin for Medusa projects: it enforces Medusa's conventions for API routes, workflows, modules, data models, subscribers, scheduled jobs, admin extensions, and module links as lint rules. Projects created with Medusa v2.16.0 or later already include it with an `eslint.config.ts` file; add it manually to older projects, plugins, or standalone module packages.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/eslint-plugin` |
44
+ | Type | Internal tooling |
45
+ | Import from | `@medusajs/eslint-plugin` |
46
+ | Entry points | `./configs/recommended`, `./configs/strict` |
47
+
48
+ ## Features
49
+
50
+ - 74 rules under the `@medusajs/` prefix, such as `@medusajs/no-loops-in-workflow` and `@medusajs/route-file-naming`.
51
+ - `recommended` preset: the default for Medusa applications. Its rules don't need type information.
52
+ - `strict` preset: extends `recommended` with type-aware and cross-file rules. Requires a `tsconfig.json` that includes the linted files.
53
+ - `modules` preset: service, module definition, and data model rules for packages that only provide a module or module provider.
54
+ - Flat config only. Supports ESLint `^8.57.0 || ^9.0.0` and TypeScript `>=4.8.0`.
6
55
 
7
56
  ## Installation
8
57
 
9
58
  ```bash
10
- npm install -D @medusajs/eslint-plugin eslint
59
+ npm install --save-dev @medusajs/eslint-plugin eslint jiti
11
60
  ```
12
61
 
13
- `eslint` is a peer dependency — install it in the consuming project.
62
+ `eslint` is a peer dependency. `jiti` lets ESLint load an `eslint.config.ts` file.
14
63
 
15
- ## Usage (flat config)
64
+ ## Usage
16
65
 
17
- ```js
18
- // eslint.config.js
66
+ ```ts
67
+ import { defineConfig } from "eslint/config"
19
68
  import medusa from "@medusajs/eslint-plugin"
20
69
 
21
- export default [...medusa.configs.recommended]
70
+ export default defineConfig([...medusa.configs.recommended])
22
71
  ```
23
72
 
24
- ## Configs
25
-
26
- - `recommended` — default preset for Medusa projects.
27
- - `strict` — extends `recommended` and enables stricter, opt-in heuristics.
28
-
29
- ## Development
73
+ Lint the project with the Medusa CLI:
30
74
 
31
75
  ```bash
32
- yarn workspace @medusajs/eslint-plugin build
33
- yarn workspace @medusajs/eslint-plugin test
76
+ npx medusa lint
34
77
  ```
78
+
79
+ | Flag | Description | Default |
80
+ | --- | --- | --- |
81
+ | `[paths...]` | Files or directories to lint. | Whole project |
82
+ | `--fix` | Auto-fix issues where possible. | `false` |
83
+ | `--quiet` | Report errors only. | `false` |
84
+
85
+ ## Resources
86
+
87
+ - [Medusa ESLint plugin](https://docs.medusajs.com/resources/lint)
88
+ - [Rules reference](https://docs.medusajs.com/resources/lint/rules)
89
+ - [`medusa lint` command](https://docs.medusajs.com/resources/medusa-cli/commands/lint)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@medusajs/eslint-plugin",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Official ESLint plugin for Medusa projects. Enforces Medusa's framework conventions across API routes, modules, workflows, subscribers, jobs, admin extensions, and module links.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -30,10 +30,14 @@
30
30
  },
31
31
  "files": [
32
32
  "dist",
33
+ "AGENTS.md",
33
34
  "!dist/**/__tests__",
34
35
  "!dist/**/*.spec.*",
35
36
  "!dist/**/*.test.*"
36
37
  ],
38
+ "llms": "https://docs.medusajs.com/llms.txt",
39
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
40
+ "mcpServer": "https://docs.medusajs.com/mcp",
37
41
  "keywords": [
38
42
  "eslint",
39
43
  "eslintplugin",