@scayle/eslint-auto-explicit-import 0.2.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @scayle/eslint-auto-explicit-import

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SCAYLE GmbH
+
+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,58 @@
+# @scayle/storefront-eslint-auto-explicit-import
+
+An extension of the official `@nuxt/eslint` module to insert more explicit import statement
+automatically using `eslint --fix` into a Nuxt-based SCAYLE Storefront project.
+
+NOTE: Currently composables, utilities, helper functions and imported functions from packages will
+be automatically inserted as imports. No components used within a `<template>` will be imported by it!
+
+- Based on [nuxt-eslint-auto-explicit-import](https://github.com/antfu/nuxt-eslint-auto-explicit-import)
+- Based on [eslint-plugin-unimport](https://github.com/antfu/eslint-plugin-unimport)
+- [Official @nuxt/eslint module](https://eslint.nuxt.com/)
+- [Official ESLint Documentation](https://eslint.org/docs/latest/)
+
+## Example
+
+- [Example Commit on eslint-flat-config-viewer](https://github.com/antfu/eslint-flat-config-viewer/commit/0f8000851b4ac0d7f3ea5e49963c6d7248303b7b)
+
+## Details
+
+## Usage
+
+Add local module to `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: [
+    // Both are required
+    '@nuxt/eslint',
+    '@scayle/eslint-auto-explicit-import',
+  ],
+})
+```
+
+Followed by adding a dedicated `eslint` flat config if none exists:
+
+```js
+// eslint.config.mjs
+import withNuxt from './nuxt/eslint.config.mjs'
+
+export default withNuxt({
+  // Your ESLint config
+})
+```
+
+Running `eslint` should now throw errors if a source file does use auto-import.
+Adding `--fix` allows for automatically inserting / fixing of missing imports.
+
+```sh
+# pnpm lint .
+pnpm lint . --fix
+```
+
+## Troubleshooting
+
+1. Should a Vue component not have a dedicated `<script>` tag with some content within,
+   it might be possible that the included local `eslint-plugin-unimport` fails with a
+   `range` undefined error.
+   In this case it is necessary to manually add the missing `<script>` tag with some dummy content.

package/dist/eslint-plugin-unimport.mjs

@@ -0,0 +1,392 @@
+import { dirname, isAbsolute, relative } from 'pathe'
+import { ESLintUtils } from '@typescript-eslint/utils'
+import { analyze } from '@typescript-eslint/scope-manager'
+import Debug from 'debug'
+
+// Based on <https://github.com/antfu/eslint-plugin-unimport>
+
+const version = '0.0.3'
+
+const createRule = ESLintUtils.RuleCreator(
+  () => 'https://github.com/antfu/eslint-plugin-unimport',
+)
+
+function betterRelative(from, to) {
+  // eslint-disable-next-line sonarjs/single-char-in-character-classes
+  const r = relative(from, to).replace(/\.[\w]+/g, '')
+
+  if (r.startsWith('../')) {
+    return r
+  }
+
+  return `./${r}`
+}
+
+const debug = Debug('unimport:eslint')
+
+function createImportsListeners(context, imports, onImportEntry) {
+  let _scopeManager
+  let _importsMap
+  const importedNames = /* @__PURE__ */ new Set()
+
+  function getScopeManager() {
+    if (!_scopeManager) {
+      _scopeManager = analyze(context.sourceCode.ast, {
+        sourceType: 'module',
+      })
+
+      _scopeManager.globalScope?.variables.forEach((node) => {
+        importedNames.add(node.name)
+      })
+    }
+
+    return _scopeManager
+  }
+
+  function getImportsMap() {
+    if (!_importsMap) {
+      _importsMap = /* @__PURE__ */ new Map()
+      imports.forEach((i) => {
+        _importsMap.set(i.as || i.name, i)
+      })
+    }
+
+    return _importsMap
+  }
+
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  function checkId(node) {
+    if (typeof node.name !== 'string') {
+      return
+    }
+
+    if (importedNames.has(node.name)) {
+      return
+    }
+
+    const importsMap = getImportsMap()
+    const item = importsMap.get(node.name)
+
+    if (!item) {
+      return
+    }
+
+    if (item.from === context.filename) {
+      return
+    }
+
+    const scopeManager = getScopeManager()
+
+    if (importedNames.has(node.name)) {
+      return
+    }
+
+    let parent = node.parent
+    let currentScope = null
+
+    while (parent && !currentScope) {
+      currentScope = scopeManager.acquire(parent)
+
+      if (currentScope) {
+        break
+      }
+
+      parent = parent.parent
+    }
+
+    if (!currentScope) {
+      currentScope = scopeManager.globalScope
+    }
+
+    const visited = /* @__PURE__ */ new Set()
+
+    while (true) {
+      if (!currentScope || visited.has(currentScope)) {
+        break
+      }
+
+      for (const ref of currentScope.variables) {
+        if (ref.name === node.name) {
+          return
+        }
+      }
+
+      visited.add(currentScope)
+      currentScope = currentScope.upper
+    }
+
+    importedNames.add(node.name)
+    onImportEntry(node, item)
+  }
+  return {
+    Identifier(node) {
+      if (/Declaration|Specifier|Property/.test(node.parent.type)) {
+        return
+      }
+
+      if (
+        node.parent.type === 'MemberExpression' &&
+        node.parent.object !== node
+      ) {
+        return
+      }
+
+      checkId(node)
+    },
+    ImportDeclaration(node) {
+      node.specifiers.forEach((s) => {
+        importedNames.add(s.local.name)
+      })
+    },
+    'Program:exit': function() {
+      const vueTemplate = context.sourceCode.ast.templateBody
+
+      if (!vueTemplate) {
+        return
+      }
+
+      function visit(node) {
+        if (!node) {
+          return
+        }
+
+        const expressionNode = node
+
+        switch (expressionNode.type) {
+          case 'Identifier':
+            checkId(expressionNode)
+            return
+          case 'MemberExpression':
+            visit(expressionNode.object)
+            return
+          case 'CallExpression':
+            visit(expressionNode.callee)
+            for (const arg of expressionNode.arguments) {
+              visit(arg)
+            }
+            return
+          case 'ConditionalExpression':
+            visit(expressionNode.test)
+            visit(expressionNode.consequent)
+            visit(expressionNode.alternate)
+            return
+          case 'FunctionExpression':
+          case 'ArrowFunctionExpression':
+            for (const param of expressionNode.params) {
+              visit(param)
+            }
+            visit(expressionNode.body)
+            return
+          case 'LogicalExpression':
+          case 'BinaryExpression':
+            visit(expressionNode.left)
+            visit(expressionNode.right)
+            return
+        }
+
+        switch (node.type) {
+          case 'VText':
+            return
+          case 'VExpressionContainer':
+            return visit(node.expression)
+          case 'VElement':
+            for (const attr of node.startTag.attributes) {
+              visit(attr)
+            }
+            for (const child of node.children) {
+              visit(child)
+            }
+            return
+          case 'VAttribute':
+            visit(node.value)
+            return
+        }
+
+        if ('children' in node) {
+          for (const child of node.children) {
+            visit(child)
+          }
+
+          return
+        }
+
+        if ('body' in node) {
+          visit(node.body)
+
+          return
+        }
+
+        {
+          const { tokens, parent, range, loc, ...rest } = node
+          debug('Unknown VNode', rest)
+        }
+      }
+
+      visit(vueTemplate)
+    },
+  }
+}
+
+const importPathDirNames = [
+  '/node_modules/',
+  '/packages/storefront-nuxt/',
+  '/packages/omnichannel-nuxt/', // Package needs to export appropriate `#omnichannel/composables` alias first
+]
+
+const validDirNames = {
+  storefrontNuxt: ['@scayle/storefront-nuxt', '/packages/storefront-nuxt'],
+  omnichannelNuxt: ['@scayle/omnichannel-nuxt', '/packages/omnichannel-nuxt'],
+}
+
+// Mapping normalized import paths of packages to pure package imports
+// to avoid "Nuxt Build Error: [vite:load-fallback] Could not load (...)" if
+// path can not properly be resolved within package dist directory.
+const importsMap = {
+  'vue-i18n/dist/vue-i18n': 'vue-i18n',
+  '@nuxtjs/i18n/dist/runtime/composables/index': '#i18n', // https://github.com/nuxt-modules/i18n/blob/main/package.json#L34C6-L34C11
+  'nuxt/dist/pages/runtime/composables': '#imports', // Needs to be imported through #imports to properly work with TypeScript in the Nuxt context
+  'nuxt-jsonld/dist/runtime/composable': '#imports', // Needs to be imported through #imports to properly work with TypeScript in the Nuxt context
+  '@nuxt/image/dist/runtime/composables': '#imports', // Needs to be imported through #imports to properly work with TypeScript in the Nuxt context
+}
+
+const transformPathToImport = (itemFrom, dirName) => {
+  const partialPath = itemFrom.split(dirName)[1]
+
+  // We check if we're trying to import composables from `@scayle/storefront-nuxt`
+  // or `@scayle/omnichannel-nuxt` and transform the import to their respective
+  // allowed import path or alias.
+  // NOTE: If a Nuxt project is part of a mono-repo setup and some of its used packages
+  // are located within the root repo, the package resolution using `mlly` will not
+  // resolve to a node_modules packages, but to the local package within the repository.
+  // https://github.com/unjs/mlly/issues/158
+  // For this reason we include a workaround that is able to check if we're within the
+  // mono-repo setup and transform the import paths appropriately.
+  if (
+    validDirNames.storefrontNuxt.some((element) => itemFrom.includes(element))
+  ) {
+    return '#storefront/composables'
+  }
+
+  if (
+    validDirNames.omnichannelNuxt.some((element) => itemFrom.includes(element))
+  ) {
+    return '#omnichannel/composables'
+  }
+
+  // `nuxt-module-builder@0.7.0` changed the file extension for files within
+  // the build `/dist/runtime/` directory from `.mjs` to `.js`.
+  // https://github.com/nuxt/module-builder/commit/dbd05bb
+  const normalizedImportPath = partialPath.replace(/mjs|js/gi, '')
+
+  return importsMap[normalizedImportPath] ?? normalizedImportPath
+}
+
+const createImportPaths = (item, context, srcAlias = '~') => {
+  const relativePath = betterRelative(
+    dirname(context.physicalFilename),
+    item.from,
+  )
+
+  if (!isAbsolute(item.from)) {
+    return item.from
+  }
+
+  // We're checking if the item.from path contains one of the relevant directory names
+  // that we want to have transformed to a "plain" package import or alias import instead.
+  const dirName = importPathDirNames.find((name) => relativePath.includes(name))
+
+  if (dirName) {
+    return transformPathToImport(relativePath, dirName)
+  }
+
+  return `${srcAlias}/${relativePath.replaceAll('../', '')}`
+}
+
+const autoInsert = createRule({
+  name: 'auto-insert',
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Auto insert missing imports from unimport registry',
+    },
+    messages: {
+      missingImport:
+        `Unimport entry '{{name}}' from '{{from}}' is not imported.`,
+    },
+    schema: [{ type: 'array', items: { type: 'any' } }],
+    fixable: 'code',
+  },
+  defaultOptions: [],
+  create(context) {
+    return createImportsListeners(
+      context,
+      context.options[0] || [],
+      (node, item) => {
+        context.report({
+          node,
+          messageId: 'missingImport',
+          data: {
+            name: item.name,
+            from: createImportPaths(item, context),
+          },
+          fix(fixer) {
+            const resolvedFrom = createImportPaths(item, context)
+            const body = context.sourceCode.ast.body
+
+            let importName = ''
+
+            if (item.name === '*') {
+              importName = `* as ${item.as}`
+            } else if (item.name === 'default') {
+              // Default exports should be imported without curly braces
+              importName = item.as || item.name
+            } else if (!item.as || item.name === item.as) {
+              // Named exports should be imported with curly braces
+              importName = `{ ${item.name} }`
+            } else {
+              // Named exports with aliases should be imported with curly braces
+              importName = `{ ${item.name} as ${item.as} }`
+            }
+
+            return fixer.insertTextBefore(
+              body[0],
+              `import ${importName} from '${resolvedFrom}'
+`,
+            )
+          },
+        })
+      },
+    )
+  },
+})
+
+const plugin = {
+  meta: {
+    name: 'unimport',
+    version,
+  },
+  rules: {
+    'auto-insert': autoInsert,
+  },
+}
+
+function createAutoInsert(options) {
+  return {
+    name: 'unimport:auto-insert',
+    plugins: {
+      unimport: plugin,
+    },
+    files: options.include ?? [
+      '**/*.ts',
+      '**/*.(c|m)js',
+      '**/*.(m|c)?tsx?',
+      '**/*.vue',
+    ],
+    ignores: options.exclude ?? ['**/*.mdx?/**'],
+    rules: {
+      'unimport/auto-insert': ['error', options.imports],
+    },
+  }
+}
+
+export { createAutoInsert, plugin as default }

package/dist/module.d.mts

@@ -0,0 +1,7 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+type ModuleOptions = object;
+declare const _default: _nuxt_schema.NuxtModule<object, object, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "storefront-eslint-auto-explicit-import",
+  "configKey": "storefront-eslint-auto-explicit-import",
+  "version": "0.2.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.1",
+    "unbuild": "3.5.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,46 @@
+import { defineNuxtModule, createResolver, logger } from '@nuxt/kit';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "storefront-eslint-auto-explicit-import"
+  },
+  setup(_, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    let unimport;
+    nuxt.hook("imports:context", (ctx) => {
+      unimport = ctx;
+    });
+    nuxt.hook("eslint:config:addons", (addons) => {
+      addons.push({
+        name: "storefront-eslint-auto-explicit-import",
+        async getConfigs() {
+          if (!unimport) {
+            logger.warn(
+              "unimport is not ready for storefront-eslint-auto-explicit-import"
+            );
+          }
+          return {
+            imports: [
+              {
+                from: resolve("./eslint-plugin-unimport.mjs"),
+                name: "createAutoInsert"
+              }
+            ],
+            configs: [
+              [
+                "// storefront-eslint-auto-explicit-import",
+                "createAutoInsert({",
+                `  imports: ${JSON.stringify(
+                  await unimport?.getImports() || []
+                )}`,
+                "})"
+              ].join("\n")
+            ]
+          };
+        }
+      });
+    });
+  }
+});
+
+export { module as default };

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@scayle/eslint-auto-explicit-import",
+  "version": "0.2.0",
+  "description": "Automatically add explicit imports to ESLint",
+  "author": "SCAYLE Commerce Engine",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "url": "git+https://github.com/scayle/eslint-auto-explicit-import.git"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "import"
+  ],
+  "main": "./dist/module.mjs",
+  "type": "module",
+  "files": [
+    "CHANGELOG.md",
+    "dist/**",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.mts",
+      "default": "./dist/module.mjs"
+    }
+  },
+  "dependencies": {
+    "debug": "4.4.1",
+    "pathe": "2.0.3"
+  },
+  "devDependencies": {
+    "@nuxt/kit": "3.16.2",
+    "@typescript-eslint/scope-manager": "8.36.0",
+    "@typescript-eslint/utils": "8.36.0",
+    "dprint": "0.50.1",
+    "eslint": "9.31.0",
+    "typescript": "5.8.3",
+    "unbuild": "3.5.0",
+    "unimport": "0.1.2",
+    "@scayle/eslint-config-storefront": "4.5.14"
+  },
+  "engines": {
+    "node": ">= 20.0.0"
+  },
+  "peerDependencies": {
+    "@nuxt/kit": ">=3.13.0"
+  },
+  "volta": {
+    "node": "22.17.0"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build",
+    "lint": "eslint .",
+    "lint:ci": "eslint . --format gitlab",
+    "format": "dprint check",
+    "format:fix": "dprint fmt",
+    "typecheck": "tsc"
+  }
+}