react19-compat-linter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Scott Mikula
+
+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,55 @@
+# react19-compat-linter
+
+React 19 removes several deprecated APIs that were available in React 18 and earlier (`ReactDOM.render`, `findDOMNode`, etc.)  Before upgrading to React 19, you need to remove these from your code—you might use a lint rule for this.  But you also need to make sure that _all bundled dependencies_ are clean—and this problem is much harder.
+
+This package solves this by providing a utility to scan your dependencies to identify compatibility issues.  At a high level, it is composed of two parts: (1) a webpack plugin that emits a list of modules to lint, and (2) a utility that runs ESLint over those modules and reports on incompatible packages.
+
+> **Why split the functionality like this?**  While webpack is the most common bundler, you may be using something else.  By decoupling the linting from the bundler, you can produce your own module list and still reuse the linting functionality.  And linting is slow; you may want to separate it from your webpack process anyway.
+
+## Getting Started
+
+### 1. Install the package
+
+```bash
+# NPM
+npm install --save-dev react19-compat-linter
+
+# Yarn
+yarn add --dev react19-compat-linter
+```
+
+### 2. Configure the webpack plugin
+
+Add the `DependencyModuleListPlugin` to your webpack configuration to extract a list of all modules used in your build:
+
+```javascript
+const { DependencyModuleListPlugin } = require('react19-compat-linter');
+const outputFile = './modules-list.json';
+
+module.exports = {
+  // ... your webpack config
+  plugins: [
+    new DependencyModuleListPlugin(outputFile)
+  ]
+};
+```
+
+When you run webpack, this plugin will generate a JSON file containing all bundled JavaScript (or TypeScript) modules from packages in the `node_modules` directory.
+
+### 3. Run the linter
+
+You can run the linter via the command line:
+
+```bash
+npm react19-compat-linter ./modules-list.json
+```
+
+Or integrate it into your build via the API:
+
+```javascript
+const { runLinter } = require('react19-compat-linter');
+
+runLinter('./modules-list.json').then(result => {
+  console.log(`Found violations in ${result.packages.length} packages.`);
+});
+```

package/bin/react19-compat-linter.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { cli } = require('../lib/cli');
+
+cli(process.argv.slice(2));

package/lib/DependencyModuleListPlugin.d.ts

@@ -0,0 +1,6 @@
+import webpack from 'webpack';
+export declare class DependencyModuleListPlugin {
+    private filePath;
+    constructor(filePath: string);
+    apply(compiler: webpack.Compiler): void;
+}

package/lib/DependencyModuleListPlugin.js

@@ -0,0 +1,44 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyModuleListPlugin = void 0;
+const webpack_1 = require("webpack");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+class DependencyModuleListPlugin {
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    apply(compiler) {
+        compiler.hooks.thisCompilation.tap('DependencyModuleListPlugin', compilation => {
+            compilation.hooks.processAssets.tapPromise({
+                name: 'DependencyModuleListPlugin',
+                stage: webpack_1.Compilation.PROCESS_ASSETS_STAGE_REPORT,
+            }, () => __awaiter(this, void 0, void 0, function* () {
+                const modules = [];
+                for (const module of compilation.modules) {
+                    const resource = module.resource;
+                    if (resource && shouldIncludeModule(resource)) {
+                        modules.push(resource);
+                    }
+                }
+                const jsonContent = JSON.stringify(modules, null, 2);
+                yield (0, promises_1.mkdir)((0, path_1.dirname)(this.filePath), { recursive: true });
+                yield (0, promises_1.writeFile)(this.filePath, jsonContent, 'utf-8');
+            }));
+        });
+    }
+}
+exports.DependencyModuleListPlugin = DependencyModuleListPlugin;
+const jsExtensions = /\.(js|jsx|ts|tsx|mjs|cjs)$/i;
+function shouldIncludeModule(resource) {
+    return jsExtensions.test(resource) && resource.includes('node_modules');
+}

package/lib/cli.d.ts

@@ -0,0 +1 @@
+export declare function cli(args: string[]): Promise<void>;

package/lib/cli.js

@@ -0,0 +1,42 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cli = cli;
+const runLinter_1 = require("./runLinter");
+function cli(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (args.length === 0) {
+            console.error('Error: Please provide the path to the modules list file');
+            console.error('Usage: react19-compat-linter <modules-list.json>');
+            process.exit(1);
+        }
+        const modulesListPath = args[0];
+        try {
+            const result = yield (0, runLinter_1.runLinter)(modulesListPath);
+            console.log(`Found violations in ${result.packages.length} packages:\n`);
+            result.packages.forEach(pkg => {
+                console.log(`${pkg.packageName} (${pkg.files.length} files):`);
+                pkg.files.forEach(file => {
+                    console.log(`  ${file.filePath}:`);
+                    file.violations.forEach(violation => {
+                        console.log(`    ${violation.line}:${violation.column} - ${violation.message}`);
+                    });
+                });
+                console.log('');
+            });
+            process.exit(0);
+        }
+        catch (error) {
+            console.error('Error running linter:', error);
+            process.exit(1);
+        }
+    });
+}

package/lib/eslint.config.d.ts

@@ -0,0 +1,13 @@
+declare const _default: {
+    plugins: {
+        'react19-compat-linter': {
+            rules: {
+                'no-restricted-imports': any;
+            };
+        };
+    };
+    rules: {
+        'react19-compat-linter/no-restricted-imports': "error";
+    };
+}[];
+export = _default;

package/lib/eslint.config.js

@@ -0,0 +1,17 @@
+"use strict";
+const no_restricted_imports_1 = require("./no-restricted-imports");
+module.exports = [
+    {
+        plugins: {
+            'react19-compat-linter': {
+                rules: {
+                    // Cast to `any` because the rule type from @typescript-eslint/utils doesn't quite match
+                    'no-restricted-imports': no_restricted_imports_1.noRestrictedImports,
+                },
+            },
+        },
+        rules: {
+            'react19-compat-linter/no-restricted-imports': 'error',
+        },
+    },
+];

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { DependencyModuleListPlugin } from './DependencyModuleListPlugin';
+export { runLinter } from './runLinter';
+export type { LinterResult, LinterPackageResult, LinterFileResult, LinterViolation } from './types';

package/lib/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLinter = exports.DependencyModuleListPlugin = void 0;
+var DependencyModuleListPlugin_1 = require("./DependencyModuleListPlugin");
+Object.defineProperty(exports, "DependencyModuleListPlugin", { enumerable: true, get: function () { return DependencyModuleListPlugin_1.DependencyModuleListPlugin; } });
+var runLinter_1 = require("./runLinter");
+Object.defineProperty(exports, "runLinter", { enumerable: true, get: function () { return runLinter_1.runLinter; } });

package/lib/no-restricted-imports.d.ts

@@ -0,0 +1,9 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const noRestrictedImports: ESLintUtils.RuleModule<"restrictedImport" | "restrictedNamespaceAccess" | "restrictedDestructuring", [{
+    restrictedImports: {
+        module: string;
+        imports: string[];
+    }[];
+}], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/lib/no-restricted-imports.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noRestrictedImports = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+exports.noRestrictedImports = utils_1.ESLintUtils.RuleCreator(f => f)({
+    name: 'no-restricted-imports',
+    meta: {
+        type: 'problem',
+        messages: {
+            restrictedImport: 'Importing {{importName}} from "{{moduleName}}" is not allowed.',
+            restrictedNamespaceAccess: 'Accessing {{importName}} from {{namespace}} is not allowed.',
+            restrictedDestructuring: 'Destructuring {{importName}} from {{namespace}} is not allowed.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    restrictedImports: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                module: {
+                                    type: 'string',
+                                },
+                                imports: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'string',
+                                    },
+                                },
+                            },
+                            required: ['module', 'imports'],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                additionalProperties: false,
+                required: ['restrictedImports'],
+            },
+        ],
+        docs: {
+            description: 'Restricts specific imports from specified modules.',
+        },
+    },
+    defaultOptions: [
+        {
+            restrictedImports: [
+                {
+                    module: 'react-dom',
+                    imports: ['findDOMNode', 'render', 'unmountComponentAtNode'],
+                },
+            ],
+        },
+    ],
+    create(context, options) {
+        const restrictedImports = options[0].restrictedImports;
+        const namespaceIdentifiers = new Map();
+        return {
+            ImportDeclaration(node) {
+                const moduleName = node.source.value;
+                // Find if this module has any restricted imports
+                const restriction = restrictedImports.find(r => r.module === moduleName);
+                if (!restriction) {
+                    return;
+                }
+                // Check each import specifier
+                node.specifiers.forEach(specifier => {
+                    if (specifier.type === 'ImportSpecifier') {
+                        const importedName = specifier.imported.type === 'Identifier'
+                            ? specifier.imported.name
+                            : specifier.imported.value;
+                        if (restriction.imports.includes(importedName)) {
+                            context.report({
+                                node: specifier,
+                                messageId: 'restrictedImport',
+                                data: {
+                                    importName: importedName,
+                                    moduleName: moduleName,
+                                },
+                            });
+                        }
+                    }
+                    else if (specifier.type === 'ImportDefaultSpecifier' ||
+                        specifier.type === 'ImportNamespaceSpecifier') {
+                        // Track namespace/default imports for this module
+                        // e.g., "import React from 'react'" or "import * as React from 'react'"
+                        namespaceIdentifiers.set(specifier.local.name, moduleName);
+                    }
+                });
+            },
+            MemberExpression(node) {
+                // Check if accessing a restricted import through a namespace identifier
+                // e.g., ReactDOM.render
+                if (node.object.type === 'Identifier' && node.property.type === 'Identifier') {
+                    const namespaceName = node.object.name;
+                    const propertyName = node.property.name;
+                    // Check if this identifier is a tracked namespace
+                    const moduleName = namespaceIdentifiers.get(namespaceName);
+                    if (!moduleName) {
+                        return;
+                    }
+                    // Find if this module has restrictions
+                    const restriction = restrictedImports.find(r => r.module === moduleName);
+                    if (!restriction) {
+                        return;
+                    }
+                    // Check if the accessed property is in the restricted imports list
+                    if (restriction.imports.includes(propertyName)) {
+                        context.report({
+                            node,
+                            messageId: 'restrictedNamespaceAccess',
+                            data: {
+                                importName: propertyName,
+                                namespace: namespaceName,
+                            },
+                        });
+                    }
+                }
+            },
+            VariableDeclarator(node) {
+                // Check for destructuring from a namespace identifier
+                // e.g., const { findDOMNode } = ReactDOM;
+                if (node.id.type === 'ObjectPattern' &&
+                    node.init &&
+                    node.init.type === 'Identifier') {
+                    const namespaceName = node.init.name;
+                    // Check if this identifier is a tracked namespace
+                    const moduleName = namespaceIdentifiers.get(namespaceName);
+                    if (!moduleName) {
+                        return;
+                    }
+                    // Find if this module has restrictions
+                    const restriction = restrictedImports.find(r => r.module === moduleName);
+                    if (!restriction) {
+                        return;
+                    }
+                    // Check each destructured property
+                    node.id.properties.forEach(prop => {
+                        if (prop.type === 'Property' && prop.key.type === 'Identifier') {
+                            const propertyName = prop.key.name;
+                            if (restriction.imports.includes(propertyName)) {
+                                context.report({
+                                    node: prop,
+                                    messageId: 'restrictedDestructuring',
+                                    data: {
+                                        importName: propertyName,
+                                        namespace: namespaceName,
+                                    },
+                                });
+                            }
+                        }
+                    });
+                }
+            },
+        };
+    },
+});

package/lib/runLinter.d.ts

@@ -0,0 +1,2 @@
+import type { LinterResult } from './types';
+export declare function runLinter(modulesList: string): Promise<LinterResult>;

package/lib/runLinter.js

@@ -0,0 +1,89 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLinter = runLinter;
+const eslint_1 = require("eslint");
+const path = __importStar(require("path"));
+const extractPackageName_1 = require("./utils/extractPackageName");
+function runLinter(modulesList) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const eslint = new eslint_1.ESLint({
+            overrideConfigFile: path.resolve(__dirname, './eslint.config.js'),
+            ignorePatterns: ['!**/node_modules/'],
+            concurrency: 'auto',
+        });
+        const allResults = yield eslint.lintFiles(modulesList);
+        // Filter for results containing the react19-compat-linter/no-restricted-imports rule violation
+        const results = allResults
+            .map(result => (Object.assign(Object.assign({}, result), { messages: result.messages.filter(msg => msg.ruleId === 'react19-compat-linter/no-restricted-imports') })))
+            .filter(result => result.messages.length > 0);
+        const files = results.map(result => ({
+            filePath: result.filePath,
+            violations: result.messages.map(msg => ({
+                line: msg.line,
+                column: msg.column,
+                message: msg.message,
+            })),
+        }));
+        // Group files by package
+        const packageMap = new Map();
+        for (const file of files) {
+            const packageName = (0, extractPackageName_1.extractPackageName)(file.filePath);
+            if (!packageMap.has(packageName)) {
+                packageMap.set(packageName, []);
+            }
+            packageMap.get(packageName).push(file);
+        }
+        // Convert to array of package results
+        const packages = Array.from(packageMap.entries()).map(([packageName, files]) => ({
+            packageName,
+            files,
+        }));
+        // Sort packages by name for consistent output
+        packages.sort((a, b) => a.packageName.localeCompare(b.packageName));
+        return {
+            packages,
+        };
+    });
+}

package/lib/types.d.ts

@@ -0,0 +1,16 @@
+export interface LinterViolation {
+    line: number;
+    column: number;
+    message: string;
+}
+export interface LinterFileResult {
+    filePath: string;
+    violations: LinterViolation[];
+}
+export interface LinterPackageResult {
+    packageName: string;
+    files: LinterFileResult[];
+}
+export interface LinterResult {
+    packages: LinterPackageResult[];
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/utils/extractPackageName.d.ts

@@ -0,0 +1 @@
+export declare function extractPackageName(filePath: string): string;

package/lib/utils/extractPackageName.js

@@ -0,0 +1,51 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPackageName = extractPackageName;
+const path = __importStar(require("path"));
+function extractPackageName(filePath) {
+    const parts = filePath.split(path.sep);
+    const nodeModulesIndex = parts.lastIndexOf('node_modules');
+    if (nodeModulesIndex === -1) {
+        throw new Error(`Path does not contain node_modules: ${filePath}`);
+    }
+    // Handle scoped packages (@scope/package-name)
+    const packageParts = parts.slice(nodeModulesIndex + 1);
+    if (packageParts[0].startsWith('@')) {
+        return packageParts.slice(0, 2).join('/');
+    }
+    // Handle regular packages
+    return packageParts[0];
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+    "name": "react19-compat-linter",
+    "version": "1.0.0",
+    "description": "Utility to validate project depedencies are React 19 compatible",
+    "main": "./lib/index.js",
+    "typings": "./lib/index.d.ts",
+    "bin": {
+        "react19-compat-linter": "./bin/react19-compat-linter.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "jest",
+        "prepublishOnly": "yarn test && yarn build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/smikula/react19-compat-linter.git"
+    },
+    "bugs": {
+        "url": "https://github.com/smikula/react19-compat-linter/issues"
+    },
+    "homepage": "https://github.com/smikula/react19-compat-linter#readme",
+    "keywords": [
+        "react",
+        "react19",
+        "compatibility",
+        "linter",
+        "eslint",
+        "webpack",
+        "migration",
+        "deprecated",
+        "react-dom"
+    ],
+    "files": [
+        "lib/",
+        "bin/",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "author": "Scott Mikula <mikula@gmail.com>",
+    "dependencies": {
+        "@typescript-eslint/utils": "^8.54.0",
+        "webpack": "^5.105.0",
+        "webpack-cli": "^6.0.1"
+    },
+    "devDependencies": {
+        "@types/eslint": "^9.6.1",
+        "@types/jest": "^30.0.0",
+        "@types/node": "^22.19.7",
+        "@typescript-eslint/parser": "^8.54.0",
+        "@typescript-eslint/rule-tester": "^8.54.0",
+        "eslint": "^9.39.2",
+        "husky": "^4.3.8",
+        "jest": "^30.2.0",
+        "prettier": "^3.8.1",
+        "pretty-quick": "^4.2.2",
+        "ts-jest": "^29.4.6",
+        "typescript": "^5.9.3"
+    },
+    "license": "MIT",
+    "husky": {
+        "hooks": {
+            "pre-commit": "pretty-quick --staged"
+        }
+    }
+}