di-bag-codemod 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Danylo Fedorov
+
+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,114 @@
+# di-bag-codemod
+
+Moves code written for [DI Bag](https://github.com/dany-fedorov/di-bag) 0.4 to
+the 0.5 API. It uses the TypeScript checker to authenticate calls, properties,
+contextually typed object keys, and exported type references as DI Bag uses.
+Argument values are rewritten only within those authenticated uses. Runtime
+`DI_BAG_*` strings and module specifiers follow explicit exact or suffix rules
+in the rename map; they do not depend on declaration resolution. Ordinary uses
+such as `text.replace(...)`, `Promise.all(...)`, and your own `register` method
+are left alone.
+
+Run it **before** you upgrade, while `di-bag` 0.4 is still installed: every
+type-based decision reads the old declarations. Runs are dry by default;
+`--write` applies the changes, and `--report <file>` records every item left
+for a person. Scoped remains the default lifetime in 0.5, so no blanket
+lifetime pinning is needed. Proven child-replacement lifetime adjustments are
+automatic; ambiguous cases stay unchanged as manual items. See the
+[0.5 migration guide](https://github.com/dany-fedorov/di-bag/blob/main/docs/guides/migrating-to-0.5.md)
+for the complete upgrade sequence.
+
+## Commands
+
+```sh
+npx di-bag-codemod                          # dry run over ./tsconfig.json
+npx di-bag-codemod --write                  # apply
+npx di-bag-codemod --project tsconfig.app.json --write --report codemod-report.json
+npx di-bag-codemod src/app.ts src/worker.ts # explicit files instead of a project
+```
+
+Pass either `--project <tsconfig>` or positional source files. Passing both is
+a usage error; use repeatable `--extra-files` to add files excluded by a
+tsconfig. Without either input form, `./tsconfig.json` is used. A run prints one
+line per changed file, one entry per manual item, and a summary:
+
+```text
+would rewrite src/app.ts: 3 rewrites
+manual src/app.ts:41:52 startupOrder is not a literal; use maxConcurrentServiceKeys: omit it for 'parallel', 1 for 'sequential', or the number
+       startupOrder: order
+1 files, 3 rewrites, 1 manual items (dry run; pass --write to apply) (TypeScript 6.0.3, project)
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--write` | Write the rewritten files. Without it nothing changes on disk. |
+| `--report <file>` | Write the changed files and complete manual items as JSON. |
+| `--extra-files <glob>` | Add files the tsconfig excludes. Repeatable. `*`, `**`, and `?` are supported. |
+| `--library-root <dir>` | Treat declarations under this directory as DI Bag. Repeatable. Without this option, installed `node_modules/di-bag` declarations are recognized automatically; when supplied, only the listed roots count. |
+| `--map <file>` | Use a rename map other than the one in this package. |
+| `--help`, `-h` | Print command usage. |
+
+Exit codes: `0` means the run finished, with or without manual items; `2` means
+a usage, tsconfig, or rename-map error.
+
+## Manual items
+
+The codemod never guesses. What it cannot decide from the original program it
+leaves unchanged and reports with file, line, column, reason, and source text:
+
+- options that are not an object literal, or that contain a spread;
+- a string value that is not a literal;
+- a method referenced or destructured without being called when its arguments
+  change shape;
+- a call with a spread argument;
+- a receiver of type `any`;
+- a runtime code split into several replacements, and an old code inside a
+  regular expression, template, or comment;
+- a re-export of a renamed name, which keeps its old public name.
+
+Fix these by hand, then run the compiler.
+
+Qualified members in `typeof` follow the same uncalled-reference rule: a compatible
+plain rename changes the terminal member, while reshaped or ambiguous methods stay
+unchanged and are reported for manual migration.
+
+## The rename map
+
+`rename-map.json` describes the distance from 0.4.0 to the current API.
+`rename-map.schema.json` documents every field.
+Method and property targets must be bare ASCII identifiers. Type targets have
+the same form and cannot be TypeScript keywords or primitive type names. Keys
+emitted inside options bags may contain other characters and are quoted safely.
+
+| Section | Rewrites |
+| --- | --- |
+| `methods` | a method name, its arguments into one options bag or an array, or a custom transform |
+| `options` | a key of an object-literal argument, by argument position and path |
+| `values` | a string at an argument path, or a string compared with or assigned to a library property |
+| `properties` | a property of a library type: access, destructuring, and keys of contextually typed object literals |
+| `types` | an exported class, interface, type alias, or error class in imports and references |
+| `codes` | an exact `DI_BAG_*` runtime code in a string literal |
+| `imports` | an exact module specifier or a suffix of a relative module specifier |
+
+An owner is the original declaration that holds the member: `Builder`, `Bag`,
+`DiBagApi`, or `StartupOptions`. A type written inline in a signature belongs
+to that function, such as `fromFactory()`, or method, such as
+`Bag.createScope()`. A custom method transform reads emitted method and existing
+property names from the map. Its optional `transformNames` object supplies
+role-based names for fields that had no declaration in 0.4.
+For a same-name method that accepts both its old positional form and its new
+options-bag form, `arguments.alreadyBag: true` makes the codemod ask the
+TypeScript checker which form a one-argument call uses. It preserves a proven
+bag, converts a proven old value, and reports an ambiguous value for manual
+migration instead of guessing.
+
+## Limits
+
+The tool rewrites TypeScript and TSX files in the selected program. It does not
+read Markdown, generated source held in strings, or JavaScript without types.
+It preserves formatting and does not run a formatter.
+
+When the project provides a `typescript` package with compiler API version
+6.0.3 or later, the codemod uses that project compiler. If no project compiler
+can be resolved, it is older, or it lacks the required JavaScript compiler API,
+the codemod uses its bundled TypeScript and identifies the choice in the summary.

package/cli.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// tools/codemod/cli.mjs
+import { existsSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { loadTypeScript, runCodemod } from './lib/codemod.mjs';
+
+const usage = 'usage: di-bag-codemod [--project tsconfig.json | file.ts ...] [--library-root dir]... [--extra-files glob]... [--map rename-map.json] [--write] [--report report.json]';
+const args = process.argv.slice(2);
+const files = [];
+const extraFiles = [];
+const libraryRoots = [];
+let project, mapFile, report, write = false;
+const value = index => {
+  if (args[index] === undefined || args[index].startsWith('-')) fail(`${args[index - 1]} needs a value`);
+  return args[index];
+};
+for (let index = 0; index < args.length; index++) {
+  const argument = args[index];
+  if (argument === '--project') project = value(++index);
+  else if (argument === '--library-root') libraryRoots.push(value(++index));
+  else if (argument === '--extra-files') extraFiles.push(value(++index));
+  else if (argument === '--map') mapFile = value(++index);
+  else if (argument === '--report') report = value(++index);
+  else if (argument === '--write') write = true;
+  else if (argument === '--help' || argument === '-h') { console.log(usage); process.exit(0); }
+  else if (argument.startsWith('-')) fail(`unknown option ${argument}`);
+  else files.push(argument);
+}
+if (project && files.length > 0) fail('--project cannot be used with positional files');
+if (!project && files.length === 0) {
+  if (!existsSync('tsconfig.json')) fail('no tsconfig.json in the current directory; pass --project or files');
+  project = 'tsconfig.json';
+}
+
+function fail(message) {
+  console.error(`di-bag-codemod: ${message}\n${usage}`);
+  process.exit(2);
+}
+
+const root = process.cwd();
+const compiler = loadTypeScript(project ? dirname(resolve(root, project)) : root);
+let result;
+try {
+  result = runCodemod({ typescript: compiler.ts, root, project, files, extraFiles, libraryRoots, write, ...(mapFile ? { mapFile: resolve(root, mapFile) } : {}) });
+} catch (error) {
+  fail(error.message);
+}
+if (report) writeFileSync(report, JSON.stringify({ version: 1, written: write, files: result.files.map(({ file, rewrites }) => ({ file, rewrites })), manual: result.manual }, null, 2) + '\n');
+for (const file of result.files) console.log(`${write ? 'rewrote' : 'would rewrite'} ${file.file}: ${file.rewrites} rewrites`);
+for (const item of result.manual) console.log(`manual ${item.file}:${item.line}:${item.column} ${item.reason}${item.text ? `\n       ${item.text}` : ''}`);
+console.log(`${result.files.length} files, ${result.rewrites} rewrites, ${result.manual.length} manual items${write ? '' : ' (dry run; pass --write to apply)'} (TypeScript ${compiler.version}, ${compiler.source})`);

package/lib/codemod.mjs

@@ -0,0 +1,77 @@
+// tools/codemod/lib/codemod.mjs
+import { writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expandGlob } from './glob.mjs';
+import { createLibrary } from './library.mjs';
+import { indexRenameMap, loadRenameMap, validateRenameMap } from './rename-map.mjs';
+import { rewriteSourceFile } from './rewrite.mjs';
+import { transforms } from './transforms/index.mjs';
+
+export { loadTypeScript } from './load-typescript.mjs';
+export { validateRenameMap } from './rename-map.mjs';
+export { transforms };
+
+/** The map shipped with this package: the distance from di-bag 0.4.0 to the current API. */
+export const defaultMapFile = resolve(dirname(fileURLToPath(import.meta.url)), '../rename-map.json');
+
+function loadProgram(ts, { project, files, root, extraFiles }) {
+  const extra = extraFiles.flatMap(pattern => expandGlob(pattern, root));
+  if (project) {
+    const config = ts.getParsedCommandLineOfConfigFile(resolve(root, project), {}, {
+      ...ts.sys, onUnRecoverableConfigFileDiagnostic: diagnostic => { throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')); },
+    });
+    return ts.createProgram([...new Set([...config.fileNames, ...extra])], { ...config.options, noEmit: true });
+  }
+  return ts.createProgram([...new Set([...files.map(file => resolve(root, file)), ...extra])], {
+    strict: true, noEmit: true, skipLibCheck: true, types: [],
+    target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.NodeNext, moduleResolution: ts.ModuleResolutionKind.NodeNext,
+  });
+}
+
+/**
+ * Rewrite every source file of a program that is neither a declaration file, nor under
+ * `node_modules`, nor part of the library itself.
+ * @param {{ typescript: typeof import('typescript'), root: string, project?: string, files?: string[], extraFiles?: string[],
+ *   libraryRoots?: string[], map?: object, mapFile?: string, write?: boolean, only?: string[], program?: import('typescript').Program }} options
+ * @returns {{ files: { file: string, rewrites: number, text: string }[], manual: { file: string, line: number, column: number, reason: string, text: string }[], rewrites: number }}
+ */
+export function runCodemod({ typescript: ts, root, project, files = [], extraFiles = [], libraryRoots = [], map, mapFile = defaultMapFile, write = false, only, program }) {
+  const renameMap = map ?? loadRenameMap(mapFile, Object.keys(transforms));
+  const problems = validateRenameMap(renameMap, Object.keys(transforms));
+  if (problems.length) throw new Error(`invalid rename map:\n${problems.join('\n')}`);
+  const index = indexRenameMap(renameMap);
+  const built = program ?? loadProgram(ts, { project, files, root, extraFiles });
+  const checker = built.getTypeChecker();
+  const library = createLibrary({ ts, checker, root, libraryRoots });
+  const selected = only === undefined ? undefined : new Set(only.map(file => resolve(root, file)));
+  const writableSourceFiles = new Set(built.getSourceFiles()
+    .map(sourceFile => resolve(sourceFile.fileName))
+    .filter(fileName => !fileName.includes('/node_modules/') && !library.isLibraryFile(fileName) && (selected === undefined || selected.has(fileName))));
+  const changed = [];
+  const manual = [];
+  let rewrites = 0;
+  for (const sourceFile of built.getSourceFiles()) {
+    const fileName = resolve(sourceFile.fileName);
+    if (sourceFile.isDeclarationFile || fileName.includes('/node_modules/') || library.isLibraryFile(fileName)) continue;
+    if (selected && !selected.has(fileName)) continue;
+    const fileLabel = relative(root, fileName).replaceAll('\\', '/');
+    let result;
+    try {
+      result = rewriteSourceFile({
+        ts, checker, program: built, sourceFile, library, index, transforms, writableSourceFiles,
+        manualItems: manual,
+        fileLabel,
+      });
+    } catch (error) {
+      manual.push({ file: fileLabel, line: 1, column: 1, reason: `this file was left untouched: ${error.message}`, text: '' });
+      continue;
+    }
+    if (result.text === sourceFile.text) continue;
+    changed.push({ file: fileLabel, rewrites: result.rewrites, text: result.text });
+    rewrites += result.rewrites;
+    if (write) writeFileSync(fileName, result.text);
+  }
+  manual.sort((left, right) => left.file.localeCompare(right.file) || left.line - right.line || left.column - right.column);
+  return { files: changed, manual, rewrites };
+}

package/lib/glob.mjs

@@ -0,0 +1,51 @@
+// tools/codemod/lib/glob.mjs
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const WILDCARD = /[*?]/;
+
+function toRegExp(pattern) {
+  let source = '';
+  for (let index = 0; index < pattern.length; index++) {
+    const character = pattern[index];
+    if (character === '*' && pattern[index + 1] === '*') {
+      // `**/` matches any number of directories, including none.
+      if (pattern[index + 2] === '/') { source += '(?:.*/)?'; index += 2; } else { source += '.*'; index += 1; }
+    } else if (character === '*') source += '[^/]*';
+    else if (character === '?') source += '[^/]';
+    else source += character.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+
+/**
+ * Expand one glob (`*`, `**`, `?`) relative to `root` into sorted absolute file paths.
+ * A pattern without wildcards names one file. `node_modules` directories are never entered.
+ * @param {string} pattern
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function expandGlob(pattern, root) {
+  const normalized = pattern.replaceAll('\\', '/');
+  const segments = normalized.split('/');
+  if (segments.includes('node_modules')) return [];
+  if (!WILDCARD.test(normalized)) {
+    const file = resolve(root, normalized);
+    return existsSync(file) && statSync(file).isFile() ? [file] : [];
+  }
+  const firstWild = segments.findIndex(segment => WILDCARD.test(segment));
+  const base = resolve(root, segments.slice(0, firstWild).join('/') || '.');
+  if (!existsSync(base)) return [];
+  const matcher = toRegExp(segments.slice(firstWild).join('/'));
+  const found = [];
+  const walk = (directory, prefix) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name === 'node_modules') continue;
+      const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(resolve(directory, entry.name), relative);
+      else if (matcher.test(relative)) found.push(resolve(directory, entry.name));
+    }
+  };
+  walk(base, '');
+  return found.sort();
+}

package/lib/library.mjs

@@ -0,0 +1,71 @@
+// tools/codemod/lib/library.mjs
+import { resolve } from 'node:path';
+
+const normalize = file => file.replaceAll('\\', '/');
+
+/**
+ * Decides which declarations belong to DI Bag and names their owner.
+ * With `libraryRoots` the library is those directories (this repository runs with `src` and `dist`);
+ * without any, the library is every `node_modules/di-bag/` directory.
+ */
+export function createLibrary({ ts, checker, root, libraryRoots = [] }) {
+  const prefixes = libraryRoots.map(directory => `${normalize(resolve(root, directory))}/`);
+  const isLibraryFile = fileName => {
+    const file = normalize(fileName);
+    return prefixes.length === 0 ? file.includes('/node_modules/di-bag/') : prefixes.some(prefix => file.startsWith(prefix));
+  };
+
+  /** The symbol a name refers to, with import aliases followed. */
+  function symbolAt(node) {
+    let symbol = checker.getSymbolAtLocation(node);
+    if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    return symbol;
+  }
+
+  /**
+   * The owner of a member declaration: the nearest enclosing named declaration.
+   * A class, interface or type alias gives `Name`; a function gives `name()`;
+   * a method gives `Owner.method()`. A type literal written inline in a signature
+   * therefore belongs to that function or method.
+   */
+  function ownerOf(declaration) {
+    for (let node = declaration.parent; node; node = node.parent) {
+      if ((ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) && node.name) return node.name.text;
+      if (ts.isFunctionDeclaration(node) && node.name) return `${node.name.text}()`;
+      if ((ts.isMethodDeclaration(node) || ts.isMethodSignature(node)) && ts.isIdentifier(node.name)) {
+        const container = node.parent;
+        if ((ts.isClassDeclaration(container) || ts.isInterfaceDeclaration(container)) && container.name) return `${container.name.text}.${node.name.text}()`;
+      }
+    }
+    return undefined;
+  }
+
+  /** Library members plus whether every declaration of the symbol belongs to a named library owner. */
+  function memberCoverage(symbol) {
+    const members = new Map();
+    const declarations = symbol?.declarations ?? [];
+    let complete = declarations.length > 0;
+    for (const declaration of declarations) {
+      if (!isLibraryFile(declaration.getSourceFile().fileName)) { complete = false; continue; }
+      const owner = ownerOf(declaration);
+      if (owner === undefined) { complete = false; continue; }
+      members.set(`${owner}.${symbol.name}`, { owner, name: symbol.name });
+    }
+    return { members: [...members.values()], complete };
+  }
+
+  /** Every distinct `{ owner, name }` a member symbol is declared as inside the library. */
+  const membersOf = symbol => memberCoverage(symbol).members;
+
+  /** The exported name when the symbol is a top-level declaration of the library, else undefined. */
+  function exportNameOf(symbol) {
+    for (const declaration of symbol?.declarations ?? []) {
+      if (!isLibraryFile(declaration.getSourceFile().fileName)) continue;
+      const holder = ts.isVariableDeclaration(declaration) ? declaration.parent?.parent : declaration;
+      if (holder?.parent && ts.isSourceFile(holder.parent)) return symbol.name;
+    }
+    return undefined;
+  }
+
+  return { isLibraryFile, symbolAt, membersOf, memberCoverage, exportNameOf };
+}

package/lib/load-typescript.mjs

@@ -0,0 +1,33 @@
+// tools/codemod/lib/load-typescript.mjs
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+
+function atLeast(version, minimum) {
+  const parts = String(version).split(/[.-]/).map(Number);
+  for (let index = 0; index < minimum.length; index++) {
+    if ((parts[index] ?? 0) !== minimum[index]) return (parts[index] ?? 0) > minimum[index];
+  }
+  return true;
+}
+
+/**
+ * The project's `typescript` when it exposes the compiler API at 6.0.3 or later, else the bundled copy.
+ * A newer project compiler without a compatible JavaScript API is analyzed with the bundled 6.
+ * @param {string} from - A directory inside the project.
+ * @returns {{ ts: typeof import('typescript'), version: string, source: 'project' | 'bundled' }}
+ */
+export function loadTypeScript(from) {
+  const bundledPath = createRequire(import.meta.url).resolve('typescript');
+  try {
+    const require = createRequire(resolve(from, 'package.json'));
+    const path = require.resolve('typescript');
+    const candidate = require(path);
+    if (path !== bundledPath && typeof candidate.createProgram === 'function' && atLeast(candidate.version, [6, 0, 3])) {
+      return { ts: candidate, version: candidate.version, source: 'project' };
+    }
+  } catch {
+    // No resolvable typescript in the project.
+  }
+  const bundled = createRequire(import.meta.url)(bundledPath);
+  return { ts: bundled, version: bundled.version, source: 'bundled' };
+}