@bpmn-io/codemods 0.1.0 → 0.2.0

package/esm/README.md

@@ -23,11 +23,19 @@ npx @bpmn-io/codemods esm <dir|file>
 
 # preview without writing
 npx @bpmn-io/codemods esm --dry-run src
+
+# only rewrite imports of specific packages
+npx @bpmn-io/codemods esm src --package diagram-js --package bpmn-js
 ```
 
 Run it from your project root so that `node_modules` (the installed,
 already-migrated package) is reachable for resolution.
 
+When one or more `--package` (`-p`) options are given, only imports of those
+packages are rewritten — relative imports and imports of other packages are
+left untouched (and not reported as unresolved). This is useful for migrating
+one dependency at a time, e.g. when only `diagram-js` has gone "ESM only".
+
 The command exits with code `1` if any import could not be resolved, so it can
 be used as a CI guard.
 
@@ -36,17 +44,17 @@ be used as a CI guard.
 For every `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts` and `.tsx` file below the target
 (ignoring `node_modules` and `.git`):
 
-1. Each static `import` / `export ... from` source, and every dynamic
-   `import('...')` call with a string-literal argument, is checked against ES
-   module resolution.
-2. If the specifier does not resolve as written but does once an extension is
+1. Collect static `import` / `export ... from` source, and every dynamic
+   `import('...')` call with a string-literal argument - filter by (optional) `package` filters
+2. Matching imports are checked against ES module resolution.
+3. If the specifier does not resolve as written but does once an extension is
    appended, the extension is added.
    - Relative and bare (`node_modules`) specifiers are both handled.
    - TypeScript / JSX sources are written with a `.js` specifier (NodeNext
      convention), even though the file on disk is `.ts`/`.tsx`.
-3. Specifiers that already carry an extension, and bare package roots
+4. Specifiers that already carry an extension, and bare package roots
    (e.g. `diagram-js`, `react`), are left untouched.
-4. Anything that still cannot be resolved (e.g. a directory import that would
+5. Anything that still cannot be resolved (e.g. a directory import that would
    need `/index.js`, or a genuinely missing file) is **reported** for manual
    review — never silently changed.
 

package/esm/lib/cli.js

@@ -9,8 +9,10 @@ native ES module resolution (e.g. when migrating to a package that ships
 "ESM only", such as diagram-js).
 
 Options:
-  -d, --dry-run   Report changes without writing files
-  -h, --help      Show this help
+  -p, --package <name>   Only rewrite imports of this package (repeatable);
+                         when given, relative and other packages are left alone
+  -d, --dry-run          Report changes without writing files
+  -h, --help             Show this help
 
 Exit code is 1 when any import could not be resolved.
 `;
@@ -21,23 +23,75 @@ Exit code is 1 when any import could not be resolved.
  * @param {string[]} argv - arguments after the mod name
  */
 export function run(argv) {
-  const dryRun = argv.includes('--dry-run') || argv.includes('-d');
-  const help = argv.includes('--help') || argv.includes('-h');
+  let options;
+
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\n${HELP}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const { help, dryRun, packages, target } = options;
 
   if (help) {
     process.stdout.write(HELP);
     return;
   }
 
-  const target = argv.find((arg) => !arg.startsWith('-')) || process.cwd();
-
-  const report = migrate(target, { dryRun });
+  const report = migrate(target, { dryRun, packages });
 
   print(report, dryRun);
 
   process.exitCode = report.unresolved.length || report.errors.length ? 1 : 0;
 }
 
+/**
+ * Parse the `esm` mod CLI arguments.
+ *
+ * @param {string[]} argv
+ *
+ * @return {{ help: boolean, dryRun: boolean, packages: string[], target: string }}
+ *
+ * @throws {Error} on invalid usage, e.g. a `--package` without a name
+ */
+export function parseArgs(argv) {
+  const options = { help: false, dryRun: false, packages: [], target: null };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--dry-run' || arg === '-d') {
+      options.dryRun = true;
+    } else if (arg === '--package' || arg === '-p') {
+      options.packages.push(requirePackage(arg, argv[++i]));
+    } else if (arg.startsWith('--package=')) {
+      options.packages.push(requirePackage('--package', arg.slice('--package='.length)));
+    } else if (!arg.startsWith('-') && options.target === null) {
+      options.target = arg;
+    }
+  }
+
+  options.target = options.target || process.cwd();
+
+  return options;
+}
+
+/**
+ * Guard against a `--package` option that is missing its value or accidentally
+ * swallowed a following flag (e.g. `-p -d`).
+ */
+function requirePackage(flag, value) {
+  if (!value || value.startsWith('-')) {
+    throw new Error(`Option ${flag} requires a package name, got: ${value ?? '(none)'}`);
+  }
+
+  return value;
+}
+
 function print(report, dryRun) {
   const rel = (file) => path.relative(process.cwd(), file) || file;
 

package/esm/lib/migrate.js

@@ -22,12 +22,13 @@ const IGNORED_DIRECTORIES = new Set([ 'node_modules', '.git' ]);
  * under native ES module resolution.
  *
  * @param {string} target - directory or file to migrate
- * @param {{ dryRun?: boolean }} [options]
+ * @param {{ dryRun?: boolean, packages?: string[] }} [options] - when
+ *   `packages` is non-empty, only imports of those packages are rewritten
  *
  * @return {Report}
  */
 export function migrate(target, options = {}) {
-  const { dryRun = false } = options;
+  const { dryRun = false, packages = [] } = options;
 
   const report = {
     filesScanned: 0,
@@ -42,7 +43,7 @@ export function migrate(target, options = {}) {
     report.filesScanned++;
 
     const code = fs.readFileSync(file, 'utf8');
-    const result = transform(code, file);
+    const result = transform(code, file, { packages });
 
     if (result.error) {
       report.errors.push({ file, message: result.error.message });

package/esm/lib/resolve.js

@@ -47,14 +47,21 @@ const BARE_CANDIDATES = [
  *
  * @param {string} specifier - the raw import source, e.g. `diagram-js/lib/util/Elements`
  * @param {string} fromFile - absolute path of the importing file
+ * @param {{ packages?: string[] }} [options] - if `packages` is non-empty, only
+ *   imports of those packages are considered; everything else is skipped
  *
  * @return {{ status: ('skip'|'rewrite'|'unresolved'), specifier: string }}
- *   `skip` if already resolvable, `rewrite` with the new specifier if an
+ *   `skip` if already resolvable or filtered out by `options.packages`, `rewrite` with the new specifier if an
  *   extension was appended, `unresolved` if no `.js`-style extension resolves.
  */
-export function resolveImport(specifier, fromFile) {
+export function resolveImport(specifier, fromFile, options = {}) {
   const bare = isBare(specifier);
 
+  // when restricted to specific packages, only their (bare) imports apply
+  if (options.packages && options.packages.length && !targetsPackage(specifier, bare, options.packages)) {
+    return { status: 'skip', specifier };
+  }
+
   // bare package roots (e.g. 'react', 'diagram-js') resolve via main/exports
   if (bare && isBareRoot(specifier)) {
     return { status: 'skip', specifier };
@@ -153,6 +160,13 @@ function isBareRoot(specifier) {
   return parseBare(specifier).subpath === '';
 }
 
+/**
+ * Whether the specifier imports from one of the given packages.
+ */
+function targetsPackage(specifier, bare, packages) {
+  return bare && packages.includes(parseBare(specifier).pkg);
+}
+
 function specifierExtension(specifier) {
   const segment = specifier.split('/').pop();
   const dot = segment.lastIndexOf('.');

package/esm/lib/transform.js

@@ -13,6 +13,7 @@ import { resolveImport } from './resolve.js';
  *
  * @param {string} code - the file contents
  * @param {string} filename - absolute path of the file (used for resolution)
+ * @param {{ packages?: string[] }} [options] - passed through to the resolver
  *
  * @return {{
  *   code: string,
@@ -22,7 +23,7 @@ import { resolveImport } from './resolve.js';
  *   error: (Error|null)
  * }}
  */
-export function transform(code, filename) {
+export function transform(code, filename, options = {}) {
   let ast;
 
   try {
@@ -40,7 +41,7 @@ export function transform(code, filename) {
   const unresolved = [];
 
   for (const source of importSources(ast)) {
-    const result = resolveImport(source.value, filename);
+    const result = resolveImport(source.value, filename, options);
     const line = source.loc.start.line;
 
     if (result.status === 'rewrite') {

package/package.json

@@ -1,11 +1,25 @@
 {
   "name": "@bpmn-io/codemods",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A collection of codemods for the bpmn.io ecosystem.",
   "type": "module",
   "bin": {
     "codemods": "bin/codemods.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bpmn-io/diagram-js"
+  },
+  "author": {
+    "name": "Nico Rehwaldt",
+    "url": "https://github.com/nikku"
+  },
+  "contributors": [
+    {
+      "name": "bpmn.io contributors",
+      "url": "https://github.com/bpmn-io"
+    }
+  ],
   "scripts": {
     "all": "npm run test",
     "test": "mocha"
@@ -26,7 +40,7 @@
     "@babel/parser": "^7.24.0"
   },
   "devDependencies": {
-    "chai": "^5.1.0",
-    "mocha": "^10.4.0"
+    "chai": "^6.2.2",
+    "mocha": "^11.7.6"
   }
 }