@backstage/eslint-plugin 0.2.3-next.0 → 0.3.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @backstage/eslint-plugin
 
+## 0.3.0-next.0
+
+### Minor Changes
+
+- ab1cdbb: Added a new `no-self-package-imports` lint rule, enabled as `error` in the recommended config, that reports when a package imports itself by its own name instead of using a relative path. This pattern causes circular initialization errors in bundled ESM and with `jest.requireActual`.
+
+## 0.2.3
+
+### Patch Changes
+
+- df43b0e: Fixed `no-mixed-plugin-imports` rule to return `null` from non-fixable suggestion handlers and added an explicit `SuggestionReportDescriptor[]` type annotation, matching the stricter type checking in TypeScript 6.0.
+
 ## 0.2.3-next.0
 
 ### Patch Changes

package/docs/rules/no-self-package-imports.md

@@ -0,0 +1,106 @@
+# @backstage/no-self-package-imports
+
+This rule prevents a package from importing itself by its own name when the
+imported entry point bundles the current file. Self-package imports in that
+situation create a circular dependency through the bundled barrel, which can
+surface as runtime errors such as
+`Cannot access 'X' before initialization` when the package is loaded in an
+environment that triggers eager re-evaluation (for example
+`jest.requireActual`, or ESM consumers that follow the cycle).
+
+The rule understands your package's `exports` map and follows the
+relative import graph from each entry's source file to determine which files
+are actually bundled into each entry. It then reports:
+
+- **Same-entry self-imports**: the current file is part of the same bundle
+  as the entry it imports, so the cycle is real.
+- **Cross-entry self-imports** (optional): the file is part of a different
+  entry's bundle than the one it imports. Cross-entry self-imports don't
+  always cycle, but they still couple unrelated entry points at initialization
+  time and are worth avoiding.
+
+Files that aren't reachable from any published entry (tests, scripts,
+orphans) are skipped, as self-imports from them can't affect a published
+bundle.
+
+Imports declared with `import type` (or `export type`) are erased at runtime
+and are always allowed, since they can't cause circular initialization.
+
+## Usage
+
+Add the rule as follows:
+
+```js
+"@backstage/no-self-package-imports": ["error"]
+```
+
+This errors on same-entry self-imports. Cross-entry self-imports are allowed
+by default; opt in to reporting them with `allowCrossEntry: false`:
+
+```js
+"@backstage/no-self-package-imports": ["error", { "allowCrossEntry": false }]
+```
+
+## Rule Details
+
+Given this `package.json`:
+
+```json
+{
+  "name": "@backstage/plugin-foo",
+  "exports": {
+    ".": "./src/index.ts",
+    "./alpha": "./src/alpha.ts",
+    "./package.json": "./package.json"
+  }
+}
+```
+
+and `src/index.ts` that re-exports `./blueprint`:
+
+```ts
+export * from './blueprint';
+```
+
+### Fail
+
+Importing `@backstage/plugin-foo` from a file that is also reachable from
+`src/index.ts` creates a cycle:
+
+```ts
+// src/blueprint.ts
+import { helper } from '@backstage/plugin-foo';
+```
+
+### Pass
+
+Use a relative import instead:
+
+```ts
+// src/blueprint.ts
+import { helper } from './helper';
+```
+
+Or, if only the type is used, `import type` is erased at runtime and is
+always allowed:
+
+```ts
+// src/blueprint.ts
+import type { Helper } from '@backstage/plugin-foo';
+```
+
+Importing `package.json` is always allowed:
+
+```ts
+import { version } from '@backstage/plugin-foo/package.json';
+```
+
+## Options
+
+### `allowCrossEntry`
+
+- Type: `boolean`
+- Default: `true`
+
+When `false`, the rule also reports self-imports that target a different
+entry from the one the current file is part of.

package/index.js

@@ -24,6 +24,7 @@ module.exports = {
         '@backstage/no-undeclared-imports': 'error',
         '@backstage/no-mixed-plugin-imports': 'warn',
         '@backstage/no-ui-css-imports-in-non-frontend': 'error',
+        '@backstage/no-self-package-imports': 'error',
       },
     },
   },
@@ -34,5 +35,6 @@ module.exports = {
     'no-top-level-material-ui-4-imports': require('./rules/no-top-level-material-ui-4-imports'),
     'no-mixed-plugin-imports': require('./rules/no-mixed-plugin-imports'),
     'no-ui-css-imports-in-non-frontend': require('./rules/no-ui-css-imports-in-non-frontend'),
+    'no-self-package-imports': require('./rules/no-self-package-imports'),
   },
 };

package/lib/visitImports.js

@@ -111,7 +111,7 @@ function getImportInfo(node) {
   return {
     path: pathNode.value,
     node: pathNode,
-    kind: anyNode.importKind ?? 'value',
+    kind: anyNode.importKind ?? anyNode.exportKind ?? 'value',
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/eslint-plugin",
-  "version": "0.2.3-next.0",
+  "version": "0.3.0-next.0",
   "description": "Backstage ESLint plugin",
   "publishConfig": {
     "access": "public"
@@ -22,7 +22,7 @@
     "minimatch": "^10.2.1"
   },
   "devDependencies": {
-    "@backstage/cli": "0.36.1-next.1",
+    "@backstage/cli": "0.36.2-next.1",
     "@types/estree": "^1.0.5",
     "eslint": "^8.33.0"
   }

package/rules/no-self-package-imports.js

@@ -0,0 +1,284 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// @ts-check
+
+const fs = require('node:fs');
+const path = require('node:path');
+const visitImports = require('../lib/visitImports');
+const getPackages = require('../lib/getPackages');
+
+/**
+ * @typedef EntryInfo
+ * @type {object}
+ * @property {string} key - The exports key, e.g. '.' or './alpha'.
+ * @property {string} sourceFile - The source file for the entry, relative to the package dir.
+ */
+
+const SOURCE_EXTENSIONS = [
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.cjs',
+];
+
+// Cache the per-package analysis across files lint invocations. The key is the
+// absolute package dir; the value is a Map from absolute file path to the set
+// of entry keys whose bundle reaches that file.
+/** @type {Map<string, Map<string, Set<string>>>} */
+const bundleCache = new Map();
+
+/**
+ * Build a list of entries from the package.json exports field. Entries that
+ * don't point to a script (e.g. `./package.json`) are ignored.
+ *
+ * @param {unknown} exportsField
+ * @returns {EntryInfo[]}
+ */
+function readEntries(exportsField) {
+  if (!exportsField || typeof exportsField !== 'object') {
+    return [{ key: '.', sourceFile: 'src/index.ts' }];
+  }
+  /** @type {EntryInfo[]} */
+  const entries = [];
+  for (const [key, value] of Object.entries(exportsField)) {
+    if (typeof value !== 'string') continue;
+    if (key === './package.json') continue;
+    const rel = value.replace(/^\.\//, '');
+    entries.push({ key, sourceFile: rel });
+  }
+  return entries;
+}
+
+/**
+ * Resolve a relative module specifier against a containing file.
+ * Tries source extensions and index files, in that order.
+ *
+ * @param {string} fromFile
+ * @param {string} specifier
+ * @returns {string | undefined}
+ */
+function resolveSourcePath(fromFile, specifier) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  // If the specifier already carries an extension, only try the exact path.
+  if (/\.[cm]?[jt]sx?$/i.test(specifier)) {
+    return fs.existsSync(base) ? base : undefined;
+  }
+  for (const ext of SOURCE_EXTENSIONS) {
+    const candidate = base + ext;
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  for (const ext of SOURCE_EXTENSIONS) {
+    const candidate = path.join(base, 'index' + ext);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+// Matches `from '...'` specifiers in `import`/`export ... from` statements.
+// Uses a non-greedy body so multi-line imports match cleanly. The negative
+// lookahead skips `import type` / `export type` statements because type-only
+// edges are erased at runtime and can't pull files into a runtime bundle.
+const FROM_SPEC_RE =
+  /(?:^|[\s;}])(?:import|export)\b(?!\s+type\b)[^"';]*?\bfrom\s*["']([^"']+)["']/gm;
+// Matches side-effect imports: `import '...';`.
+const SIDE_EFFECT_IMPORT_RE = /(?:^|[\s;}])import\s*["']([^"']+)["']/gm;
+
+/**
+ * Extract relative module specifiers from a source file's contents.
+ *
+ * @param {string} contents
+ * @returns {string[]}
+ */
+function collectRelativeSpecifiers(contents) {
+  const specs = new Set();
+  for (const m of contents.matchAll(FROM_SPEC_RE)) {
+    if (m[1].startsWith('.')) specs.add(m[1]);
+  }
+  for (const m of contents.matchAll(SIDE_EFFECT_IMPORT_RE)) {
+    if (m[1].startsWith('.')) specs.add(m[1]);
+  }
+  return [...specs];
+}
+
+/**
+ * Walk the relative import/export graph of each entry's source file and build
+ * a map of absolute file paths to the set of entries whose bundles include
+ * them. Files that aren't reachable from any entry (e.g. tests, scripts)
+ * aren't present in the map.
+ *
+ * @param {string} pkgDir
+ * @param {EntryInfo[]} entries
+ * @returns {Map<string, Set<string>>}
+ */
+function buildFileToEntriesMap(pkgDir, entries) {
+  /** @type {Map<string, Set<string>>} */
+  const fileToEntries = new Map();
+  for (const entry of entries) {
+    const sourceFile = path.join(pkgDir, entry.sourceFile);
+    if (!fs.existsSync(sourceFile)) continue;
+    /** @type {Set<string>} */
+    const visited = new Set();
+    const queue = [sourceFile];
+    while (queue.length > 0) {
+      const current = /** @type {string} */ (queue.pop());
+      if (visited.has(current)) continue;
+      visited.add(current);
+
+      let set = fileToEntries.get(current);
+      if (!set) {
+        set = new Set();
+        fileToEntries.set(current, set);
+      }
+      set.add(entry.key);
+
+      let contents;
+      try {
+        contents = fs.readFileSync(current, 'utf8');
+      } catch {
+        continue;
+      }
+
+      for (const spec of collectRelativeSpecifiers(contents)) {
+        const resolved = resolveSourcePath(current, spec);
+        if (resolved) queue.push(resolved);
+      }
+    }
+  }
+  return fileToEntries;
+}
+
+/**
+ * @param {string} pkgDir
+ * @param {EntryInfo[]} entries
+ * @returns {Map<string, Set<string>>}
+ */
+function getFileToEntriesMap(pkgDir, entries) {
+  let cached = bundleCache.get(pkgDir);
+  if (!cached) {
+    cached = buildFileToEntriesMap(pkgDir, entries);
+    bundleCache.set(pkgDir, cached);
+  }
+  return cached;
+}
+
+/**
+ * Find which entry an import targets based on its subpath. Returns undefined
+ * when the import doesn't match any declared entry.
+ *
+ * @param {string} subPath - The part after the package name, without leading slash. Empty for the root entry.
+ * @param {EntryInfo[]} entries
+ * @returns {EntryInfo | undefined}
+ */
+function findEntryForImport(subPath, entries) {
+  const key = subPath ? `./${subPath}` : '.';
+  return entries.find(e => e.key === key);
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    messages: {
+      sameEntrySelfImport:
+        "Do not import from your own package '{{packageName}}'. This causes a circular dependency because '{{entry}}' re-exports this file. Switch to a relative import, or use `import type` if only types are needed (type-only imports are erased at runtime).",
+      crossEntrySelfImport:
+        "Avoid importing from your own package '{{packageName}}' via '{{importPath}}'. Even across entry points this can lead to subtle circular initialization issues. Prefer a relative import, or use `import type` if only types are needed (type-only imports are erased at runtime).",
+    },
+    docs: {
+      description:
+        'Disallow a package from importing itself by its own name, which causes circular initialization issues in bundled ESM.',
+      url: 'https://github.com/backstage/backstage/blob/master/packages/eslint-plugin/docs/rules/no-self-package-imports.md',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowCrossEntry: {
+            type: 'boolean',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const options = context.options[0] || {};
+    const allowCrossEntry = options.allowCrossEntry !== false;
+
+    const packages = getPackages(context.getCwd());
+    const filename = context.getFilename();
+    const selfPkg = packages?.byPath(filename);
+    if (!selfPkg) {
+      return {};
+    }
+    const selfName = selfPkg.packageJson.name;
+    const entries = readEntries(selfPkg.packageJson.exports);
+    const fileToEntries = getFileToEntriesMap(selfPkg.dir, entries);
+    const fileEntries = fileToEntries.get(filename);
+
+    // If the file isn't part of any entry's bundle (tests, scripts, orphans),
+    // a self-package import from it can't create a circular-initialization
+    // problem in a published bundle. Skip.
+    if (!fileEntries || fileEntries.size === 0) {
+      return {};
+    }
+
+    return visitImports(context, (node, imp) => {
+      if (imp.type !== 'internal') return;
+      if (imp.packageName !== selfName) return;
+      // Type-only imports are erased at runtime and can't cause circular init.
+      if (imp.kind === 'type') return;
+      // Importing a non-script asset (e.g. `package.json`) doesn't go through
+      // the module barrel, so it can't cause circular init issues.
+      if (imp.path === 'package.json' || imp.path.endsWith('/package.json')) {
+        return;
+      }
+
+      const importEntry = findEntryForImport(imp.path, entries);
+      if (!importEntry) return;
+
+      const importPath = imp.path ? `${selfName}/${imp.path}` : selfName;
+
+      if (fileEntries.has(importEntry.key)) {
+        context.report({
+          node,
+          messageId: 'sameEntrySelfImport',
+          data: {
+            packageName: selfName,
+            entry: importEntry.key,
+          },
+        });
+        return;
+      }
+
+      if (!allowCrossEntry) {
+        context.report({
+          node,
+          messageId: 'crossEntrySelfImport',
+          data: {
+            packageName: selfName,
+            importPath,
+          },
+        });
+      }
+    });
+  },
+};

package/src/__fixtures__/monorepo/packages/self-import-pkg/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@internal/self-import-pkg",
+  "backstage": {
+    "role": "node-library"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./alpha": "./src/alpha/index.ts",
+    "./testUtils": "./src/testUtils.ts",
+    "./package.json": "./package.json"
+  }
+}

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/alpha/index.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './refs';
+export * from '../shared';
+export * from '../next';
+export type { TypeOnly } from './typeRef';

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/alpha/refs.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const refs = 3;

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/alpha/typeRef.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export type TypeOnly = { value: number };

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/index.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './util';
+export * from './shared';

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/next/foo.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const foo = 4;

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/next/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './foo';

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/orphan.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const orphan = 6;

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/shared.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const shared = 2;

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/testUtils/helper.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const helper = 5;

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/testUtils.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './testUtils/helper';

package/src/__fixtures__/monorepo/packages/self-import-pkg/src/util.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const util = 1;

package/src/no-self-package-imports.test.ts

@@ -0,0 +1,229 @@
+/*
+ * Copyright 2026 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { RuleTester } from 'eslint';
+import path from 'node:path';
+import rule from '../rules/no-self-package-imports';
+
+const RULE = 'no-self-package-imports';
+const FIXTURE = path.resolve(__dirname, '__fixtures__/monorepo');
+const PKG_DIR = path.join(FIXTURE, 'packages/self-import-pkg');
+
+const sameEntryErr = (entry = '.') => ({
+  messageId: 'sameEntrySelfImport',
+  data: { packageName: '@internal/self-import-pkg', entry },
+});
+
+const crossEntryErr = (importPath: string) => ({
+  messageId: 'crossEntrySelfImport',
+  data: { packageName: '@internal/self-import-pkg', importPath },
+});
+
+const origDir = process.cwd();
+afterAll(() => {
+  process.chdir(origDir);
+});
+process.chdir(FIXTURE);
+
+const ruleTester = new RuleTester({
+  parser: require.resolve('@typescript-eslint/parser'),
+  parserOptions: {
+    sourceType: 'module',
+    ecmaVersion: 2021,
+  },
+});
+
+ruleTester.run(RULE, rule, {
+  valid: [
+    // Relative imports are always fine.
+    {
+      code: `import { foo } from './local'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    // Imports of other packages are unaffected.
+    {
+      code: `import { foo } from '@internal/bar'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    {
+      code: `import { foo } from 'react'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    // `src/alpha/refs.ts` is only in the `./alpha` bundle; importing from the
+    // root entry `.` is a cross-entry reference, which is allowed by default.
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/alpha/refs.ts'),
+    },
+    // `src/index.ts` is only in the `.` bundle; importing from `./alpha` is
+    // cross-entry.
+    {
+      code: `import { foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg/testUtils'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    // `src/next/foo.ts` is physically under `src/` but only re-exported from
+    // `./alpha` (via `src/alpha/index.ts` → `../next`). The rule follows the
+    // actual barrel graph rather than the directory layout, so importing
+    // from the root entry is correctly classified as cross-entry.
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/next/foo.ts'),
+    },
+    // `package.json` imports are exempt since they don't go through the
+    // module barrel.
+    {
+      code: `import pkg from '@internal/self-import-pkg/package.json'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    // Files that aren't reachable from any entry (tests, scripts, orphans)
+    // can't cause circular-init errors in the published bundle, so they're
+    // skipped entirely.
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/index.test.ts'),
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/index.test.ts'),
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/orphan.ts'),
+    },
+    // Dynamic imports in a test file still count as orphan, since the test
+    // file itself isn't part of any entry's bundle.
+    {
+      code: `const m = import('@internal/self-import-pkg')`,
+      filename: path.join(PKG_DIR, 'src/alpha/refs.test.ts'),
+    },
+    // `import type` is erased at runtime and can't create circular
+    // initialization issues, so it's always allowed.
+    {
+      code: `import type { Foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    {
+      code: `import type { Foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/alpha/refs.ts'),
+    },
+    // `export type { ... } from` is also a type-only statement: the TS AST
+    // marks it with `exportKind: 'type'`, and the emitted JS has no runtime
+    // edge. Both same-entry and cross-entry forms must be skipped.
+    {
+      code: `export type { Foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+    },
+    {
+      code: `export type { Foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/alpha/refs.ts'),
+    },
+    // `src/alpha/typeRef.ts` is only reachable from the `./alpha` barrel via
+    // an `export type { ... } from './typeRef'` edge. Since type-only edges
+    // are erased at runtime, the file isn't part of any entry's bundle and
+    // self-imports from it must be skipped as orphans.
+    {
+      code: `import { foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/alpha/typeRef.ts'),
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/alpha/typeRef.ts'),
+    },
+  ],
+  invalid: [
+    // Same-entry self-imports are always errors because they create circular
+    // module graphs inside a bundle.
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+      errors: [sameEntryErr('.')],
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/util.ts'),
+      errors: [sameEntryErr('.')],
+    },
+    {
+      code: `export { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+      errors: [sameEntryErr('.')],
+    },
+    {
+      code: `const x = require('@internal/self-import-pkg')`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+      errors: [sameEntryErr('.')],
+    },
+    {
+      code: `const m = import('@internal/self-import-pkg')`,
+      filename: path.join(PKG_DIR, 'src/util.ts'),
+      errors: [sameEntryErr('.')],
+    },
+    // Files in a non-root entry's bundle importing that same entry are
+    // flagged.
+    {
+      code: `import { foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/alpha/refs.ts'),
+      errors: [sameEntryErr('./alpha')],
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg/testUtils'`,
+      filename: path.join(PKG_DIR, 'src/testUtils.ts'),
+      errors: [sameEntryErr('./testUtils')],
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg/testUtils'`,
+      filename: path.join(PKG_DIR, 'src/testUtils/helper.ts'),
+      errors: [sameEntryErr('./testUtils')],
+    },
+    // `src/next/foo.ts` is actually in the `./alpha` bundle via barrel
+    // re-exports, so importing `./alpha` from it is same-entry — even though
+    // the directory layout might suggest otherwise.
+    {
+      code: `import { foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/next/foo.ts'),
+      errors: [sameEntryErr('./alpha')],
+    },
+    // `src/shared.ts` is re-exported by both the root and alpha entries, so
+    // either target is same-entry.
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/shared.ts'),
+      errors: [sameEntryErr('.')],
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/shared.ts'),
+      errors: [sameEntryErr('./alpha')],
+    },
+    // With `allowCrossEntry: false`, cross-entry imports are also flagged.
+    {
+      code: `import { foo } from '@internal/self-import-pkg'`,
+      filename: path.join(PKG_DIR, 'src/alpha/refs.ts'),
+      options: [{ allowCrossEntry: false }],
+      errors: [crossEntryErr('@internal/self-import-pkg')],
+    },
+    {
+      code: `import { foo } from '@internal/self-import-pkg/alpha'`,
+      filename: path.join(PKG_DIR, 'src/index.ts'),
+      options: [{ allowCrossEntry: false }],
+      errors: [crossEntryErr('@internal/self-import-pkg/alpha')],
+    },
+  ],
+});