di-bag-codemod 0.1.0

package/lib/transforms/build-and-start.mjs

@@ -0,0 +1,58 @@
+// tools/codemod/lib/transforms/build-and-start.mjs
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const propertyName = name => IDENTIFIER.test(name) ? name : JSON.stringify(name);
+
+/**
+ * `builder.buildAndStart(keys, options)` becomes `builder.build().ensureServicesReady(keys, options)`.
+ * `signal` and `timeoutMs` are renamed. `startupOrder` becomes the mapped concurrency role:
+ * 'parallel' is the new default and is dropped, 'sequential' is 1, a number stays that number.
+ * Every emitted API name comes from the rename map.
+ * @returns {string | undefined} the new call, or undefined after reporting why it was left alone.
+ */
+export default function buildAndStart(call, api) {
+  const { ts } = api;
+  const callee = call.expression;
+  const [keys, options, ...rest] = call.arguments;
+  const signal = api.nameOf('StartupOptions', 'signal');
+  const timeout = api.nameOf('StartupOptions', 'timeoutMs');
+  const concurrency = api.nameForRole('concurrency');
+  if (keys === undefined || rest.length > 0) {
+    api.manual(call, `buildAndStart is called with an unexpected number of arguments; rewrite it to ${api.nameOf('Builder', 'build')}().${api.nameOf('Builder', 'buildAndStart')}(serviceKeys, options) by hand`);
+    return undefined;
+  }
+  const separator = api.slice(callee.expression.end, api.start(callee.name));
+  const replacements = [{
+    start: api.start(callee.name), end: callee.name.end,
+    text: `${api.nameOf('Builder', 'build')}()${separator}${api.nameOf('Builder', 'buildAndStart')}`,
+  }];
+  if (options === undefined) return api.assemble(call, replacements);
+  if (!ts.isObjectLiteralExpression(options)) {
+    if (!api.provenOptionOrigin(options, 'StartupOptions')) api.manual(options, `these options are not an object literal; where they are built, rename signal to ${signal}, timeoutMs to ${timeout}, and replace startupOrder with ${concurrency}`);
+    return api.assemble(call, replacements);
+  }
+  const spread = options.properties.find(ts.isSpreadAssignment);
+  if (spread) {
+    api.manual(spread, 'options are spread here; rename signal, timeoutMs and startupOrder where that object is built');
+    return undefined;
+  }
+  const bag = api.objectLiteral(options, {
+    rename: key => ({ signal, timeoutMs: timeout })[key],
+    replace: {
+      startupOrder(property) {
+        const value = ts.isPropertyAssignment(property) ? property.initializer : undefined;
+        if (value && (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value))) {
+          if (value.text === 'parallel') return null;
+          if (value.text === 'sequential') return `${propertyName(concurrency)}: 1`;
+        }
+        if (value && ts.isNumericLiteral(value)) return `${propertyName(concurrency)}: ${value.text}`;
+        api.manual(property, `startupOrder is not a literal; use ${concurrency}: omit it for 'parallel', 1 for 'sequential', or the number`);
+        return undefined;
+      },
+    },
+  });
+  if (bag === undefined) return undefined;
+  replacements.push(bag.remaining === 0
+    ? { start: keys.end, end: options.end, text: '' }
+    : { start: api.start(options), end: options.end, text: bag.text });
+  return api.assemble(call, replacements);
+}

package/lib/transforms/collection-read.mjs

@@ -0,0 +1,14 @@
+import { locate, tokenUse } from './collection-tokens.mjs';
+
+export default function collectionRead(call, api) {
+  const callee = call.expression;
+  const target = api.nameOf(api.member.owner, api.member.name);
+  const use = tokenUse(api, call.arguments[0]);
+  if (use.state === 'collection') {
+    return api.assemble(call, [{ start: api.start(callee.name), end: callee.name.end, text: target }]);
+  }
+  api.manual(call, use.state === 'mixed'
+    ? `${use.name} is also used as a single service (${locate(use.otherUse)}); split it into two tokens, then write ${target}(token) here`
+    : `${api.member.name} is removed; create this token as a collection token, then write ${target}(token) here`);
+  return undefined;
+}

package/lib/transforms/collection-reference.mjs

@@ -0,0 +1,10 @@
+import { locate, tokenUse } from './collection-tokens.mjs';
+
+export default function collectionReference(call, api) {
+  const use = tokenUse(api, call.arguments[0]);
+  if (use.state === 'collection' && call.arguments.length === 1) return api.text(call.arguments[0]);
+  api.manual(call, use.state === 'mixed'
+    ? `${use.name} is also used as a single service (${locate(use.otherUse)}); split it into two tokens, then pass the collection token itself here`
+    : `${api.member.name} is removed; create this token as a collection token, then pass the token itself here`);
+  return undefined;
+}

package/lib/transforms/collection-token.mjs

@@ -0,0 +1,20 @@
+import { creationUse, locate } from './collection-tokens.mjs';
+
+export default function collectionToken(call, api) {
+  const callee = call.expression;
+  const use = creationUse(api, call);
+  if (use.state === 'collection' || use.state === 'single') {
+    return api.assemble(call, [{
+      start: api.start(callee.name),
+      end: callee.name.end,
+      text: api.nameForRole(use.state),
+    }]);
+  }
+  if (use.state === 'mixed') {
+    api.manual(call, `${use.name} is used as a collection and as a single service (${locate(use.otherUse)}); create a second token with ${api.nameForRole('collection')} and keep the single token with ${api.nameForRole('single')}`);
+  } else {
+    api.manual(call, `token creation is not bound to a traceable program variable; choose ${api.nameForRole('single')} or ${api.nameForRole('collection')} by hand`);
+  }
+  // The kind stays manual; independently resolved children can still migrate.
+  return api.assemble(call, []);
+}

package/lib/transforms/collection-tokens.mjs

@@ -0,0 +1,98 @@
+// tools/codemod/lib/transforms/collection-tokens.mjs
+const COLLECTION_POSITIONS = new Set(['Builder.contribute', 'DiBagApi.all', 'Bag.resolveAll', 'Bag.inspectAll']);
+const analyses = new WeakMap();
+
+function analyze(api) {
+  const { ts, checker, program, library } = api;
+  let analysis = analyses.get(program);
+  if (analysis) return analysis;
+  analysis = new Map();
+  analyses.set(program, analysis);
+  const files = program.getSourceFiles().filter(file =>
+    !file.isDeclarationFile && !library.isLibraryFile(file.fileName) && !file.fileName.includes('/node_modules/'));
+  const visitDeclarations = node => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && isTokenCreation(api, node.initializer)) {
+      const symbol = checker.getSymbolAtLocation(node.name);
+      if (symbol) {
+        analysis.set(symbol, { declaration: node, creation: node.initializer, collectionUses: [], otherUses: [] });
+      }
+    }
+    ts.forEachChild(node, visitDeclarations);
+  };
+  for (const file of files) visitDeclarations(file);
+  const visitUses = node => {
+    if (ts.isIdentifier(node)) {
+      const entry = analysis.get(variableSymbol(api, node));
+      if (entry && node !== entry.declaration.name) {
+        const use = classify(api, node);
+        if (use === 'collection') entry.collectionUses.push(node);
+        else if (use === 'other') entry.otherUses.push(node);
+      }
+    }
+    ts.forEachChild(node, visitUses);
+  };
+  for (const file of files) visitUses(file);
+  return analysis;
+}
+
+function isTokenCreation(api, node) {
+  const { ts, library } = api;
+  if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return false;
+  const coverage = library.memberCoverage(library.symbolAt(node.expression.name));
+  return coverage.complete && coverage.members.length > 0
+    && coverage.members.every(member => member.owner === 'token()' && member.name === 'of');
+}
+
+function variableSymbol(api, identifier) {
+  const { ts, checker } = api;
+  const parent = identifier.parent;
+  let symbol = ts.isShorthandPropertyAssignment(parent) ? checker.getShorthandAssignmentValueSymbol(parent)
+    : ts.isExportSpecifier(parent) ? checker.getExportSpecifierLocalTargetSymbol(parent)
+    : checker.getSymbolAtLocation(identifier);
+  if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+  return symbol;
+}
+
+function classify(api, identifier) {
+  const { ts, library } = api;
+  const parent = identifier.parent;
+  if (ts.isImportSpecifier(parent) || ts.isExportSpecifier(parent) || ts.isImportClause(parent) || ts.isTypeQueryNode(parent)) return 'neutral';
+  if (ts.isPropertyAccessExpression(parent) && parent.expression === identifier && parent.name.text === 'key') return 'neutral';
+  if (ts.isCallExpression(parent) && parent.arguments[0] === identifier && ts.isPropertyAccessExpression(parent.expression)) {
+    const coverage = library.memberCoverage(library.symbolAt(parent.expression.name));
+    if (coverage.complete && coverage.members.length > 0
+        && coverage.members.every(member => COLLECTION_POSITIONS.has(`${member.owner}.${member.name}`))) {
+      return 'collection';
+    }
+  }
+  return 'other';
+}
+
+export function tokenUse(api, expression) {
+  const { ts } = api;
+  if (!ts.isIdentifier(expression)) return { state: 'untraceable' };
+  const entry = analyze(api).get(variableSymbol(api, expression));
+  if (!entry) return { state: 'untraceable' };
+  return describe(expression.text, entry);
+}
+
+export function creationUse(api, call) {
+  const { ts, checker } = api;
+  const declaration = call.parent;
+  if (!ts.isVariableDeclaration(declaration) || declaration.initializer !== call || !ts.isIdentifier(declaration.name)) {
+    return { state: 'untraceable' };
+  }
+  const entry = analyze(api).get(checker.getSymbolAtLocation(declaration.name));
+  return entry ? describe(declaration.name.text, entry) : { state: 'untraceable' };
+}
+
+function describe(name, entry) {
+  if (entry.collectionUses.length === 0) return { state: 'single', name };
+  if (entry.otherUses.length > 0) return { state: 'mixed', name, otherUse: entry.otherUses[0] };
+  return { state: 'collection', name };
+}
+
+export function locate(node) {
+  const file = node.getSourceFile();
+  return `${file.fileName.split('/').slice(-2).join('/')}:${file.getLineAndCharacterOfPosition(node.getStart(file)).line + 1}`;
+}

package/lib/transforms/container-derivation.mjs

@@ -0,0 +1,61 @@
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const propertyName = name => IDENTIFIER.test(name) ? name : JSON.stringify(name);
+
+function methodReplacement(call, api) {
+  const name = call.expression.name;
+  return { start: api.start(name), end: name.end, text: api.nameOf('Bag', name.text) };
+}
+
+function fieldNames(oldName, api) {
+  const names = {
+    keys: propertyName(api.nameForRole('keys')),
+    providers: propertyName(api.nameForRole('providers')),
+  };
+  return oldName === 'createScope'
+    ? { ...names, shared: propertyName(api.nameForRole('sharing')) }
+    : names;
+}
+
+function shareReplacements(options, call, api, sharedName) {
+  const { ts } = api;
+  if (!ts.isObjectLiteralExpression(options) || options.properties.length !== 1) {
+    api.manual(call, 'the createScope options are not an object literal; rewrite it to createChildContainer by hand');
+    return undefined;
+  }
+  const [property] = options.properties;
+  if (ts.isShorthandPropertyAssignment(property) && property.name.text === 'share') {
+    return [{ start: api.start(property.name), end: property.name.end, text: `${sharedName}: share` }];
+  }
+  if (ts.isPropertyAssignment(property) && !ts.isComputedPropertyName(property.name)
+      && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
+      && property.name.text === 'share') {
+    return [{ start: api.start(property.name), end: property.name.end, text: sharedName }];
+  }
+  api.manual(call, 'the createScope options are not an object literal; rewrite it to createChildContainer by hand');
+  return undefined;
+}
+
+export default function containerDerivation(call, api) {
+  const oldName = call.expression.name.text;
+  const args = [...call.arguments];
+  const names = fieldNames(oldName, api);
+  const replacements = [methodReplacement(call, api)];
+  const lifetimeManual = api.childLifetimeManualReason(call);
+  if (lifetimeManual !== undefined) api.manual(call, lifetimeManual);
+  if (oldName === 'fork') {
+    if (args.length === 0 || args.length === 2) return api.assemble(call, replacements);
+    api.manual(call, 'fork is called with an unexpected number of arguments; rewrite it to createIndependentContainer by hand');
+    return undefined;
+  }
+  if (args.length === 0 || args.length === 2) return api.assemble(call, replacements);
+  if (args.length === 1) {
+    const shared = shareReplacements(args[0], call, api, names.shared);
+    return shared === undefined ? undefined : api.assemble(call, [...replacements, ...shared]);
+  }
+  if (args.length === 3) {
+    const shared = shareReplacements(args[2], call, api, names.shared);
+    return shared === undefined ? undefined : api.assemble(call, [...replacements, ...shared]);
+  }
+  api.manual(call, 'createScope is called with an unexpected number of arguments; rewrite it to createChildContainer by hand');
+  return undefined;
+}

package/lib/transforms/index.mjs

@@ -0,0 +1,19 @@
+// tools/codemod/lib/transforms/index.mjs
+import buildAndStart from './build-and-start.mjs';
+import collectionRead from './collection-read.mjs';
+import collectionReference from './collection-reference.mjs';
+import collectionToken from './collection-token.mjs';
+import containerDerivation from './container-derivation.mjs';
+import providerFacades from './provider-facades.mjs';
+import providerSources from './provider-sources.mjs';
+
+/** Custom transforms by id. Each transform returns a whole rewritten call or reports and gives up. */
+export const transforms = {
+  'build-and-start': buildAndStart,
+  'collection-read': collectionRead,
+  'collection-reference': collectionReference,
+  'collection-token': collectionToken,
+  'container-derivation': containerDerivation,
+  'provider-facades': providerFacades,
+  'provider-sources': providerSources,
+};

package/lib/transforms/provider-facades.mjs

@@ -0,0 +1,74 @@
+import { originalKind, literalBag, valueOf, nodeOf, renamedLiteral, text, textWithTrivia } from './provider-methods.mjs';
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const propertyName = name => IDENTIFIER.test(name) ? name : JSON.stringify(name);
+const field = (role, value, api) => `${propertyName(api.nameForRole(role))}: ${value}`;
+const member = (receiver, role, api) => {
+  const name = api.nameForRole(role);
+  return IDENTIFIER.test(name) ? `${receiver}.${name}` : `${receiver}[${JSON.stringify(name)}]`;
+};
+const bagCall = (facade, role, fields, api) =>
+  `${member(facade, role, api)}({ ${fields.join(', ')} })`;
+const callbackValues = new Map([['direct', 'exposed-service'], ['awaited', 'fulfilled-value']]);
+const lifetimeValues = new Map([['root', 'singleton:one-per-container-tree'], ['scoped', 'scoped:one-per-container'], ['transient', 'transient:one-per-resolve']]);
+const returnValues = new Map([['auto', 'auto-detect'], ['raw', 'uninspected'], ['nativePromise', 'native-promise']]);
+
+export default function providerFacades(call, api) {
+  const oldName = call.expression.name.text;
+  const registration = call.arguments[0];
+  if (originalKind(registration, api) === 'manual') {
+    api.manual(call, 'the decorated value is any, unknown, invalid, or a factory/provider union; wrap a factory with createProvider or supply a provider by hand');
+    return undefined;
+  }
+  const facade = text(call.expression.expression, api);
+  const receiver = text(registration, api);
+  if (oldName === 'withDisposal') return bagCall(facade, 'method', [field('provider', receiver, api), field('disposeService', textWithTrivia(call.arguments[1], api).trimStart(), api)], api);
+  if (oldName === 'withLifetime') {
+    const oldLifetime = call.arguments[1];
+    const adjustment = api.childLifetimeAdjustment(call);
+    const lifetime = adjustment
+      ? api.quote(oldLifetime, adjustment.lifetime)
+      : renamedLiteral(oldLifetime, lifetimeValues, call, 'withLifetime uses a nonliteral lifetime; rewrite it to a full lifetime value by hand', api);
+    if (lifetime === undefined) return undefined;
+    const fields = [field('provider', receiver, api), field('lifetime', lifetime, api)];
+    let hasAllows = false;
+    if (call.arguments[2] !== undefined) {
+      const options = literalBag(call.arguments[2], new Set(['allowScopedDependencies']), call, 'the withLifetime options are not a supported object literal; rewrite the provider bag by hand', api);
+      if (options === undefined) return undefined;
+      const allows = valueOf(options, 'allowScopedDependencies', api);
+      if (allows !== undefined) { fields.push(field('allowsScopedDependencies', allows, api)); hasAllows = true; }
+    }
+    if (adjustment?.addAllows && !hasAllows) fields.push(field('allowsScopedDependencies', 'true', api));
+    return bagCall(facade, 'method', fields, api);
+  }
+  const allowed = oldName === 'transformService' ? new Set(['mode', 'transform', 'acquisitionMode']) : new Set(['static', 'dynamic']);
+  const options = literalBag(call.arguments[1], allowed, call, `the ${oldName} options are not a supported object literal; rewrite the provider bag by hand`, api);
+  if (options === undefined) return undefined;
+  if (oldName === 'transformService') {
+    const transform = valueOf(options, 'transform', api);
+    const receives = renamedLiteral(nodeOf(options, 'mode', api), callbackValues, call, 'transformService mode is nonliteral; choose callbackReceives by hand', api);
+    const returnNode = nodeOf(options, 'acquisitionMode', api);
+    const returnKind = returnNode === undefined ? undefined : renamedLiteral(returnNode, returnValues, call, 'transformService acquisitionMode is nonliteral; choose transformReturnKind by hand', api);
+    if (transform === undefined || receives === undefined || (returnNode !== undefined && returnKind === undefined)) return undefined;
+    const fields = [field('provider', receiver, api), field('transformService', transform, api), field('callbackReceives', receives, api)];
+    if (returnKind !== undefined) fields.push(field('transformReturnKind', returnKind, api));
+    return bagCall(facade, 'method', fields, api);
+  }
+  const registrationMetadata = valueOf(options, 'static', api);
+  const dynamicProperty = options.get('dynamic');
+  if (registrationMetadata !== undefined && dynamicProperty !== undefined) {
+    api.manual(call, 'combined static and dynamic metadata can change evaluation order when split; rewrite the two provider bags by hand');
+    return undefined;
+  }
+  if (registrationMetadata !== undefined) return bagCall(facade, 'registrationFacade', [field('provider', receiver, api), field('registrationMetadata', registrationMetadata, api)], api);
+  if (!dynamicProperty || !api.ts.isPropertyAssignment(dynamicProperty)) {
+    api.manual(call, 'withMetadata dynamic options are opaque; rewrite the provider bag by hand');
+    return undefined;
+  }
+  const dynamic = literalBag(dynamicProperty.initializer, new Set(['mode', 'describe']), call, 'withMetadata dynamic options are not a supported object literal; rewrite the provider bag by hand', api);
+  if (dynamic === undefined) return undefined;
+  const describe = valueOf(dynamic, 'describe', api);
+  const receives = renamedLiteral(nodeOf(dynamic, 'mode', api), callbackValues, call, 'withMetadata dynamic mode is nonliteral; choose callbackReceives by hand', api);
+  if (describe === undefined || receives === undefined) return undefined;
+  return bagCall(facade, 'acquisitionFacade', [field('provider', receiver, api), field('describeAcquisition', describe, api), field('callbackReceives', receives, api)], api);
+}

package/lib/transforms/provider-methods.mjs

@@ -0,0 +1,100 @@
+export function originalKind(node, api) {
+  const type = api.checker.getTypeAtLocation(node);
+  if (type.flags & (api.ts.TypeFlags.Any | api.ts.TypeFlags.Unknown | api.ts.TypeFlags.TypeParameter)) return 'manual';
+  const members = type.isUnion() ? type.types : [type];
+  const kinds = members.map(member => {
+    if (api.checker.getSignaturesOfType(member, api.ts.SignatureKind.Call).length > 0) return 'factory';
+    const unresolved = member.aliasSymbol ?? member.getSymbol();
+    const symbol = unresolved?.flags & api.ts.SymbolFlags.Alias ? api.checker.getAliasedSymbol(unresolved) : unresolved;
+    const bases = member.getBaseTypes?.() ?? [];
+    const authentic = candidate => candidate?.declarations?.some(declaration => api.library.isLibraryFile(declaration.getSourceFile().fileName));
+    if (authentic(symbol) && (symbol?.name === 'FactoryWithDisposal' || symbol?.name === 'Provider' || symbol?.name === 'ProviderBase')) return 'provider';
+    if (bases.some(base => { const unresolvedBase = base.aliasSymbol ?? base.getSymbol(); const baseSymbol = unresolvedBase?.flags & api.ts.SymbolFlags.Alias ? api.checker.getAliasedSymbol(unresolvedBase) : unresolvedBase; return authentic(baseSymbol) && baseSymbol?.name === 'ProviderBase'; })) return 'provider';
+    return 'invalid';
+  });
+  return kinds.every(kind => kind === 'factory') ? 'factory'
+    : kinds.every(kind => kind === 'provider') ? 'provider'
+    : 'manual';
+}
+export const text = (node, api) => api.text(node);
+export const textWithTrivia = (node, api) => `${api.slice(node.pos, api.start(node))}${api.text(node)}`;
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const propertyName = name => IDENTIFIER.test(name) ? name : JSON.stringify(name);
+const field = (role, value, api) => `${propertyName(api.nameForRole(role))}: ${value}`;
+const roleMethod = (receiver, role, args, api) => {
+  const name = api.nameForRole(role);
+  const access = IDENTIFIER.test(name) ? `.${name}` : `[${JSON.stringify(name)}]`;
+  return `(${receiver})${access}(${args.join(', ')})`;
+};
+const prop = (property, api) => (api.ts.isPropertyAssignment(property) || api.ts.isShorthandPropertyAssignment(property)) && !api.ts.isComputedPropertyName(property.name) ? property.name.text : undefined;
+export function literalBag(node, allowed, call, reason, api) {
+  if (!api.ts.isObjectLiteralExpression(node) || node.properties.some(item => api.ts.isSpreadAssignment(item) || api.ts.isMethodDeclaration(item) || api.ts.isGetAccessorDeclaration(item) || api.ts.isSetAccessorDeclaration(item) || prop(item, api) === undefined || !allowed.has(prop(item, api)))) { api.manual(call, reason); return undefined; }
+  const names = node.properties.map(item => prop(item, api));
+  if (new Set(names).size !== names.length || /\/\*|\/\//.test(api.slice(api.start(node), node.end))) { api.manual(call, `${reason}; duplicate keys and comments require a hand rewrite`); return undefined; }
+  return new Map(node.properties.map(item => [prop(item, api), item]));
+}
+export function valueOf(map, name, api) { const item = map.get(name); return item && api.ts.isShorthandPropertyAssignment(item) ? text(item.name, api) : item && api.ts.isPropertyAssignment(item) ? textWithTrivia(item.initializer, api).trimStart() : undefined; }
+export function nodeOf(map, name, api) { const item = map.get(name); return item && api.ts.isShorthandPropertyAssignment(item) ? item.name : item && api.ts.isPropertyAssignment(item) ? item.initializer : undefined; }
+export function renamedLiteral(node, values, call, reason, api) {
+  if (!node || (!api.ts.isStringLiteral(node) && !api.ts.isNoSubstitutionTemplateLiteral(node))) { api.manual(call, reason); return undefined; }
+  return api.quote(node, values.get(node.text) ?? node.text);
+}
+export function lifetimeOptions(node, call, api) {
+  if (node === undefined) return undefined;
+  const bag = literalBag(node, new Set(['allowScopedDependencies']), call, 'the withLifetime options are not a supported object literal; rewrite the provider chain by hand', api); if (bag === undefined) return null;
+  const item = bag.get('allowScopedDependencies');
+  if (item === undefined) return text(node, api);
+  if (api.ts.isShorthandPropertyAssignment(item)) return api.assemble(node, [{ start: api.start(item), end: item.end, text: field('allowsScopedDependencies', text(item.name, api), api) }]);
+  return api.assemble(node, [{ start: api.start(item.name), end: item.name.end, text: propertyName(api.nameForRole('allowsScopedDependencies')) }]);
+}
+function method(receiver, oldName, args, api) { return `(${receiver}).${api.nameOf('DiBagApi', oldName)}(${args.join(', ')})`; }
+function receiverFor(call, api) {
+  const registration = call.arguments[0];
+  const kind = originalKind(registration, api);
+  if (kind === 'manual') { api.manual(call, 'the decorated value is any, unknown, invalid, or a factory/provider union; wrap a factory with createProvider or supply a provider by hand'); return undefined; }
+  const source = text(registration, api);
+  if (kind === 'provider') return source;
+  const facade = text(call.expression.expression, api);
+  return `${facade}.${api.nameOf('DiBagApi', 'fromFactory')}(${source})`;
+}
+export default function providerMethods(call, api) {
+  const oldName = call.expression.name.text;
+  const receiver = receiverFor(call, api); if (receiver === undefined) return undefined;
+  if (oldName === 'withDisposal') return method(receiver, oldName, [textWithTrivia(call.arguments[1], api).trimStart()], api);
+  if (oldName === 'withLifetime') {
+    const lifetime = renamedLiteral(call.arguments[1], new Map([['root', 'singleton:one-per-container-tree'], ['scoped', 'scoped:one-per-container'], ['transient', 'transient:one-per-resolve']]), call, 'withLifetime uses a nonliteral lifetime; rewrite it to a full lifetime value by hand', api);
+    if (lifetime === undefined) return undefined;
+    const options = lifetimeOptions(call.arguments[2], call, api); if (options === null) return undefined;
+    return method(receiver, oldName, options === undefined ? [lifetime] : [lifetime, options], api);
+  }
+  const allowed = oldName === 'transformService' ? new Set(['mode', 'transform', 'acquisitionMode']) : new Set(['static', 'dynamic']);
+  const options = literalBag(call.arguments[1], allowed, call, `the ${oldName} options are not a supported object literal; rewrite the provider chain by hand`, api);
+  if (options === undefined) return undefined;
+  if (oldName === 'transformService') {
+    const callback = valueOf(options, 'transform', api);
+    const receives = renamedLiteral(nodeOf(options, 'mode', api), new Map([['direct', 'exposed-service'], ['awaited', 'fulfilled-value']]), call, 'transformService mode is nonliteral; choose callbackReceives by hand', api);
+    const returnNode = nodeOf(options, 'acquisitionMode', api);
+    const returnKind = returnNode === undefined ? undefined : renamedLiteral(returnNode, new Map([['auto', 'auto-detect'], ['raw', 'uninspected'], ['nativePromise', 'native-promise']]), call, 'transformService acquisitionMode is nonliteral; choose transformReturnKind by hand', api);
+    if (callback === undefined || receives === undefined || (returnNode !== undefined && returnKind === undefined)) { if (callback === undefined) api.manual(call, 'transformService options must contain transform and mode; rewrite the provider chain by hand'); return undefined; }
+    const fields = [field('transformService', callback, api), field('callbackReceives', receives, api)];
+    if (returnKind !== undefined) fields.push(field('transformReturnKind', returnKind, api));
+    return method(receiver, oldName, [`{ ${fields.join(', ')} }`], api);
+  }
+  const staticValue = valueOf(options, 'static', api), dynamicNode = options.get('dynamic');
+  if (staticValue !== undefined && dynamicNode !== undefined) {
+    api.manual(call, 'combined static and dynamic metadata can change evaluation order when split; rewrite the two provider methods by hand');
+    return undefined;
+  }
+  let result = receiver;
+  if (staticValue !== undefined) result = method(result, oldName, [staticValue], api);
+  if (dynamicNode !== undefined && !api.ts.isPropertyAssignment(dynamicNode)) { api.manual(call, 'withMetadata shorthand dynamic options are opaque; rewrite the provider chain by hand'); return undefined; }
+  if (dynamicNode !== undefined && api.ts.isPropertyAssignment(dynamicNode)) {
+    const dynamic = literalBag(dynamicNode.initializer, new Set(['mode', 'describe']), call, 'withMetadata dynamic options are not a supported object literal; rewrite the provider chain by hand', api); if (dynamic === undefined) return undefined;
+    const describe = valueOf(dynamic, 'describe', api);
+    const mode = renamedLiteral(nodeOf(dynamic, 'mode', api), new Map([['direct', 'exposed-service'], ['awaited', 'fulfilled-value']]), call, 'withMetadata dynamic mode is nonliteral; choose callbackReceives by hand', api);
+    if (describe === undefined || mode === undefined) { api.manual(call, 'withMetadata dynamic options must contain describe and mode; rewrite the provider chain by hand'); return undefined; }
+    result = roleMethod(result, 'acquisitionMethod', [`{ ${field('describeAcquisition', describe, api)}, ${field('callbackReceives', mode, api)} }`], api);
+  }
+  if (staticValue === undefined && dynamicNode === undefined) { api.manual(call, 'withMetadata has neither static nor dynamic metadata; rewrite the provider chain by hand'); return undefined; }
+  return result;
+}

package/lib/transforms/provider-sources.mjs

@@ -0,0 +1,174 @@
+const returnKind = value => ({
+  auto: 'auto-detect', raw: 'uninspected', nativePromise: 'native-promise',
+})[value];
+
+const modeTypeArgument = { fromFactory: 1, fromFunction: 2, fromClass: 2, fromPlugin: 2 };
+
+function explicitKindReplacements(call, api) {
+  const index = modeTypeArgument[api.member.name];
+  const argument = index === undefined ? undefined : call.typeArguments?.[index];
+  if (argument === undefined) return [];
+  const replacements = [];
+  const visit = node => {
+    if (api.ts.isLiteralTypeNode(node) && (api.ts.isStringLiteral(node.literal) || api.ts.isNoSubstitutionTemplateLiteral(node.literal))) {
+      const mapped = returnKind(node.literal.text);
+      if (mapped === undefined) return false;
+      const original = api.text(node.literal);
+      const delimiter = original[0] === '"' ? '"' : original[0] === '`' ? '`' : "'";
+      replacements.push({ start: api.start(node.literal), end: node.literal.end, text: `${delimiter}${mapped}${delimiter}` });
+      return true;
+    }
+    return api.ts.isUnionTypeNode(node) && node.types.every(visit);
+  };
+  if (!visit(argument)) {
+    api.manual(argument, `${api.member.name} has a nonliteral or unsupported explicit return-kind type argument ${index}; rewrite it by hand`);
+    return [];
+  }
+  return [{ start: api.start(argument), end: argument.end, text: api.assemble(argument, replacements) }];
+}
+
+function literalProperties(literal, api, operation) {
+  const values = new Map();
+  for (const property of literal.properties) {
+    if (api.ts.isSpreadAssignment(property)) {
+      api.manual(operation, `${api.member.name} options contain a spread; rewrite them to ${api.nameOf('DiBagApi', api.member.name)} with explicit factoryReturnKind${api.member.name === 'fromPlugin' ? ' and isValidPluginOutput' : ''} by hand`);
+      return undefined;
+    }
+    if (!api.ts.isPropertyAssignment(property) && !api.ts.isShorthandPropertyAssignment(property)) {
+      api.manual(operation, `${api.member.name} options contain a computed or accessor property; rewrite them by hand`);
+      return undefined;
+    }
+    const name = property.name && (api.ts.isIdentifier(property.name) || api.ts.isStringLiteral(property.name)) ? property.name.text : undefined;
+    if (name === undefined) {
+      api.manual(operation, `${api.member.name} options contain a computed property; rewrite them by hand`);
+      return undefined;
+    }
+    values.set(name, api.ts.isShorthandPropertyAssignment(property) ? api.text(property.name) : api.text(property.initializer));
+  }
+  return values;
+}
+
+function optionFields(call, api, index) {
+  const options = call.arguments[index];
+  if (options === undefined) return new Map();
+  if (!api.ts.isObjectLiteralExpression(options)) {
+    api.manual(options, `${api.member.name} options are not an object literal; rewrite them to ${api.nameOf('DiBagApi', api.member.name)} options with factoryReturnKind${api.member.name === 'fromFactory' ? ' and factoryReceivesContext' : ''} by hand`);
+    return undefined;
+  }
+  return literalProperties(options, api, call);
+}
+
+function quotedKind(expression, api, operation) {
+  if (expression === undefined) return { present: false };
+  const node = expression.trim();
+  const match = /^(?:'([^']+)'|"([^"]+)")$/.exec(node);
+  const mapped = match ? returnKind(match[1] ?? match[2]) : undefined;
+  if (mapped === undefined) {
+    api.manual(operation, `${api.member.name} acquisitionMode is not a supported string literal; rewrite factoryReturnKind by hand`);
+    return undefined;
+  }
+  return { present: true, text: `'${mapped}'` };
+}
+
+function acceptsOnly(options, names, api, operation) {
+  const unexpected = [...options.keys()].find(name => !names.includes(name));
+  if (unexpected === undefined) return true;
+  api.manual(operation, `${api.member.name} options contain unsupported property ${unexpected}; rewrite them by hand`);
+  return false;
+}
+
+function property(api, role, value) {
+  return `${api.nameForRole(role)}: ${value}`;
+}
+
+function bagCall(call, api, fields, typeReplacements) {
+  const callee = call.expression;
+  const replacements = [
+    ...typeReplacements,
+    { start: api.start(callee.name), end: callee.name.end, text: api.nameOf('DiBagApi', api.member.name) },
+    { start: api.start(call.arguments[0]), end: call.arguments[call.arguments.length - 1].end, text: `{ ${fields.join(', ')} }` },
+  ];
+  return api.assemble(call, replacements);
+}
+
+export default function providerSources(call, api) {
+  const name = api.member.name;
+  const args = call.arguments;
+  const typeReplacements = explicitKindReplacements(call, api);
+  if (args.some(api.ts.isSpreadElement)) {
+    api.manual(call, `${name} is called with a spread argument; rewrite it by hand`);
+    return undefined;
+  }
+
+  if (name === 'fromFactory' || name === 'fromSyncFactory' || name === 'fromAsyncFactory') {
+    if (args.length < 1 || args.length > 2) {
+      api.manual(call, `${name} has an unexpected argument count; rewrite it to createProvider by hand`);
+      return undefined;
+    }
+    const options = optionFields(call, api, 1);
+    if (options === undefined) return undefined;
+    if (!acceptsOnly(options, name === 'fromFactory' ? ['acquisitionMode', 'context'] : ['context'], api, call)) return undefined;
+    const fields = [];
+    const selected = name === 'fromFactory' ? quotedKind(options.get('acquisitionMode'), api, call) : { present: true, text: name === 'fromSyncFactory' ? `'sync-value'` : `'native-promise'` };
+    if (selected === undefined) return undefined;
+    if (selected.present) fields.push(property(api, 'returnKind', selected.text));
+    const context = options.get('context');
+    if (context !== undefined) {
+      if (!/^(?:'acquisition'|"acquisition")$/.test(context.trim())) {
+        api.manual(call, `${name} context is not the literal 'acquisition'; rewrite factoryReceivesContext by hand`);
+        return undefined;
+      }
+      fields.push(property(api, 'receivesContext', 'true'));
+    }
+    const callee = call.expression;
+    const replacement = [...typeReplacements, { start: api.start(callee.name), end: callee.name.end, text: api.nameOf('DiBagApi', name) }];
+    if (fields.length === 0) {
+      if (args[1] !== undefined) replacement.push({ start: args[0].end, end: args[1].end, text: '' });
+      return api.assemble(call, replacement);
+    }
+    if (args[1] === undefined) replacement.push({ start: args[0].end, end: args[0].end, text: `, { ${fields.join(', ')} }` });
+    else replacement.push({ start: api.start(args[1]), end: args[1].end, text: `{ ${fields.join(', ')} }` });
+    return api.assemble(call, replacement);
+  }
+
+  if (name === 'fromFunction' || name === 'fromClass') {
+    if (args.length < 2 || args.length > 3) {
+      api.manual(call, `${name} has an unexpected argument count; rewrite it by hand`);
+      return undefined;
+    }
+    const options = optionFields(call, api, 2);
+    if (options === undefined) return undefined;
+    if (!acceptsOnly(options, ['acquisitionMode'], api, call)) return undefined;
+    const fields = [property(api, 'dependencies', api.text(args[0])), property(api, 'callable', api.text(args[1]))];
+    const selected = quotedKind(options.get('acquisitionMode'), api, call);
+    if (selected === undefined) return undefined;
+    if (selected.present) fields.push(property(api, 'returnKind', selected.text));
+    return bagCall(call, api, fields, typeReplacements);
+  }
+
+  if (name === 'fromPlugin') {
+    if (args.length !== 3) {
+      api.manual(call, 'fromPlugin has an unexpected argument count; rewrite it to createProviderFromPlugin by hand');
+      return undefined;
+    }
+    const options = optionFields(call, api, 2);
+    if (options === undefined) return undefined;
+    if (!acceptsOnly(options, ['acquisitionMode', 'validate'], api, call)) return undefined;
+    const selected = quotedKind(options.get('acquisitionMode'), api, call);
+    if (selected === undefined) return undefined;
+    const validator = options.get('validate');
+    if (!selected.present || validator === undefined) {
+      api.manual(call, 'fromPlugin options do not have literal acquisitionMode and validate properties; rewrite them by hand');
+      return undefined;
+    }
+    return bagCall(call, api, [
+      property(api, 'dependencies', api.text(args[0])),
+      property(api, 'descriptor', api.text(args[1])),
+      property(api, 'returnKind', selected.text),
+      property(api, 'validator', validator),
+    ], typeReplacements);
+  }
+
+  api.manual(call, `provider-sources does not recognize ${name}`);
+  return undefined;
+}