flaglint 0.3.0 → 0.4.1

package/dist/bin/flaglint.js

@@ -4,7 +4,7 @@
 import { Command } from "commander";
 
 // src/commands/scan.ts
-import { writeFile } from "fs/promises";
+import { writeFile as writeFile2 } from "fs/promises";
 import { stat } from "fs/promises";
 import { resolve as resolve4 } from "path";
 import chalk from "chalk";
@@ -36,8 +36,30 @@ function staleReason(u) {
 }
 
 // src/scanner/index.ts
-var LD_MEMBER_METHODS = /* @__PURE__ */ new Set(["variation", "variationDetail", "allFlags"]);
-var LD_CLIENT_PATTERN = /^ld|client/i;
+var LD_NODE_SERVER_PACKAGES = /* @__PURE__ */ new Set([
+  "launchdarkly-node-server-sdk",
+  "@launchdarkly/node-server-sdk"
+]);
+var LD_FLAG_KEY_METHODS = /* @__PURE__ */ new Set([
+  "variation",
+  "variationDetail",
+  "boolVariation",
+  "boolVariationDetail",
+  "stringVariation",
+  "stringVariationDetail",
+  "numberVariation",
+  "numberVariationDetail",
+  "jsonVariation",
+  "jsonVariationDetail"
+]);
+var LD_ALL_FLAGS_METHODS = /* @__PURE__ */ new Set(["allFlags", "allFlagsState"]);
+var LD_DETAIL_METHODS = /* @__PURE__ */ new Set([
+  "variationDetail",
+  "boolVariationDetail",
+  "stringVariationDetail",
+  "numberVariationDetail",
+  "jsonVariationDetail"
+]);
 var LD_HOOKS = /* @__PURE__ */ new Set(["useFlags", "useLDClient"]);
 var DEFAULT_EXCLUDE = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.next/**"];
 function extractFlagKey(arg) {
@@ -51,6 +73,80 @@ function extractFlagKey(arg) {
   }
   return { flagKey: "dynamic", isDynamic: true };
 }
+function expressionText(code, node) {
+  const range = node?.range;
+  if (!range) return void 0;
+  return code.slice(range[0], range[1]);
+}
+function expressionRange(node) {
+  return node?.range;
+}
+function isAwaitedCall(code, call) {
+  const range = expressionRange(call);
+  if (!range) return false;
+  let i = range[0] - 1;
+  while (i >= 0 && /\s/.test(code[i])) i--;
+  const end = i + 1;
+  while (i >= 0 && /[A-Za-z_$]/.test(code[i])) i--;
+  return code.slice(i + 1, end) === "await";
+}
+function inferValueType(methodName, fallback) {
+  if (methodName === "boolVariation" || methodName === "boolVariationDetail") return "boolean";
+  if (methodName === "stringVariation" || methodName === "stringVariationDetail") return "string";
+  if (methodName === "numberVariation" || methodName === "numberVariationDetail") return "number";
+  if (methodName === "jsonVariation" || methodName === "jsonVariationDetail") return "object";
+  if (!fallback) return "unknown";
+  if (fallback.type === "Literal") {
+    const value = fallback.value;
+    if (typeof value === "boolean") return "boolean";
+    if (typeof value === "string") return "string";
+    if (typeof value === "number") return "number";
+    return "unknown";
+  }
+  if (fallback.type === "ObjectExpression" || fallback.type === "ArrayExpression") return "object";
+  return "unknown";
+}
+function buildMigrationInventoryItem(code, filePath, loc, call, methodName, args, flagKey, isDynamic) {
+  const callRange = expressionRange(call);
+  if (LD_ALL_FLAGS_METHODS.has(methodName)) {
+    return {
+      file: filePath,
+      line: loc.line,
+      column: loc.column,
+      launchDarklyMethod: methodName,
+      callExpression: expressionText(code, call),
+      rangeStart: callRange?.[0],
+      rangeEnd: callRange?.[1],
+      isAwaited: isAwaitedCall(code, call),
+      isDynamic: false,
+      valueType: "unknown",
+      evaluationContextExpression: expressionText(code, args[0]),
+      safelyAutomatable: false,
+      manualReviewReason: "bulk-inventory-call"
+    };
+  }
+  const fallback = args[2];
+  const valueType = inferValueType(methodName, fallback);
+  const manualReviewReason = isDynamic ? "dynamic-key" : LD_DETAIL_METHODS.has(methodName) ? "detail-method" : valueType === "unknown" ? "unknown-fallback" : void 0;
+  return {
+    file: filePath,
+    line: loc.line,
+    column: loc.column,
+    launchDarklyMethod: methodName,
+    callExpression: expressionText(code, call),
+    rangeStart: callRange?.[0],
+    rangeEnd: callRange?.[1],
+    isAwaited: isAwaitedCall(code, call),
+    flagKeyExpression: expressionText(code, args[0]),
+    staticFlagKey: isDynamic ? void 0 : flagKey,
+    isDynamic,
+    valueType,
+    fallbackExpression: expressionText(code, fallback),
+    evaluationContextExpression: expressionText(code, args[1]),
+    safelyAutomatable: manualReviewReason == null,
+    manualReviewReason
+  };
+}
 function walk(root, visit) {
   if (!root || typeof root !== "object") return;
   const stack = [root];
@@ -76,16 +172,62 @@ function walk(root, visit) {
     }
   }
 }
-function detectUsages(ast, filePath, wrappers) {
+function collectLDClients(ast) {
+  const ldNamespaces = /* @__PURE__ */ new Set();
+  for (const stmt of ast.body) {
+    if (stmt.type === "ImportDeclaration") {
+      const importDecl = stmt;
+      if (LD_NODE_SERVER_PACKAGES.has(importDecl.source.value)) {
+        for (const spec of importDecl.specifiers) {
+          if (spec.type === "ImportNamespaceSpecifier" || spec.type === "ImportDefaultSpecifier") {
+            ldNamespaces.add(spec.local.name);
+          }
+        }
+      }
+      continue;
+    }
+    if (stmt.type === "VariableDeclaration") {
+      const varDecl = stmt;
+      for (const decl of varDecl.declarations) {
+        if (decl.id.type !== "Identifier" || !decl.init) continue;
+        const init = decl.init;
+        if (init.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "require" && init.arguments.length >= 1 && init.arguments[0].type === "Literal" && LD_NODE_SERVER_PACKAGES.has(
+          init.arguments[0].value
+        )) {
+          ldNamespaces.add(decl.id.name);
+        }
+      }
+    }
+  }
+  if (ldNamespaces.size === 0) return /* @__PURE__ */ new Set();
+  const ldClients = /* @__PURE__ */ new Set();
+  walk(ast, (node) => {
+    if (node.type !== "VariableDeclaration") return;
+    const varDecl = node;
+    for (const decl of varDecl.declarations) {
+      if (decl.id.type !== "Identifier" || !decl.init || decl.init.type !== "CallExpression") continue;
+      const initCall = decl.init;
+      if (initCall.callee.type !== "MemberExpression" || initCall.callee.computed) continue;
+      const initCallee = initCall.callee;
+      if (initCallee.object.type === "Identifier" && initCallee.property.type === "Identifier" && ldNamespaces.has(initCallee.object.name) && initCallee.property.name === "init") {
+        ldClients.add(decl.id.name);
+      }
+    }
+  });
+  return ldClients;
+}
+function detectUsages(ast, code, filePath, wrappers) {
   const usages = [];
+  const migrationInventory = [];
+  const ldClients = collectLDClients(ast);
   walk(ast, (node) => {
     if (node.type === "CallExpression") {
       const call = node;
       const { callee } = call;
       const loc = call.loc?.start ?? { line: 0, column: 0 };
-      if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.property.type === "Identifier" && LD_CLIENT_PATTERN.test(callee.object.name) && LD_MEMBER_METHODS.has(callee.property.name)) {
-        const method = callee.property.name;
-        if (method === "allFlags") {
+      if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.property.type === "Identifier" && ldClients.has(callee.object.name)) {
+        const methodName = callee.property.name;
+        if (LD_ALL_FLAGS_METHODS.has(methodName)) {
           const sig = checkStale("*", filePath);
           usages.push({
             flagKey: "*",
@@ -93,10 +235,15 @@ function detectUsages(ast, filePath, wrappers) {
             file: filePath,
             line: loc.line,
             column: loc.column,
-            callType: "allFlags",
+            callType: methodName,
             stalenessSignals: sig ? [sig] : []
           });
-        } else {
+          migrationInventory.push(
+            buildMigrationInventoryItem(code, filePath, loc, call, methodName, call.arguments, "*", false)
+          );
+          return;
+        }
+        if (LD_FLAG_KEY_METHODS.has(methodName)) {
           const { flagKey, isDynamic } = extractFlagKey(call.arguments[0]);
           const sig = checkStale(flagKey, filePath);
           usages.push({
@@ -105,9 +252,13 @@ function detectUsages(ast, filePath, wrappers) {
             file: filePath,
             line: loc.line,
             column: loc.column,
-            callType: method,
+            callType: methodName,
             stalenessSignals: sig ? [sig] : []
           });
+          migrationInventory.push(
+            buildMigrationInventoryItem(code, filePath, loc, call, methodName, call.arguments, flagKey, isDynamic)
+          );
+          return;
         }
         return;
       }
@@ -186,7 +337,7 @@ function detectUsages(ast, filePath, wrappers) {
       }
     }
   });
-  return usages;
+  return { usages, migrationInventory };
 }
 async function scan(source, config, onProgress, evaluator) {
   const start = Date.now();
@@ -200,6 +351,7 @@ async function scan(source, config, onProgress, evaluator) {
   }
   const files = await source.listFiles(config.include, config.exclude);
   const allUsages = [];
+  const migrationInventory = [];
   const warnings = [];
   let scannedFiles = 0;
   async function processFile(file) {
@@ -208,22 +360,22 @@ async function scan(source, config, onProgress, evaluator) {
       code = await source.readFile(file);
     } catch (err) {
       const fsCode = err.code ?? "UNKNOWN";
-      return { usages: [], warning: { kind: "read-failure", file, fsCode } };
+      return { usages: [], migrationInventory: [], warning: { kind: "read-failure", file, fsCode } };
     }
     let ast;
     try {
       ast = parse(code, {
         jsx: true,
         loc: true,
-        range: false,
+        range: true,
         comment: false,
         tokens: false,
         filePath: file
       });
     } catch {
-      return { usages: [], warning: { kind: "parse-failure", file } };
+      return { usages: [], migrationInventory: [], warning: { kind: "parse-failure", file } };
     }
-    return { usages: detectUsages(ast, file, config.wrappers), warning: null };
+    return { ...detectUsages(ast, code, file, config.wrappers), warning: null };
   }
   const limit = pLimit(50);
   const results = await Promise.all(
@@ -237,6 +389,7 @@ async function scan(source, config, onProgress, evaluator) {
   );
   for (const r of results) {
     allUsages.push(...r.usages);
+    migrationInventory.push(...r.migrationInventory);
     if (r.warning) warnings.push(r.warning);
   }
   if (config.minFileCount > 0) {
@@ -277,6 +430,7 @@ async function scan(source, config, onProgress, evaluator) {
     totalUsages: allUsages.length,
     uniqueFlags,
     usages: allUsages,
+    migrationInventory,
     scanDurationMs: Date.now() - start,
     warnings
   };
@@ -284,7 +438,7 @@ async function scan(source, config, onProgress, evaluator) {
 
 // src/scanner/local-source.ts
 import fg from "fast-glob";
-import { readFile } from "fs/promises";
+import { readFile, writeFile } from "fs/promises";
 import { join, relative, resolve } from "path";
 var LocalFileSource = class {
   constructor(dir) {
@@ -305,6 +459,9 @@ var LocalFileSource = class {
   async readFile(path) {
     return readFile(join(this.dir, path), "utf8");
   }
+  async writeFile(path, content) {
+    await writeFile(join(this.dir, path), content, "utf8");
+  }
 };
 
 // src/reporter/index.ts
@@ -378,7 +535,7 @@ function formatMarkdown(result, options) {
   }
   if (staleFlags.length > 0) {
     lines.push("## \u26A0 Stale Flag Candidates");
-    lines.push("Flags that may be safe to remove:");
+    lines.push("Flags with review signals:");
     lines.push("| Flag Key | Reason | Location |");
     lines.push("|----------|--------|----------|");
     for (const [key, data] of staleFlags) {
@@ -531,7 +688,7 @@ function formatHTML(result, options) {
     return `<tr class="${cls}"><td><code>${esc(key)}</code></td><td>${data.usages.length}</td><td>${fileList}</td><td>${[...data.callTypes].map(esc).join(", ")}</td><td>${status}</td></tr>`;
   }).join("\n      ");
   const title = options.title ? esc(options.title) : "FlagLint Scan Report";
-  const version = true ? "0.3.0" : "0.1.0";
+  const version = true ? "0.4.1" : "0.1.0";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -629,7 +786,7 @@ var FlagLintConfigSchema = z.object({
   ]),
   provider: z.enum(["launchdarkly", "unleash", "growthbook", "custom"]).default("launchdarkly"),
   // TODO v0.3: replace minFileCount with real date-based staleness via git log
-  minFileCount: z.number().int().min(0).default(1),
+  minFileCount: z.number().int().min(0).default(0),
   wrappers: z.array(z.string()).default([]),
   reportTitle: z.string().optional(),
   outputDir: z.string().default(".")
@@ -790,7 +947,7 @@ Examples:
       if (options.output) {
         const outPath = resolve4(options.output);
         try {
-          await writeFile(outPath, report, "utf8");
+          await writeFile2(outPath, report, "utf8");
           process.stderr.write(chalk.dim(`   Report written to ${options.output}
 `));
         } catch (err) {
@@ -811,234 +968,606 @@ Examples:
 }
 
 // src/commands/migrate.ts
-import { writeFile as writeFile2 } from "fs/promises";
+import { writeFile as writeFile3 } from "fs/promises";
 import { stat as stat2 } from "fs/promises";
 import { resolve as resolve5 } from "path";
 import chalk2 from "chalk";
 import ora2 from "ora";
 
 // src/migrator/index.ts
-function keyLiteral(usage) {
-  return usage.isDynamic ? "flagKey" : `'${usage.flagKey}'`;
+function legacyInventoryFromUsage(usage) {
+  const isBulk = usage.flagKey === "*" || usage.callType === "allFlags" || usage.callType === "allFlagsState";
+  const manualReviewReason = isBulk ? "bulk-inventory-call" : usage.isDynamic ? "dynamic-key" : "unknown-fallback";
+  return {
+    file: usage.file,
+    line: usage.line,
+    column: usage.column,
+    launchDarklyMethod: usage.callType,
+    flagKeyExpression: isBulk ? void 0 : usage.isDynamic ? "flagKey" : `'${usage.flagKey}'`,
+    staticFlagKey: usage.isDynamic || isBulk ? void 0 : usage.flagKey,
+    isDynamic: usage.isDynamic,
+    valueType: "unknown",
+    safelyAutomatable: false,
+    manualReviewReason
+  };
 }
-function buildItem(usage) {
-  const k = keyLiteral(usage);
-  if (usage.isDynamic) {
-    const isDetail = usage.callType === "variationDetail";
-    const methodName = isDetail ? "variationDetail" : "variation";
-    return {
-      usage,
-      openFeatureEquivalent: isDetail ? "client.getBooleanDetails()" : "client.getBooleanValue()",
-      codeChangeBefore: `ldClient.${methodName}(flagKey, context, false)`,
-      codeChangeAfter: isDetail ? `await client.getBooleanDetails(flagKey, false) // server SDK is async` : `await client.getBooleanValue(flagKey, false) // server SDK is async`,
-      requiresManualReview: true,
-      reviewReason: "Flag key determined at runtime; OpenFeature server SDK methods are async \u2014 add await and make the enclosing function async"
-    };
+function inventoryFrom(result) {
+  if (result.migrationInventory) return result.migrationInventory;
+  return result.usages.map(legacyInventoryFromUsage);
+}
+function isServerInventoryItem(item) {
+  return item.launchDarklyMethod === "variation" || item.launchDarklyMethod === "variationDetail" || item.launchDarklyMethod === "boolVariation" || item.launchDarklyMethod === "boolVariationDetail" || item.launchDarklyMethod === "stringVariation" || item.launchDarklyMethod === "stringVariationDetail" || item.launchDarklyMethod === "numberVariation" || item.launchDarklyMethod === "numberVariationDetail" || item.launchDarklyMethod === "jsonVariation" || item.launchDarklyMethod === "jsonVariationDetail" || item.launchDarklyMethod === "allFlags" || item.launchDarklyMethod === "allFlagsState";
+}
+function openFeatureMethod(valueType) {
+  switch (valueType) {
+    case "boolean":
+      return "client.getBooleanValue()";
+    case "string":
+      return "client.getStringValue()";
+    case "number":
+      return "client.getNumberValue()";
+    case "object":
+      return "client.getObjectValue()";
+    case "unknown":
+      return null;
   }
-  switch (usage.callType) {
-    case "variation":
-      return {
-        usage,
-        openFeatureEquivalent: "client.getBooleanValue()",
-        codeChangeBefore: `ldClient.variation(${k}, context, false)`,
-        codeChangeAfter: `await client.getBooleanValue(${k}, false) // server SDK is async`,
-        requiresManualReview: true,
-        reviewReason: "OpenFeature server SDK methods are async \u2014 add await and make the enclosing function async"
-      };
-    case "variationDetail":
-      return {
-        usage,
-        openFeatureEquivalent: "client.getBooleanDetails()",
-        codeChangeBefore: `ldClient.variationDetail(${k}, context, false)`,
-        codeChangeAfter: `await client.getBooleanDetails(${k}, false) // server SDK is async`,
-        requiresManualReview: true,
-        reviewReason: "OpenFeature server SDK methods are async \u2014 add await and make the enclosing function async"
-      };
-    case "allFlags":
-      return {
-        usage,
-        openFeatureEquivalent: null,
-        codeChangeBefore: `ldClient.allFlags(context)`,
-        codeChangeAfter: `// No direct OpenFeature equivalent \u2014 requires manual implementation`,
-        requiresManualReview: true,
-        reviewReason: "allFlags() has no direct OpenFeature equivalent"
-      };
-    case "isFeatureEnabled":
-      return {
-        usage,
-        openFeatureEquivalent: "client.getBooleanValue()",
-        codeChangeBefore: `isFeatureEnabled(${k}, context)`,
-        codeChangeAfter: `await client.getBooleanValue(${k}, false) // server SDK is async`,
-        requiresManualReview: true,
-        reviewReason: "OpenFeature server SDK methods are async \u2014 add await and make the enclosing function async"
-      };
-    case "hook-useFlags":
-      return {
-        usage,
-        openFeatureEquivalent: "useBooleanFlagValue()",
-        codeChangeBefore: `const flags = useFlags()`,
-        codeChangeAfter: `const flagValue = useBooleanFlagValue('your-flag-key', false) // TODO: one hook call per flag`,
-        requiresManualReview: true,
-        reviewReason: "useFlags() returns all flags; OpenFeature requires one useBooleanFlagValue() call per flag"
-      };
-    case "hook-useLDClient":
-      return {
-        usage,
-        openFeatureEquivalent: "useOpenFeatureClient()",
-        codeChangeBefore: `const client = useLDClient()`,
-        codeChangeAfter: `const client = useOpenFeatureClient()`,
-        requiresManualReview: false
-      };
-    case "hoc":
-      return {
-        usage,
-        openFeatureEquivalent: null,
-        codeChangeBefore: `withLDConsumer()(Component)`,
-        codeChangeAfter: `// withOpenFeature() does not exist in OpenFeature SDK 0.4+
-// Convert to a functional component and use useBooleanFlagValue() instead`,
-        requiresManualReview: true,
-        reviewReason: "withOpenFeature() HOC does not exist in OpenFeature SDK 0.4+; convert to a functional component with hooks"
-      };
-    case "provider":
-      return {
-        usage,
-        openFeatureEquivalent: "OpenFeatureProvider",
-        codeChangeBefore: `<LDProvider clientSideID="...">`,
-        codeChangeAfter: `<OpenFeatureProvider provider={...}>`,
-        requiresManualReview: false
-      };
+}
+function reasonLabel(reason) {
+  switch (reason) {
+    case "dynamic-key":
+      return "dynamic key";
+    case "unknown-fallback":
+      return "unsupported or unknown fallback";
+    case "detail-method":
+      return "detail method";
+    case "bulk-inventory-call":
+      return "bulk inventory call";
     default:
-      throw new Error(`Unhandled callType: ${usage.callType}`);
+      return "manual review required";
   }
 }
-function calcReadinessScore(usages) {
-  let score = 100;
-  const dynamicCount = usages.filter((u) => u.isDynamic).length;
-  score -= Math.min(dynamicCount * 10, 40);
-  const useFlagsCount = usages.filter((u) => u.callType === "hook-useFlags").length;
-  score -= useFlagsCount * 5;
-  const hasAllFlags = usages.some((u) => u.callType === "allFlags");
-  if (hasAllFlags) score -= 15;
-  const hocCount = usages.filter((u) => u.callType === "hoc").length;
-  score -= hocCount * 5;
-  const hasStaticKeys = usages.some((u) => !u.isDynamic && u.flagKey !== "*");
-  if (!hasStaticKeys) score -= 20;
-  return Math.max(0, score);
+function buildEvidenceItem(item) {
+  const flagLabel = item.staticFlagKey ?? item.flagKeyExpression ?? "*";
+  const beforeArgs = [
+    item.flagKeyExpression,
+    item.evaluationContextExpression,
+    item.fallbackExpression
+  ].filter((value) => Boolean(value));
+  const before = `${item.launchDarklyMethod}(${beforeArgs.join(", ")})`;
+  const equivalent = item.safelyAutomatable ? openFeatureMethod(item.valueType) : null;
+  return {
+    usage: {
+      flagKey: item.staticFlagKey ?? (item.isDynamic ? "dynamic" : "*"),
+      isDynamic: item.isDynamic,
+      file: item.file,
+      line: item.line,
+      column: item.column,
+      callType: item.launchDarklyMethod,
+      stalenessSignals: []
+    },
+    openFeatureEquivalent: equivalent,
+    codeChangeBefore: before,
+    codeChangeAfter: "// No codemod generated by this report",
+    requiresManualReview: !item.safelyAutomatable,
+    reviewReason: item.safelyAutomatable ? void 0 : reasonLabel(item.manualReviewReason)
+  };
 }
-function calcRequiredPackages(usages) {
-  const REACT_CALL_TYPES = ["hook-useFlags", "hook-useLDClient", "hoc", "provider"];
-  const SERVER_CALL_TYPES = ["variation", "variationDetail", "allFlags", "isFeatureEnabled"];
-  const hasReactUsage = usages.some((u) => REACT_CALL_TYPES.includes(u.callType));
-  const hasServerUsage = usages.some((u) => SERVER_CALL_TYPES.includes(u.callType));
-  const pkgs = /* @__PURE__ */ new Set();
-  if (hasReactUsage && !hasServerUsage) {
-    pkgs.add("@openfeature/web-sdk");
-    pkgs.add("@openfeature/react-sdk");
-  } else if (hasReactUsage && hasServerUsage) {
-    pkgs.add("@openfeature/server-sdk");
-    pkgs.add("@openfeature/web-sdk");
-    pkgs.add("@openfeature/react-sdk");
-  } else {
-    pkgs.add("@openfeature/server-sdk");
-  }
-  return [...pkgs].sort();
+function calcReadinessScore(items) {
+  if (items.length === 0) return 0;
+  const safeCount = items.filter((item) => item.safelyAutomatable).length;
+  const score = Math.round(safeCount / items.length * 100);
+  return safeCount === items.length ? 100 : Math.min(score, 99);
+}
+function calcRequiredPackages(items) {
+  return items.some(isServerInventoryItem) ? ["@openfeature/server-sdk"] : [];
 }
 function analyze(result) {
-  const items = result.usages.map(buildItem);
-  const readinessScore = calcReadinessScore(result.usages);
-  const requiredPackages = calcRequiredPackages(result.usages);
-  const manualReviewCount = items.filter((i) => i.requiresManualReview).length;
-  const autoMigrateCount = items.filter((i) => !i.requiresManualReview).length;
-  return { readinessScore, requiredPackages, items, manualReviewCount, autoMigrateCount };
+  const inventoryItems = inventoryFrom(result);
+  const items = inventoryItems.map(buildEvidenceItem);
+  const totalLaunchDarklyUsages = inventoryItems.length;
+  const safelyAutomatableCount = inventoryItems.filter((item) => item.safelyAutomatable).length;
+  const dynamicKeyCount = inventoryItems.filter((item) => item.manualReviewReason === "dynamic-key").length;
+  const bulkInventoryCallCount = inventoryItems.filter(
+    (item) => item.manualReviewReason === "bulk-inventory-call"
+  ).length;
+  const unsupportedUnknownCount = inventoryItems.filter(
+    (item) => item.manualReviewReason === "unknown-fallback"
+  ).length;
+  const manualReviewCount = totalLaunchDarklyUsages - safelyAutomatableCount;
+  const autoMigrateCount = safelyAutomatableCount;
+  const readinessScore = calcReadinessScore(inventoryItems);
+  const requiredPackages = calcRequiredPackages(inventoryItems);
+  return {
+    readinessScore,
+    requiredPackages,
+    items,
+    inventoryItems,
+    totalLaunchDarklyUsages,
+    safelyAutomatableCount,
+    dynamicKeyCount,
+    bulkInventoryCallCount,
+    unsupportedUnknownCount,
+    manualReviewCount,
+    autoMigrateCount
+  };
 }
 function formatMigrationReport(analysis) {
-  const { readinessScore, requiredPackages, items, manualReviewCount, autoMigrateCount } = analysis;
+  const {
+    requiredPackages,
+    inventoryItems,
+    totalLaunchDarklyUsages,
+    safelyAutomatableCount,
+    manualReviewCount,
+    dynamicKeyCount,
+    bulkInventoryCallCount,
+    unsupportedUnknownCount
+  } = analysis;
   const date = (/* @__PURE__ */ new Date()).toLocaleDateString();
-  const version = true ? "0.3.0" : "0.1.0";
-  let scoreLabel;
-  if (readinessScore >= 80) scoreLabel = "\u2713 Your codebase is ready for migration";
-  else if (readinessScore >= 50) scoreLabel = "\u26A0 Some manual work required before migration";
-  else scoreLabel = "\u2717 Significant refactoring needed";
+  const version = true ? "0.4.1" : "0.1.0";
   const lines = [];
-  lines.push(`# OpenFeature Migration Plan`);
+  lines.push("# OpenFeature Migration Inventory");
   lines.push(`Generated by FlagLint v${version} on ${date}`);
   lines.push("");
-  lines.push(`## Migration Readiness Score: ${readinessScore}/100`);
-  lines.push(scoreLabel);
-  lines.push("");
-  lines.push(`**Auto-migratable:** ${autoMigrateCount} usages  `);
-  lines.push(`**Requires manual review:** ${manualReviewCount} usages`);
-  lines.push("");
-  lines.push("## Required Packages");
-  lines.push("```");
-  lines.push(`npm install ${requiredPackages.join(" ")}`);
-  lines.push("```");
+  lines.push("## Evidence Summary");
+  lines.push(`**Total LaunchDarkly usages found:** ${totalLaunchDarklyUsages}  `);
+  lines.push(`**Safely automatable usages:** ${safelyAutomatableCount}  `);
+  lines.push(`**Manual review required:** ${manualReviewCount}  `);
+  lines.push(`**Dynamic keys:** ${dynamicKeyCount}  `);
+  lines.push(`**Bulk inventory calls:** ${bulkInventoryCallCount}  `);
+  lines.push(`**Unsupported/unknown cases:** ${unsupportedUnknownCount}`);
   lines.push("");
-  lines.push("## Step-by-Step Checklist");
-  lines.push("- [ ] Install OpenFeature packages");
-  lines.push("- [ ] Configure your OpenFeature provider (LaunchDarkly, Unleash, etc.)");
-  lines.push("- [ ] Replace LDProvider with OpenFeatureProvider");
-  lines.push("- [ ] Update each flag evaluation call (see below)");
-  lines.push("- [ ] Remove LaunchDarkly SDK dependency");
-  lines.push("- [ ] Test all flagged features");
-  lines.push("");
-  const autoItems = items.filter((i) => !i.requiresManualReview);
-  const manualItems = items.filter((i) => i.requiresManualReview);
-  if (autoItems.length > 0) {
-    lines.push("## Code Changes Required");
-    for (const item of autoItems) {
-      const { usage } = item;
-      lines.push(`### ${usage.file}:${usage.line} \u2014 \`${usage.flagKey}\``);
-      lines.push("**Before:**");
-      lines.push("```typescript");
-      lines.push(item.codeChangeBefore);
-      lines.push("```");
-      lines.push("**After:**");
-      lines.push("```typescript");
-      lines.push(item.codeChangeAfter);
-      lines.push("```");
-      lines.push("");
+  if (manualReviewCount > 0) {
+    lines.push(
+      "> This report is an inventory, not a codemod. Manual-review items must be resolved before treating the migration as safe."
+    );
+    lines.push("");
+  }
+  if (requiredPackages.length > 0) {
+    lines.push("## OpenFeature Packages To Evaluate");
+    lines.push("```");
+    lines.push(`npm install ${requiredPackages.join(" ")}`);
+    lines.push("```");
+    lines.push("");
+  }
+  const safeItems = inventoryItems.filter((item) => item.safelyAutomatable);
+  const manualItems = inventoryItems.filter((item) => !item.safelyAutomatable);
+  if (safeItems.length > 0) {
+    lines.push("## Safely Automatable Inventory");
+    for (const item of safeItems) {
+      const flag = item.staticFlagKey ?? item.flagKeyExpression ?? "unknown";
+      lines.push(
+        `- ${item.file}:${item.line}:${item.column} \u2014 \`${flag}\` via \`${item.launchDarklyMethod}\` (${item.valueType})`
+      );
+      lines.push(
+        `  context: \`${item.evaluationContextExpression ?? "unknown"}\`; fallback: \`${item.fallbackExpression ?? "unknown"}\``
+      );
     }
+    lines.push("");
   }
   if (manualItems.length > 0) {
     lines.push("## Manual Review Required");
     for (const item of manualItems) {
-      const { usage } = item;
-      lines.push(`### ${usage.file}:${usage.line} \u2014 \`${usage.flagKey}\``);
-      if (item.reviewReason) lines.push(`> ${item.reviewReason}`);
-      lines.push("**Before:**");
-      lines.push("```typescript");
-      lines.push(item.codeChangeBefore);
-      lines.push("```");
-      lines.push("**After:**");
-      lines.push("```typescript");
-      lines.push(item.codeChangeAfter);
-      lines.push("```");
-      lines.push("");
+      const flag = item.staticFlagKey ?? item.flagKeyExpression ?? "*";
+      lines.push(
+        `- ${item.file}:${item.line}:${item.column} \u2014 \`${flag}\` via \`${item.launchDarklyMethod}\`: ${reasonLabel(item.manualReviewReason)}`
+      );
+      if (item.evaluationContextExpression) lines.push(`  context: \`${item.evaluationContextExpression}\``);
+      if (item.fallbackExpression) lines.push(`  fallback: \`${item.fallbackExpression}\``);
     }
+    lines.push("");
   }
   lines.push("## Resources");
   lines.push("- OpenFeature docs: https://openfeature.dev/docs");
+  lines.push("- OpenFeature server SDK: https://openfeature.dev/docs/reference/technologies/server/javascript");
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/migrator/dry-run.ts
+var DETAIL_METHODS = /* @__PURE__ */ new Set([
+  "variationDetail",
+  "boolVariationDetail",
+  "stringVariationDetail",
+  "numberVariationDetail",
+  "jsonVariationDetail"
+]);
+function methodForType(valueType) {
+  switch (valueType) {
+    case "boolean":
+      return "getBooleanValue";
+    case "string":
+      return "getStringValue";
+    case "number":
+      return "getNumberValue";
+    case "object":
+      return "getObjectValue";
+    case "unknown":
+      return null;
+  }
+}
+function manualReason(item) {
+  if (item.manualReviewReason === "dynamic-key") return "dynamic key requires manual review";
+  if (item.manualReviewReason === "unknown-fallback") return "unknown fallback type requires manual review";
+  if (item.manualReviewReason === "detail-method") {
+    return "detail methods skipped: OpenFeature detail APIs exist, but LaunchDarkly/OpenFeature detail result parity requires manual review";
+  }
+  if (item.manualReviewReason === "bulk-inventory-call") return "bulk inventory call has no single-flag codemod";
+  return "manual review required";
+}
+function buildReplacement(item) {
+  if (DETAIL_METHODS.has(item.launchDarklyMethod)) {
+    return {
+      item,
+      reason: "detail methods skipped: OpenFeature detail APIs exist, but LaunchDarkly/OpenFeature detail result parity requires manual review"
+    };
+  }
+  if (!item.safelyAutomatable) {
+    return { item, reason: manualReason(item) };
+  }
+  if (item.rangeStart == null || item.rangeEnd == null || !item.callExpression) {
+    return { item, reason: "missing source range for reviewable diff" };
+  }
+  if (!item.flagKeyExpression || !item.fallbackExpression || !item.evaluationContextExpression) {
+    return { item, reason: "missing flag key, fallback, or evaluation context evidence" };
+  }
+  const method = methodForType(item.valueType);
+  if (!method) return { item, reason: "unsupported or unknown value type" };
+  const call = `openFeatureClient.${method}(${item.flagKeyExpression}, ${item.fallbackExpression}, ${item.evaluationContextExpression})`;
+  return {
+    item,
+    replacement: call,
+    requiresProviderSetup: true
+  };
+}
+function applyReplacements(code, replacements) {
+  let next = code;
+  for (const replacement of [...replacements].sort((a, b) => b.item.rangeStart - a.item.rangeStart)) {
+    next = next.slice(0, replacement.item.rangeStart) + replacement.replacement + next.slice(replacement.item.rangeEnd);
+  }
+  return next;
+}
+function changedLineNumbers(before, after) {
+  const changed = [];
+  const length = Math.max(before.length, after.length);
+  for (let i = 0; i < length; i++) {
+    if (before[i] !== after[i]) changed.push(i);
+  }
+  return changed;
+}
+function formatFileDiff(file, beforeCode, afterCode) {
+  const before = beforeCode.split("\n");
+  const after = afterCode.split("\n");
+  const changed = changedLineNumbers(before, after);
+  if (changed.length === 0) return [];
+  const lines = [];
+  lines.push(`diff --git a/${file} b/${file}`);
+  lines.push(`--- a/${file}`);
+  lines.push(`+++ b/${file}`);
+  for (const index of changed) {
+    const oldLine = before[index] ?? "";
+    const newLine = after[index] ?? "";
+    lines.push(`@@ -${index + 1},1 +${index + 1},1 @@`);
+    lines.push(`-${oldLine}`);
+    lines.push(`+${newLine}`);
+  }
+  return lines;
+}
+function itemLabel(item) {
+  return item.staticFlagKey ?? item.flagKeyExpression ?? "*";
+}
+function formatProviderSetupSection() {
+  const lines = [];
+  lines.push("## Provider Setup (Required Before Applying Diffs)");
+  lines.push("");
+  lines.push("LaunchDarkly remains your feature flag provider.");
+  lines.push("OpenFeature becomes the evaluation API your application code calls.");
+  lines.push("You add one initialization step; **do not remove any LaunchDarkly packages** \u2014");
+  lines.push("the OpenFeature provider depends on them at runtime.");
+  lines.push("");
+  lines.push("### 1. Install packages");
+  lines.push("");
+  lines.push("```sh");
+  lines.push(
+    "npm install @openfeature/server-sdk @launchdarkly/node-server-sdk @launchdarkly/openfeature-node-server"
+  );
+  lines.push("```");
+  lines.push("");
+  lines.push("### 2. Initialize once at application startup");
+  lines.push("");
+  lines.push("Add the following to your application bootstrap (do not apply automatically):");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push('import { OpenFeature } from "@openfeature/server-sdk";');
+  lines.push('import { LaunchDarklyProvider } from "@launchdarkly/openfeature-node-server";');
+  lines.push("");
+  lines.push("const ldProvider = new LaunchDarklyProvider(process.env.LD_SDK_KEY!);");
+  lines.push("await OpenFeature.setProviderAndWait(ldProvider);");
+  lines.push("");
+  lines.push("// Share this client across your application.");
+  lines.push("// Replace the `openFeatureClient` placeholder in the diffs below.");
+  lines.push("const openFeatureClient = OpenFeature.getClient();");
+  lines.push("```");
+  lines.push("");
+  lines.push("### 3. Evaluation context \u2014 targeting key");
+  lines.push("");
+  lines.push("LaunchDarkly requires a targeting key in every evaluation context. The");
+  lines.push("provider accepts either OpenFeature `targetingKey` or an existing");
+  lines.push("LaunchDarkly `key`.");
+  lines.push("Keep your existing LaunchDarkly `key` contexts, or use `targetingKey`");
+  lines.push("for new OpenFeature-native contexts:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("{ targetingKey: user.id } // or { key: user.id }");
+  lines.push("```");
+  lines.push("");
+  return lines;
+}
+async function formatDryRunDiff(analysis, source) {
+  const replacementsByFile = /* @__PURE__ */ new Map();
+  const skipped = [];
+  for (const item of analysis.inventoryItems) {
+    const result = buildReplacement(item);
+    if ("reason" in result) {
+      skipped.push(result);
+      continue;
+    }
+    if (!replacementsByFile.has(item.file)) replacementsByFile.set(item.file, []);
+    replacementsByFile.get(item.file).push(result);
+  }
+  const lines = [];
+  lines.push("# FlagLint migrate --dry-run");
+  lines.push("");
   lines.push(
-    "- OpenFeature React SDK: https://openfeature.dev/docs/reference/technologies/client/web/react"
+    "These diffs use the placeholder `openFeatureClient` and require OpenFeature provider/client setup before they can be applied."
   );
+  lines.push("No files are modified by dry-run output.");
   lines.push("");
+  lines.push(`Reviewable diffs: ${[...replacementsByFile.values()].reduce((sum, items) => sum + items.length, 0)}`);
+  lines.push(
+    `Diffs requiring provider setup: ${[...replacementsByFile.values()].reduce((sum, items) => sum + items.filter((item) => item.requiresProviderSetup).length, 0)}`
+  );
+  lines.push(`Skipped usages: ${skipped.length}`);
+  lines.push("");
+  lines.push(...formatProviderSetupSection());
+  if (replacementsByFile.size > 0) {
+    lines.push("## Diffs");
+    lines.push("```diff");
+    for (const [file, replacements] of [...replacementsByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      const before = await source.readFile(file);
+      const after = applyReplacements(before, replacements);
+      lines.push(...formatFileDiff(file, before, after));
+    }
+    lines.push("```");
+    lines.push("");
+  }
+  if (skipped.length > 0) {
+    lines.push("## Skipped Usages");
+    for (const { item, reason } of skipped) {
+      lines.push(`- ${item.file}:${item.line}:${item.column} \u2014 \`${itemLabel(item)}\` via \`${item.launchDarklyMethod}\`: ${reason}`);
+    }
+    lines.push("");
+  }
   return lines.join("\n");
 }
 
+// src/migrator/apply.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { parse as parse2 } from "@typescript-eslint/typescript-estree";
+var execFileAsync = promisify(execFile);
+var ApplyError = class extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+    this.name = "ApplyError";
+  }
+  kind;
+};
+var OF_SERVER_SDK = "@openfeature/server-sdk";
+function tryParse(code) {
+  for (const jsx of [false, true]) {
+    try {
+      return parse2(code, { jsx, comment: false });
+    } catch {
+    }
+  }
+  return null;
+}
+function walkNodes(root, visit) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    visit(node);
+    for (const val of Object.values(node)) {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item !== null && typeof item === "object" && "type" in item) {
+            stack.push(item);
+          }
+        }
+      } else if (val !== null && typeof val === "object" && "type" in val) {
+        stack.push(val);
+      }
+    }
+  }
+}
+function hasOpenFeatureClientBinding(code) {
+  const ast = tryParse(code);
+  if (!ast) return false;
+  const ofApiNames = /* @__PURE__ */ new Set();
+  for (const stmt of ast.body) {
+    if (stmt.type === "ImportDeclaration" && stmt.source.value === OF_SERVER_SDK) {
+      for (const spec of stmt.specifiers) {
+        if (spec.type === "ImportSpecifier") {
+          const importedName = spec.imported.type === "Identifier" ? spec.imported.name : spec.imported.value;
+          if (importedName === "OpenFeature") {
+            ofApiNames.add(spec.local.name);
+          }
+        }
+      }
+      continue;
+    }
+    if (stmt.type === "VariableDeclaration") {
+      for (const decl of stmt.declarations) {
+        const init = decl.init;
+        if (init?.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "require" && init.arguments.length === 1 && init.arguments[0]?.type === "Literal" && init.arguments[0].value === OF_SERVER_SDK && decl.id.type === "ObjectPattern") {
+          for (const prop of decl.id.properties) {
+            if (prop.type === "Property" && prop.key.type === "Identifier" && prop.key.name === "OpenFeature" && prop.value.type === "Identifier") {
+              ofApiNames.add(prop.value.name);
+            }
+          }
+        }
+      }
+    }
+  }
+  if (ofApiNames.size === 0) return false;
+  let proven = false;
+  walkNodes(ast, (node) => {
+    if (proven) return;
+    if (node.type !== "VariableDeclarator") return;
+    const decl = node;
+    if (decl.id.type !== "Identifier") return;
+    if (decl.id.name !== "openFeatureClient") return;
+    if (decl.init?.type !== "CallExpression") return;
+    const call = decl.init;
+    if (call.callee.type !== "MemberExpression") return;
+    const member = call.callee;
+    if (member.computed) return;
+    if (member.object.type !== "Identifier") return;
+    if (!ofApiNames.has(member.object.name)) return;
+    if (member.property.type !== "Identifier") return;
+    if (member.property.name !== "getClient") return;
+    proven = true;
+  });
+  return proven;
+}
+var DETAIL_METHODS2 = /* @__PURE__ */ new Set([
+  "variationDetail",
+  "boolVariationDetail",
+  "stringVariationDetail",
+  "numberVariationDetail",
+  "jsonVariationDetail"
+]);
+function methodForType2(valueType) {
+  switch (valueType) {
+    case "boolean":
+      return "getBooleanValue";
+    case "string":
+      return "getStringValue";
+    case "number":
+      return "getNumberValue";
+    case "object":
+      return "getObjectValue";
+    case "unknown":
+      return null;
+  }
+}
+function buildReplacement2(item, code) {
+  if (DETAIL_METHODS2.has(item.launchDarklyMethod)) {
+    return {
+      item,
+      reason: "detail methods skipped: OpenFeature detail APIs exist, but LaunchDarkly/OpenFeature detail result parity requires manual review"
+    };
+  }
+  if (!item.safelyAutomatable) {
+    const reason = item.manualReviewReason === "dynamic-key" ? "dynamic key requires manual review" : item.manualReviewReason === "unknown-fallback" ? "unknown fallback type requires manual review" : item.manualReviewReason === "bulk-inventory-call" ? "bulk inventory call has no single-flag codemod" : "manual review required";
+    return { item, reason };
+  }
+  if (item.rangeStart == null || item.rangeEnd == null || !item.callExpression) {
+    return { item, reason: "missing source range for apply" };
+  }
+  const currentText = code.slice(item.rangeStart, item.rangeEnd);
+  if (currentText !== item.callExpression) {
+    return {
+      item,
+      reason: "range content does not match original call \u2014 already transformed or stale analysis; skipping"
+    };
+  }
+  if (!item.flagKeyExpression || !item.fallbackExpression || !item.evaluationContextExpression) {
+    return { item, reason: "missing flag key, fallback, or evaluation context evidence" };
+  }
+  const method = methodForType2(item.valueType);
+  if (!method) return { item, reason: "unsupported or unknown value type" };
+  const call = `openFeatureClient.${method}(${item.flagKeyExpression}, ${item.fallbackExpression}, ${item.evaluationContextExpression})`;
+  return { item, replacement: call };
+}
+function applyReplacements2(code, replacements) {
+  let next = code;
+  for (const r of [...replacements].sort((a, b) => b.item.rangeStart - a.item.rangeStart)) {
+    next = next.slice(0, r.item.rangeStart) + r.replacement + next.slice(r.item.rangeEnd);
+  }
+  return next;
+}
+async function defaultIsWorkingTreeDirty() {
+  try {
+    const { stdout } = await execFileAsync("git", ["status", "--porcelain"]);
+    return stdout.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+async function applyMigration(analysis, source, options = {}) {
+  if (!options.allowDirty) {
+    const checkDirty = options.isWorkingTreeDirty ?? defaultIsWorkingTreeDirty;
+    if (await checkDirty()) {
+      throw new ApplyError(
+        "dirty-tree",
+        "Working tree has uncommitted changes.\nCommit or stash your changes first, or pass --allow-dirty to override.\nReview `flaglint migrate --dry-run` for provider setup guidance before applying."
+      );
+    }
+  }
+  const itemsByFile = /* @__PURE__ */ new Map();
+  for (const item of analysis.inventoryItems) {
+    if (!itemsByFile.has(item.file)) itemsByFile.set(item.file, []);
+    itemsByFile.get(item.file).push(item);
+  }
+  const transformedFiles = [];
+  const skippedFiles = [];
+  let transformed = 0;
+  for (const [file, items] of [...itemsByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const code = await source.readFile(file);
+    if (!hasOpenFeatureClientBinding(code)) {
+      skippedFiles.push({
+        file,
+        reason: "skipped \u2014 OpenFeature client setup required. Review `flaglint migrate --dry-run` provider guidance first."
+      });
+      continue;
+    }
+    const replacements = [];
+    for (const item of items) {
+      const result = buildReplacement2(item, code);
+      if ("reason" in result) continue;
+      replacements.push(result);
+    }
+    if (replacements.length === 0) continue;
+    const newCode = applyReplacements2(code, replacements);
+    if (newCode === code) continue;
+    await source.writeFile(file, newCode);
+    transformedFiles.push(file);
+    transformed += replacements.length;
+  }
+  return { transformed, skipped: skippedFiles.length, transformedFiles, skippedFiles };
+}
+
 // src/commands/migrate.ts
 function registerMigrateCommand(program2) {
-  program2.command("migrate").description("Analyze migration readiness and generate an OpenFeature migration plan").argument("[dir]", "directory to analyze", process.cwd()).option("-o, --output <file>", "write migration plan to file", "MIGRATION.md").option("-c, --config <path>", "path to .flaglintrc config file").option("--dry-run", "print migration plan to stdout without writing file").option("--exclude-tests", "exclude test files (*.test.*, *.spec.*, __tests__/, tests/)").addHelpText(
+  program2.command("migrate").description("Analyze migration readiness and generate an OpenFeature migration plan").argument("[dir]", "directory to analyze", process.cwd()).option("-o, --output <file>", "write migration plan to file", "MIGRATION.md").option("-c, --config <path>", "path to .flaglintrc config file").option("--dry-run", "print reviewable diffs to stdout without writing files").option("--apply", "apply safe transformations to source files in-place").option("--allow-dirty", "allow --apply on a dirty git working tree").option("--exclude-tests", "exclude test files (*.test.*, *.spec.*, __tests__/, tests/)").addHelpText(
     "after",
     `
 Examples:
   $ flaglint migrate                 generate migration plan for current directory
   $ flaglint migrate ./src           analyze specific directory
-  $ flaglint migrate --dry-run       preview without writing file
+  $ flaglint migrate --dry-run       preview diffs without writing files
+  $ flaglint migrate --apply         apply safe transformations in-place
+  $ flaglint migrate --apply --allow-dirty  apply even on a dirty working tree
   $ flaglint migrate --output plan.md write to custom file
   $ flaglint migrate --exclude-tests skip test and spec files`
   ).action(
     async (dir, options) => {
+      if (options.dryRun && options.apply) {
+        process.stderr.write(chalk2.red("Error: --dry-run and --apply are mutually exclusive.\n"));
+        process.exit(1);
+      }
       try {
         const s = await stat2(resolve5(dir));
         if (!s.isDirectory()) {
@@ -1081,12 +1610,13 @@ Examples:
         spinner.stop();
         process.exit(130);
       });
+      const source = new LocalFileSource(dir);
       let scanResult;
       try {
-        scanResult = await scan(new LocalFileSource(dir), scanConfig, (filesScanned) => {
+        scanResult = await scan(source, scanConfig, (filesScanned) => {
           spinner.text = `Scanning files... ${filesScanned}`;
         });
-        spinner.text = "Analyzing migration readiness...";
+        spinner.text = "Analyzing migration inventory...";
       } catch (err) {
         spinner.fail("Scan failed");
         process.stderr.write(chalk2.red(String(err)) + "\n");
@@ -1115,24 +1645,69 @@ Examples:
         const msg = w.kind === "read-failure" ? `warn: could not read ${w.file} (${w.fsCode})` : `warn: failed to parse ${w.file}`;
         process.stderr.write(chalk2.yellow(msg + "\n"));
       }
-      const { readinessScore } = analysis;
-      const scoreColor = readinessScore >= 80 ? chalk2.green : readinessScore >= 50 ? chalk2.yellow : chalk2.red;
-      process.stderr.write(scoreColor(`Migration Readiness Score: ${readinessScore}/100
+      const summaryColor = analysis.manualReviewCount > 0 ? chalk2.yellow : chalk2.green;
+      process.stderr.write(summaryColor(`LaunchDarkly usages found: ${analysis.totalLaunchDarklyUsages}
 `));
       process.stderr.write(
         chalk2.gray(
-          `Auto-migratable: ${analysis.autoMigrateCount} \xB7 Manual review: ${analysis.manualReviewCount}
+          `Safely automatable: ${analysis.safelyAutomatableCount} \xB7 Manual review: ${analysis.manualReviewCount}
 `
         )
       );
-      const report = formatMigrationReport(analysis);
       if (options.dryRun) {
-        process.stdout.write(report + "\n");
+        const report2 = await formatDryRunDiff(analysis, source);
+        process.stdout.write(report2 + "\n");
         process.exit(0);
       }
+      if (options.apply) {
+        let result;
+        try {
+          result = await applyMigration(analysis, source, { allowDirty: options.allowDirty });
+        } catch (err) {
+          if (err instanceof ApplyError && err.kind === "dirty-tree") {
+            process.stderr.write(chalk2.red(`
+Error: ${err.message}
+`));
+            process.exit(1);
+          }
+          process.stderr.write(chalk2.red(String(err)) + "\n");
+          process.exit(1);
+        }
+        if (result.transformed > 0) {
+          process.stderr.write(
+            chalk2.green(
+              `Transformed: ${result.transformed} call-site(s) across ${result.transformedFiles.length} file(s)
+`
+            )
+          );
+          for (const file of result.transformedFiles) {
+            process.stderr.write(chalk2.dim(`  \u2713 ${file}
+`));
+          }
+        } else {
+          process.stderr.write(chalk2.dim("No call-sites were transformed.\n"));
+        }
+        if (result.skipped > 0) {
+          process.stderr.write(
+            chalk2.yellow(`Skipped: ${result.skipped} file(s) \u2014 OpenFeature client setup required
+`)
+          );
+          for (const { file } of result.skippedFiles) {
+            process.stderr.write(
+              chalk2.dim(`  \u26A0 ${file}: no openFeatureClient binding found
+`)
+            );
+            process.stderr.write(
+              chalk2.dim("    Run `flaglint migrate --dry-run` for provider setup guidance.\n")
+            );
+          }
+        }
+        process.exit(0);
+      }
+      const report = formatMigrationReport(analysis);
       const outPath = resolve5(options.output);
       try {
-        await writeFile2(outPath, report, "utf8");
+        await writeFile3(outPath, report, "utf8");
         process.stderr.write(chalk2.green(`Migration plan written to ${options.output}
 `));
       } catch (err) {
@@ -1149,10 +1724,179 @@ Examples:
   );
 }
 
+// src/commands/validate.ts
+import { stat as stat3 } from "fs/promises";
+import { resolve as resolve6 } from "path";
+import chalk3 from "chalk";
+import ora3 from "ora";
+
+// src/validator/index.ts
+function matchesBootstrapPattern(file, patterns) {
+  const clean = (s) => s.replace(/^\.\//, "");
+  const cleanFile = clean(file);
+  return patterns.some((pattern) => {
+    const cleanPattern = clean(pattern);
+    if (cleanFile === cleanPattern) return true;
+    const regexStr = cleanPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\x00/g, ".*").replace(/\?/g, "[^/]");
+    try {
+      return new RegExp(`^${regexStr}$`).test(cleanFile);
+    } catch {
+      return false;
+    }
+  });
+}
+function validateScanResult(result, options = {}) {
+  const violations = [];
+  if (options.noDirectLaunchDarkly) {
+    const bootstrapExclude = options.bootstrapExclude ?? [];
+    for (const usage of result.usages) {
+      if (matchesBootstrapPattern(usage.file, bootstrapExclude)) continue;
+      violations.push({
+        file: usage.file,
+        line: usage.line,
+        column: usage.column,
+        callType: usage.callType,
+        flagKey: usage.flagKey,
+        isDynamic: usage.isDynamic
+      });
+    }
+  }
+  return {
+    scannedFiles: result.scannedFiles,
+    totalUsages: result.totalUsages,
+    violations,
+    passed: violations.length === 0
+  };
+}
+function violationLabel(v) {
+  if (v.isDynamic) return `${v.callType}(dynamic key \u2014 manual review required)`;
+  if (v.flagKey === "*") return `${v.callType}(bulk inventory)`;
+  return `${v.callType}("${v.flagKey}")`;
+}
+function formatValidationReport(result, options = {}) {
+  const lines = [];
+  if (!options.noDirectLaunchDarkly) {
+    lines.push(
+      `Scanned ${result.scannedFiles} file(s). Found ${result.totalUsages} LaunchDarkly usage(s).`
+    );
+    return lines.join("\n") + "\n";
+  }
+  if (result.passed) {
+    lines.push(
+      `\u2713 validate --no-direct-launchdarkly: no direct LaunchDarkly evaluation calls found.`
+    );
+    lines.push(`  Scanned ${result.scannedFiles} file(s).`);
+    return lines.join("\n") + "\n";
+  }
+  const count = result.violations.length;
+  lines.push(
+    `\u2717 validate --no-direct-launchdarkly: ${count} direct LaunchDarkly evaluation call(s) found.`
+  );
+  lines.push("");
+  for (const v of result.violations) {
+    lines.push(`  ${v.file}:${v.line}:${v.column} \u2014 ${violationLabel(v)}`);
+  }
+  lines.push("");
+  lines.push("These files must migrate to OpenFeature before this rule passes.");
+  lines.push("Run `flaglint migrate --dry-run` to review the migration plan.");
+  return lines.join("\n") + "\n";
+}
+
+// src/commands/validate.ts
+function registerValidateCommand(program2) {
+  program2.command("validate").description("Validate that your codebase complies with feature flag usage policies").argument("[dir]", "directory to validate", process.cwd()).option(
+    "--no-direct-launchdarkly",
+    "fail if any direct LaunchDarkly Node server SDK evaluation calls are found"
+  ).option(
+    "--bootstrap-exclude <glob>",
+    "glob pattern for files allowed to use LaunchDarkly SDK directly (repeatable)",
+    (val, prev) => [...prev, val],
+    []
+  ).option("-c, --config <path>", "path to .flaglintrc config file").addHelpText(
+    "after",
+    `
+Examples:
+  $ flaglint validate                                        scan and report LD usages
+  $ flaglint validate --no-direct-launchdarkly              fail on any direct LD eval calls
+  $ flaglint validate --no-direct-launchdarkly \\
+      --bootstrap-exclude src/provider/setup.ts             allow bootstrap file
+  $ flaglint validate --no-direct-launchdarkly \\
+      --bootstrap-exclude "src/provider/**"                 allow all provider files
+  $ flaglint validate --no-direct-launchdarkly \\
+      --bootstrap-exclude "src/provider/*.ts" \\
+      --bootstrap-exclude "src/bootstrap/**"                multiple exclusion patterns`
+  ).action(
+    async (dir, options) => {
+      try {
+        const s = await stat3(resolve6(dir));
+        if (!s.isDirectory()) {
+          process.stderr.write(chalk3.red(`Error: Not a directory: ${dir}
+`));
+          process.exit(1);
+        }
+      } catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+          process.stderr.write(chalk3.red(`Error: Directory not found: ${dir}
+`));
+        } else if (code === "EACCES") {
+          process.stderr.write(chalk3.red(`Error: Permission denied: ${dir}
+`));
+        } else {
+          process.stderr.write(chalk3.red(`Error: Cannot access directory: ${dir}
+`));
+        }
+        process.exit(1);
+      }
+      let config;
+      try {
+        config = await loadConfig(options.config);
+      } catch (err) {
+        process.stderr.write(chalk3.red(String(err instanceof Error ? err.message : err)) + "\n");
+        process.exit(1);
+      }
+      const spinner = ora3(`Scanning ${dir}...`).start();
+      process.once("SIGINT", () => {
+        spinner.stop();
+        process.exit(130);
+      });
+      const source = new LocalFileSource(dir);
+      let scanResult;
+      try {
+        scanResult = await scan(source, config, (filesScanned) => {
+          spinner.text = `Scanning files... ${filesScanned}`;
+        });
+        spinner.stop();
+      } catch (err) {
+        spinner.fail("Scan failed");
+        process.stderr.write(chalk3.red(String(err)) + "\n");
+        process.exit(1);
+      }
+      for (const w of scanResult.warnings) {
+        const msg = w.kind === "read-failure" ? `warn: could not read ${w.file} (${w.fsCode})` : `warn: failed to parse ${w.file}`;
+        process.stderr.write(chalk3.yellow(msg + "\n"));
+      }
+      const noDirectLaunchDarkly = options.directLaunchdarkly === false;
+      const bootstrapExclude = options.bootstrapExclude ?? [];
+      const validateOptions = {
+        noDirectLaunchDarkly,
+        bootstrapExclude
+      };
+      const validationResult = validateScanResult(scanResult, validateOptions);
+      const report = formatValidationReport(validationResult, validateOptions);
+      process.stdout.write(report);
+      if (!validationResult.passed) {
+        process.exit(1);
+      }
+      process.exit(0);
+    }
+  );
+}
+
 // src/cli.ts
 function createCLI() {
   const program2 = new Command();
-  program2.name("flaglint").description("Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.").version("0.3.0", "-v, --version", "output the current version").addHelpText(
+  program2.name("flaglint").description("LaunchDarkly Node.js server SDK -> OpenFeature migration.").version("0.4.1", "-v, --version", "output the current version").addHelpText(
     "after",
     `
 Examples:
@@ -1161,10 +1905,12 @@ Examples:
   $ flaglint scan --format json      output as JSON
   $ flaglint scan --output report.md save to file
   $ flaglint migrate                 generate migration plan
-  $ flaglint migrate --dry-run       preview without writing`
+  $ flaglint migrate --dry-run       preview without writing
+  $ flaglint validate --no-direct-launchdarkly  enforce OF migration in CI`
   );
   registerScanCommand(program2);
   registerMigrateCommand(program2);
+  registerValidateCommand(program2);
   return program2;
 }