ESLint: Add custom rule to detect cross package imports (#17029)

This has come up a few times recently, where despite our best efforts to
configure VSCode quick fixes, it can still end up adding cross package
relative imports, which cause build and/or runtime errors that are hard
to understand and diagnose. This change introduces a new custom ESLint
plugin (thanks Claude!) that detects when this happens and uses the path
mappings from our tsconfig.json to suggest a corrected import:

<img width="818" height="130" alt="image"
src="https://github.com/user-attachments/assets/b1db607e-4f50-4e43-94f2-3471e6a558eb"
/>

<img width="745" height="304" alt="image"
src="https://github.com/user-attachments/assets/7ace3e76-479f-46e1-93e4-7d463a852d3f"
/>

<img width="436" height="93" alt="image"
src="https://github.com/user-attachments/assets/637cfae9-e7cc-4c2d-9740-21aa43b57a75"
/>

Author: ryantrem

.eslintrc.js

@@ -600,6 +600,7 @@ const rules = {
         "no-async-promise-executor": "warn",
         "no-throw-literal": "error",
         curly: "error",
+        "babylonjs/no-cross-package-relative-imports": "error",
     },
 };
 

packages/tools/eslintBabylonPlugin/src/index.ts

@@ -6,6 +6,8 @@ import { TSDocConfiguration, TSDocParser, TextRange } from "@microsoft/tsdoc";
 import * as tsdoc from "@microsoft/tsdoc";
 import type { TSDocConfigFile } from "@microsoft/tsdoc-config";
 import * as ts from "typescript";
+import * as fs from "fs";
+import * as path from "path";
 
 // import { Debug } from "./Debug";
 import { ConfigCache } from "./ConfigCache";
@@ -141,6 +143,68 @@ function walkCompilerAstAndFindComments(node: ts.Node, indent: string, notFoundC
     return node.forEachChild((child) => walkCompilerAstAndFindComments(child, indent + "  ", notFoundComments, sourceText, getterSetterFound));
 }
 
+type TsConfig = {
+    compilerOptions: {
+        baseUrl: string;
+        paths: Record<string, string[]>;
+    };
+};
+
+let tsConfig: TsConfig | null = null;
+function loadTsConfig(projectRoot: string): TsConfig | null {
+    if (tsConfig) {
+        return tsConfig;
+    }
+
+    try {
+        const tsconfigPath = path.join(projectRoot, "tsconfig.json");
+        const tsconfigContent = fs.readFileSync(tsconfigPath, "utf8");
+        // Remove comments and parse JSON
+        const cleanJson = tsconfigContent.replace(/\/\*[\s\S]*?\*\/|\/\/.*$/gm, "");
+        tsConfig = JSON.parse(cleanJson);
+    } catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn(`BabylonJS custom eslint plugin failed to load tsconfig.json: ${error.message}`);
+    }
+
+    return tsConfig;
+}
+
+function shouldUsePathMapping(importPath: string, filename: string, tsConfig: TsConfig) {
+    if (!importPath.startsWith("../") || !tsConfig?.compilerOptions?.paths) {
+        return null;
+    }
+
+    const { baseUrl = ".", paths } = tsConfig.compilerOptions;
+    const projectRoot = path.dirname(path.join(path.dirname(filename), "..", "..", ".."));
+
+    // Resolve the relative import to an absolute path
+    const resolvedImportPath = path.resolve(path.dirname(filename), importPath);
+
+    // Check if this resolved path matches any of the path mappings
+    for (const [pathKey, pathValues] of Object.entries(paths)) {
+        for (const pathValue of pathValues) {
+            // Convert tsconfig path to absolute path
+            const absolutePathPattern = path.resolve(projectRoot, baseUrl, pathValue);
+
+            // Check if the resolved import matches this path mapping
+            if (resolvedImportPath.startsWith(absolutePathPattern.replace("*", ""))) {
+                // Calculate what the import should be
+                const relativePart = path.relative(absolutePathPattern.replace("*", ""), resolvedImportPath);
+
+                const suggestedImport = pathKey
+                    .replace("*", relativePart)
+                    .replace(/\\/g, "/") // Normalize to forward slashes
+                    .replace(/\.(ts|tsx)$/, ""); // Remove extension
+
+                return suggestedImport;
+            }
+        }
+    }
+
+    return null;
+}
+
 const plugin: IPlugin = {
     rules: {
         // NOTE: The actual ESLint rule name will be "tsdoc/syntax".  It is calculated by deleting "eslint-plugin-"
@@ -388,6 +452,49 @@ const plugin: IPlugin = {
                 };
             },
         },
+        "no-cross-package-relative-imports": {
+            meta: {
+                type: "problem",
+                docs: {
+                    description: "Prevent relative imports that should use TypeScript path mappings",
+                },
+                fixable: "code",
+                messages: {
+                    usePathMapping: 'Use path mapping "{{suggestion}}" instead of relative import "{{importPath}}".',
+                },
+            },
+            create(context) {
+                return {
+                    Program() {
+                        // Load tsconfig once per file
+                        const filename = context.filename;
+                        const projectRoot = filename.split("packages")[0];
+                        tsConfig = loadTsConfig(projectRoot);
+                    },
+
+                    ImportDeclaration(node) {
+                        const importPath = node.source.value as string;
+                        const filename = context.filename;
+
+                        const suggestion = shouldUsePathMapping(importPath, filename, tsConfig!);
+
+                        if (suggestion) {
+                            context.report({
+                                node,
+                                messageId: "usePathMapping",
+                                data: {
+                                    importPath,
+                                    suggestion,
+                                },
+                                fix(fixer) {
+                                    return fixer.replaceText(node.source, `"${suggestion}"`);
+                                },
+                            });
+                        }
+                    },
+                };
+            },
+        },
     },
 };