@bpmn-io/codemods 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @bpmn-io/codemods
+
+A collection of codemods for the bpmn.io ecosystem, exposed via CLI.
+
+## Usage
+
+```bash
+npx @bpmn-io/codemods <mod> [options]
+
+# e.g.
+npx @bpmn-io/codemods esm --dry-run src
+```
+
+Run a mod with `--help` for its options.
+
+## Available mods
+
+| Mod | Purpose |
+| --- | --- |
+| [`esm`](./esm) | Append explicit extensions to imports so they resolve under native ES module resolution (e.g. migrating to "ESM only" packages such as diagram-js). |
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+`npm test` runs the tests of every mod (`*/test/**/*.spec.js`).
+
+## Adding a mod
+
+> [!NOTE]
+> Each mod lives in its own sub-folder with its own library API and tests and is run through a single CLI.
+
+Create a new sub-folder mirroring [`esm`](./esm):
+
+```
+<mod>/
+  lib/cli.js     # exports `run(argv)` — the CLI handler
+  lib/           # library implementation
+  test/          # *.spec.js + fixtures
+  README.md
+```
+
+Then register it in [bin/codemods.js](./bin/codemods.js):
+
+```js
+import { run as myMod } from '../<mod>/lib/cli.js';
+
+const MODS = {
+  esm,
+  myMod
+};
+```
+
+Add a row to the table above and list `<mod>/lib` in the `files` field of the
+root [package.json](./package.json). Shared dev dependencies (`@babel/parser`,
+`mocha`, `chai`) live at the root.

package/bin/codemods.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { run as esm } from '../esm/lib/cli.js';
+
+/**
+ * Registry of available codemods, keyed by their CLI name.
+ *
+ * Each handler receives the arguments that follow the mod name.
+ *
+ * @type {Record<string, (argv: string[]) => void>}
+ */
+const MODS = {
+  esm
+};
+
+const HELP = `Usage: npx @bpmn-io/codemods <mod> [options]
+
+A collection of codemods for the bpmn.io ecosystem.
+
+Mods:
+${Object.keys(MODS).map((name) => `  ${name}`).join('\n')}
+
+Run a mod with --help for its options, e.g.:
+  npx @bpmn-io/codemods esm --help
+`;
+
+main(process.argv.slice(2));
+
+function main(argv) {
+  const [ mod, ...rest ] = argv;
+
+  if (!mod || mod === '--help' || mod === '-h') {
+    process.stdout.write(HELP);
+    process.exitCode = mod ? 0 : 1;
+    return;
+  }
+
+  const handler = MODS[mod];
+
+  if (!handler) {
+    process.stderr.write(`Unknown mod: ${mod}\n\n${HELP}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  handler(rest);
+}

package/esm/README.md

@@ -0,0 +1,70 @@
+# esm codemod
+
+Appends explicit extensions to `import` / `export ... from` sources and dynamic
+`import('...')` calls so they resolve under **native ES module resolution**.
+
+This is useful when migrating to a package that ships "ESM only". For example,
+[diagram-js](https://github.com/bpmn-io/diagram-js) used to allow extension-less
+deep imports of its utilities; the ESM-only releases require an explicit
+extension:
+
+```diff
+- import { getParents } from 'diagram-js/lib/util/Elements';
++ import { getParents } from 'diagram-js/lib/util/Elements.js';
+```
+
+The mod is not tied to diagram-js — it works for any relative or package import
+whose target file exists once an extension is appended.
+
+## Usage
+
+```bash
+npx @bpmn-io/codemods esm <dir|file>
+
+# preview without writing
+npx @bpmn-io/codemods esm --dry-run src
+```
+
+Run it from your project root so that `node_modules` (the installed,
+already-migrated package) is reachable for resolution.
+
+The command exits with code `1` if any import could not be resolved, so it can
+be used as a CI guard.
+
+## What it does
+
+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
+   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
+   (e.g. `diagram-js`, `react`), are left untouched.
+4. 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.
+
+Only the source string is edited; surrounding formatting is preserved exactly.
+
+## Programmatic API
+
+```js
+import { migrate } from '@bpmn-io/codemods/esm/lib/migrate.js';
+
+const report = migrate('src', { dryRun: true });
+```
+
+### Out of scope
+
+By design, the mod does **not**:
+
+- rewrite `require()` calls,
+- rewrite dynamic imports with a non-literal argument (`import(name)`),
+- add `/index.js` for directory imports,
+- guess at unresolvable imports — these are reported instead.

package/esm/lib/cli.js

@@ -0,0 +1,74 @@
+import path from 'node:path';
+
+import { migrate } from './migrate.js';
+
+const HELP = `Usage: npx @bpmn-io/codemods esm [options] <dir|file>
+
+Append explicit extensions to import/export sources so they resolve under
+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
+
+Exit code is 1 when any import could not be resolved.
+`;
+
+/**
+ * Run the `esm` codemod CLI.
+ *
+ * @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');
+
+  if (help) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const target = argv.find((arg) => !arg.startsWith('-')) || process.cwd();
+
+  const report = migrate(target, { dryRun });
+
+  print(report, dryRun);
+
+  process.exitCode = report.unresolved.length || report.errors.length ? 1 : 0;
+}
+
+function print(report, dryRun) {
+  const rel = (file) => path.relative(process.cwd(), file) || file;
+
+  if (report.rewrites.length) {
+    process.stdout.write(`\n${dryRun ? 'Would rewrite' : 'Rewrote'} imports:\n`);
+
+    for (const { file, from, to, line } of report.rewrites) {
+      process.stdout.write(`  ${rel(file)}:${line}  ${from} -> ${to}\n`);
+    }
+  }
+
+  if (report.unresolved.length) {
+    process.stdout.write('\nCould not resolve (please check manually):\n');
+
+    for (const { file, specifier, line } of report.unresolved) {
+      process.stdout.write(`  ${rel(file)}:${line}  ${specifier}\n`);
+    }
+  }
+
+  if (report.errors.length) {
+    process.stdout.write('\nFailed to parse:\n');
+
+    for (const { file, message } of report.errors) {
+      process.stdout.write(`  ${rel(file)}  ${message}\n`);
+    }
+  }
+
+  process.stdout.write(
+    `\n${report.filesScanned} file(s) scanned, ` +
+    `${report.filesChanged} changed, ` +
+    `${report.importsRewritten} import(s) rewritten, ` +
+    `${report.unresolved.length} unresolved.\n`
+  );
+}

package/esm/lib/migrate.js

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { transform } from './transform.js';
+
+const SOURCE_EXTENSIONS = new Set([ '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx' ]);
+const IGNORED_DIRECTORIES = new Set([ 'node_modules', '.git' ]);
+
+/**
+ * @typedef {Object} Report
+ * @property {number} filesScanned
+ * @property {number} filesChanged
+ * @property {number} importsRewritten
+ * @property {Array<{ file: string, from: string, to: string, line: number }>} rewrites
+ * @property {Array<{ file: string, specifier: string, line: number }>} unresolved
+ * @property {Array<{ file: string, message: string }>} errors
+ */
+
+/**
+ * Recursively migrate all JS/TS files below `target` (or a single file),
+ * appending explicit extensions to imports that would otherwise not resolve
+ * under native ES module resolution.
+ *
+ * @param {string} target - directory or file to migrate
+ * @param {{ dryRun?: boolean }} [options]
+ *
+ * @return {Report}
+ */
+export function migrate(target, options = {}) {
+  const { dryRun = false } = options;
+
+  const report = {
+    filesScanned: 0,
+    filesChanged: 0,
+    importsRewritten: 0,
+    rewrites: [],
+    unresolved: [],
+    errors: []
+  };
+
+  for (const file of collectFiles(path.resolve(target))) {
+    report.filesScanned++;
+
+    const code = fs.readFileSync(file, 'utf8');
+    const result = transform(code, file);
+
+    if (result.error) {
+      report.errors.push({ file, message: result.error.message });
+      continue;
+    }
+
+    for (const u of result.unresolved) {
+      report.unresolved.push({ file, ...u });
+    }
+
+    if (result.changed) {
+      report.filesChanged++;
+      report.importsRewritten += result.changes.length;
+
+      for (const c of result.changes) {
+        report.rewrites.push({ file, ...c });
+      }
+
+      if (!dryRun) {
+        fs.writeFileSync(file, result.code);
+      }
+    }
+  }
+
+  return report;
+}
+
+function* collectFiles(target) {
+  const stat = fs.statSync(target);
+
+  if (stat.isFile()) {
+    yield target;
+    return;
+  }
+
+  for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+    const full = path.join(target, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRECTORIES.has(entry.name)) {
+        yield* collectFiles(full);
+      }
+    } else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+      yield full;
+    }
+  }
+}

package/esm/lib/resolve.js

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Extensions that, when already present on a specifier, mean the import is
+ * explicit and must be left untouched (module sources as well as assets that
+ * are handled by bundlers, never by ES module resolution).
+ */
+const KNOWN_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.json', '.node',
+  '.css', '.scss', '.sass', '.less', '.styl',
+  '.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.wasm',
+  '.html', '.xml', '.md', '.txt', '.vue', '.bpmn', '.dmn', '.form'
+]);
+
+/**
+ * Extensions tried for relative imports, in priority order, mapped to the
+ * extension that should be written into the specifier.
+ *
+ * TypeScript / JSX source files are resolved with `.js` specifiers (the
+ * NodeNext / "ESM only" convention), even though the file on disk is `.ts`.
+ */
+const RELATIVE_CANDIDATES = [
+  { file: '.js', write: '.js' },
+  { file: '.jsx', write: '.js' },
+  { file: '.ts', write: '.js' },
+  { file: '.tsx', write: '.js' },
+  { file: '.mjs', write: '.mjs' },
+  { file: '.cjs', write: '.cjs' },
+  { file: '.json', write: '.json' }
+];
+
+/**
+ * Extensions tried for bare (node_modules) imports. Published packages ship
+ * compiled files, so we only look for runtime extensions.
+ */
+const BARE_CANDIDATES = [
+  { file: '.js', write: '.js' },
+  { file: '.mjs', write: '.mjs' },
+  { file: '.cjs', write: '.cjs' },
+  { file: '.json', write: '.json' }
+];
+
+/**
+ * Decide how a single import specifier should be migrated for native ES
+ * module resolution.
+ *
+ * @param {string} specifier - the raw import source, e.g. `diagram-js/lib/util/Elements`
+ * @param {string} fromFile - absolute path of the importing file
+ *
+ * @return {{ status: ('skip'|'rewrite'|'unresolved'), specifier: string }}
+ *   `skip` if already resolvable, `rewrite` with the new specifier if an
+ *   extension was appended, `unresolved` if no `.js`-style extension resolves.
+ */
+export function resolveImport(specifier, fromFile) {
+  const bare = isBare(specifier);
+
+  // bare package roots (e.g. 'react', 'diagram-js') resolve via main/exports
+  if (bare && isBareRoot(specifier)) {
+    return { status: 'skip', specifier };
+  }
+
+  // already carries an explicit extension
+  if (KNOWN_EXTENSIONS.has(specifierExtension(specifier))) {
+    return { status: 'skip', specifier };
+  }
+
+  const rewritten = bare
+    ? resolveBare(specifier, fromFile)
+    : resolveRelative(specifier, fromFile);
+
+  if (rewritten) {
+    return { status: 'rewrite', specifier: rewritten };
+  }
+
+  return { status: 'unresolved', specifier };
+}
+
+function resolveRelative(specifier, fromFile) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+
+  return resolveCandidates(base, specifier, RELATIVE_CANDIDATES);
+}
+
+function resolveBare(specifier, fromFile) {
+  const { pkg, subpath } = parseBare(specifier);
+
+  const pkgDir = findPackageDir(pkg, path.dirname(fromFile));
+
+  if (!pkgDir) {
+    return null;
+  }
+
+  return resolveCandidates(path.join(pkgDir, subpath), specifier, BARE_CANDIDATES);
+}
+
+function resolveCandidates(basePath, specifier, candidates) {
+  for (const { file, write } of candidates) {
+    if (isFile(basePath + file)) {
+      return specifier + write;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Locate a package directory by walking up the `node_modules` chain, starting
+ * from the importing file's directory.
+ */
+function findPackageDir(pkg, fromDir) {
+  let dir = fromDir;
+
+  for (;;) {
+    const candidate = path.join(dir, 'node_modules', pkg);
+
+    if (isDirectory(candidate)) {
+      return candidate;
+    }
+
+    const parent = path.dirname(dir);
+
+    if (parent === dir) {
+      return null;
+    }
+
+    dir = parent;
+  }
+}
+
+function parseBare(specifier) {
+  if (specifier.startsWith('@')) {
+    const parts = specifier.split('/');
+
+    return {
+      pkg: parts.slice(0, 2).join('/'),
+      subpath: parts.slice(2).join('/')
+    };
+  }
+
+  const idx = specifier.indexOf('/');
+
+  return idx === -1
+    ? { pkg: specifier, subpath: '' }
+    : { pkg: specifier.slice(0, idx), subpath: specifier.slice(idx + 1) };
+}
+
+function isBare(specifier) {
+  return !specifier.startsWith('.') && !specifier.startsWith('/');
+}
+
+function isBareRoot(specifier) {
+  return parseBare(specifier).subpath === '';
+}
+
+function specifierExtension(specifier) {
+  const segment = specifier.split('/').pop();
+  const dot = segment.lastIndexOf('.');
+
+  return dot <= 0 ? '' : segment.slice(dot).toLowerCase();
+}
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDirectory(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/esm/lib/transform.js

@@ -0,0 +1,151 @@
+import path from 'node:path';
+
+import { parse } from '@babel/parser';
+
+import { resolveImport } from './resolve.js';
+
+/**
+ * Rewrite the import/export sources of a single file so that they resolve
+ * under native ES module resolution.
+ *
+ * Only the source string literals are touched; the rest of the file is left
+ * byte-for-byte unchanged.
+ *
+ * @param {string} code - the file contents
+ * @param {string} filename - absolute path of the file (used for resolution)
+ *
+ * @return {{
+ *   code: string,
+ *   changed: boolean,
+ *   changes: Array<{ from: string, to: string, line: number }>,
+ *   unresolved: Array<{ specifier: string, line: number }>,
+ *   error: (Error|null)
+ * }}
+ */
+export function transform(code, filename) {
+  let ast;
+
+  try {
+    ast = parse(code, {
+      sourceType: 'module',
+      allowReturnOutsideFunction: true,
+      plugins: pluginsFor(filename)
+    });
+  } catch (error) {
+    return { code, changed: false, changes: [], unresolved: [], error };
+  }
+
+  const edits = [];
+  const changes = [];
+  const unresolved = [];
+
+  for (const source of importSources(ast)) {
+    const result = resolveImport(source.value, filename);
+    const line = source.loc.start.line;
+
+    if (result.status === 'rewrite') {
+      const quote = code[source.start];
+
+      edits.push({
+        start: source.start,
+        end: source.end,
+        text: quote + result.specifier + quote
+      });
+
+      changes.push({ from: source.value, to: result.specifier, line });
+    } else if (result.status === 'unresolved') {
+      unresolved.push({ specifier: source.value, line });
+    }
+  }
+
+  return {
+    code: applyEdits(code, edits),
+    changed: edits.length > 0,
+    changes,
+    unresolved,
+    error: null
+  };
+}
+
+/**
+ * Collect the source string literals of all static `import`/`export ... from`
+ * declarations as well as dynamic `import('...')` calls with a string argument.
+ *
+ * Dynamic imports with a non-literal argument (template, variable) cannot be
+ * resolved statically and are therefore ignored.
+ */
+function importSources(ast) {
+  const sources = [];
+
+  for (const node of walk(ast.program)) {
+    if (
+      (node.type === 'ImportDeclaration' ||
+        node.type === 'ExportNamedDeclaration' ||
+        node.type === 'ExportAllDeclaration') &&
+      node.source
+    ) {
+      sources.push(node.source);
+    } else if (node.type === 'CallExpression' && node.callee.type === 'Import') {
+      const [ arg ] = node.arguments;
+
+      if (arg && arg.type === 'StringLiteral') {
+        sources.push(arg);
+      }
+    }
+  }
+
+  return sources;
+}
+
+/**
+ * Depth-first traversal over every AST node, dependency-free.
+ */
+function* walk(node) {
+  yield node;
+
+  for (const key in node) {
+    const value = node[key];
+
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (isNode(child)) {
+          yield* walk(child);
+        }
+      }
+    } else if (isNode(value)) {
+      yield* walk(value);
+    }
+  }
+}
+
+function isNode(value) {
+  return value !== null && typeof value === 'object' && typeof value.type === 'string';
+}
+
+/**
+ * Apply replacements to the source string. Edits are applied back-to-front so
+ * that earlier offsets stay valid.
+ */
+function applyEdits(code, edits) {
+  let result = code;
+
+  for (const { start, end, text } of edits.sort((a, b) => b.start - a.start)) {
+    result = result.slice(0, start) + text + result.slice(end);
+  }
+
+  return result;
+}
+
+function pluginsFor(filename) {
+  const ext = path.extname(filename).toLowerCase();
+
+  if (ext === '.ts') {
+    return [ 'typescript', 'decorators-legacy' ];
+  }
+
+  if (ext === '.tsx') {
+    return [ 'typescript', 'jsx', 'decorators-legacy' ];
+  }
+
+  return [ 'jsx', 'decorators-legacy' ];
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bpmn-io/codemods",
+  "version": "0.1.0",
+  "description": "A collection of codemods for the bpmn.io ecosystem.",
+  "type": "module",
+  "bin": {
+    "codemods": "bin/codemods.js"
+  },
+  "scripts": {
+    "all": "npm run test",
+    "test": "mocha"
+  },
+  "files": [
+    "bin",
+    "esm/lib",
+    "esm/README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.24.0"
+  },
+  "devDependencies": {
+    "chai": "^5.1.0",
+    "mocha": "^10.4.0"
+  }
+}