flaglint 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-06-07
+
+### Added
+
+- `flaglint audit --cost-estimate` — adds a directional migration-effort estimate to
+  audit output. Computes low/high hour ranges from automatable and manual-review call
+  counts using configurable planning heuristics.
+- `flaglint audit --hourly-rate <rate>` — adds engineering cost projection
+  (`costLow`/`costHigh`) to the estimate. Requires `--cost-estimate`.
+- Migration readiness score displayed in `flaglint audit` terminal output: 0–100 ratio
+  of safely automatable calls to total detected LaunchDarkly calls, with grade
+  (`ready` | `moderate` | `complex` | `not-applicable`) and progress bar.
+- New docs pages: Migration Readiness concept page and Cost Estimation CLI reference.
+
+---
+
 ## [0.6.0] - 2026-06-02
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Standardize LaunchDarkly usage on OpenFeature.</strong>
+  <strong>Find every direct LaunchDarkly SDK call. Migrate safely. Enforce the boundary.</strong>
 </p>
 
 <p align="center">
@@ -21,99 +21,103 @@
   </a>
 </p>
 
-# FlagLint
-
-**The argument-order difference between LaunchDarkly and OpenFeature 
-silently breaks flag evaluations in production. FlagLint catches it.**
-
-FlagLint inventories direct LaunchDarkly Node.js SDK calls, generates reviewable migration plans,
-and prevents new vendor-coupled flag access from entering your codebase.
-LaunchDarkly remains your provider. OpenFeature becomes the evaluation API your application code calls.
-
-**[Documentation](https://flaglint.dev/docs)** · **[Quickstart](https://flaglint.dev/docs/quickstart)** · **[Enterprise Demo](https://flaglint.dev/docs/enterprise-demo)** · **[npm](https://npmjs.com/package/flaglint)** · **[Issues](https://github.com/flaglint/flaglint/issues)**
-
-![FlagLint demo](./flaglint-demo.gif)
-
 ---
 
-## Quick start
+Most teams do not know how many direct LaunchDarkly SDK calls are in their codebase, which ones are safe to migrate, or which ones will silently break if migrated naively. FlagLint answers all three questions before you touch a line of code.
 
 ```bash
-npx flaglint scan ./src
+npx flaglint audit ./src
 ```
 
 ```
-✔ Scanning 5 files...
-✔ Found 20 direct LaunchDarkly Node SDK calls across 11 unique flags
-⚡ 6 dynamic flag keys — manual review required
-↳ 2 detail method calls — manual review required
+✓ Audit complete: 13 flags — 3 high risk, 10 medium risk
 
-→ Run flaglint migrate --dry-run for a reviewable migration diff
+Migration readiness: 50/100  ·  moderate
+[█████████████░░░░░░░░░░░░] 50%
+10 safely automatable  ·  10 require manual review
 ```
 
-Preview the migration before changing anything:
+Add `--cost-estimate` to include a directional planning estimate:
 
 ```bash
-npx flaglint migrate ./src --dry-run
+npx flaglint audit ./src --cost-estimate
 ```
 
----
+```
+✓ Audit complete: 13 flags — 3 high risk, 10 medium risk
 
-## Workflow
+Migration readiness: 50/100  ·  moderate
+[█████████████░░░░░░░░░░░░] 50%
+10 safely automatable  ·  10 require manual review
+
+Estimated migration effort: 22.8h – 43.9h
+Estimates are directional. See the report for assumptions.
+```
 
-| Step | Command | What happens |
-|------|---------|-------------|
-| 1 | `flaglint scan ./src` | AST inventory of every direct LD Node server SDK call |
-| 2 | `flaglint migrate --dry-run` | Reviewable before/after diffs; inline provider setup guidance |
-| 3 | `flaglint migrate --apply` | Rewrites only guarded, provably automatable call-sites |
-| 4 | `flaglint validate --no-direct-launchdarkly` | CI gate: exit 1 if direct LD evaluation calls remain |
+For the full report see `--format html`. [Documentation](https://flaglint.dev/docs) · [Quickstart](https://flaglint.dev/docs/quickstart) · [npm](https://npmjs.com/package/flaglint)
+
+No API key. No source upload. LaunchDarkly stays your provider — OpenFeature becomes the evaluation API your application calls.
 
 ---
 
-### `flaglint audit [dir]`
+## The problem FlagLint solves
 
-Generates a local flag debt audit report. No API keys or credentials needed.
+The OpenFeature `getBooleanValue(key, defaultValue, context)` API takes arguments in a different order from LaunchDarkly's `boolVariation(key, context, defaultValue)`. A naive find-and-replace silently swaps your fallback and context, producing valid-looking code that evaluates flags incorrectly in production.
 
-```bash
-flaglint audit ./src
-flaglint audit ./src --format html --output audit.html
-flaglint audit ./src --format json
-```
+FlagLint's static analysis proves — before rewriting anything — that the flag key is static, the fallback value and type are known, and a verified OpenFeature client binding is present. If any condition cannot be proven, the call is reported for manual review and left untouched.
 
-Produces a risk-scored inventory of every LaunchDarkly flag in your codebase — sorted by risk level (high / medium / low) with the reasons for each rating. Useful for planning migration scope before running `migrate --dry-run`.
+---
+
+## Workflow
+
+| Step | Command | What it does |
+|------|---------|--------------|
+| 1 | `flaglint audit ./src` | Risk-ranked overview. High / medium / low per flag. No API key needed. |
+| 2 | `flaglint scan ./src` | Detailed file-level structured inventory for automation or review. |
+| 3 | `flaglint migrate ./src --dry-run` | Reviewable before/after diffs. Shows exactly what will change. |
+| 4 | `flaglint migrate ./src --apply` | Rewrites only calls with proven static inputs and a verified OpenFeature binding. |
+| 5 | `flaglint validate ./src --no-direct-launchdarkly` | CI gate — exits 1 if any direct LD evaluation call remains. |
 
 ---
 
-## Before → After (real output from enterprise demo)
+## Before and after
 
 ```diff
---- a/checkout.ts
-+++ b/checkout.ts
+--- a/src/routes/checkout.ts
++++ b/src/routes/checkout.ts
 -  return ldClient.boolVariation("checkout-v2", ctx, false);
 +  return openFeatureClient.getBooleanValue("checkout-v2", false, ctx);
 
 -  return ldClient.stringVariation("payment-provider", ctx, "stripe");
 +  return openFeatureClient.getStringValue("payment-provider", "stripe", ctx);
 
---- a/pricing.ts
-+++ b/pricing.ts
+--- a/src/services/pricing.ts
++++ b/src/services/pricing.ts
 -  return ldClient.numberVariation("discount-percentage", ctx, 0);
 +  return openFeatureClient.getNumberValue("discount-percentage", 0, ctx);
 ```
 
-Flag key, fallback value, `await`, and evaluation context are preserved exactly.
+Flag key, fallback value, evaluation context, and `await` are preserved exactly. The LaunchDarkly packages stay — the OpenFeature provider depends on them at runtime.
 
 ---
 
-## Supported scope
+## What is never auto-rewritten
+
+FlagLint is intentionally conservative. These are always skipped and reported for manual review:
 
-LaunchDarkly Node.js server-side SDK calls from `launchdarkly-node-server-sdk` and
-`@launchdarkly/node-server-sdk`. Both ESM import and CJS `require()` forms.
+- **Dynamic keys** — `ldClient.boolVariation(getFlagKey(user), ctx, false)`
+- **Detail evaluations** — `boolVariationDetail`, `variationDetail`
+- **Bulk calls** — `allFlags()`, `allFlagsState()`
+- **Unknown fallback types**
+- **Configured wrappers**
+- **Ambiguous OpenFeature client bindings**
+- **Browser SDKs, React SDKs, non-Node SDKs**
 
-`--apply` rewrites `boolVariation`, `stringVariation`, `numberVariation`, `jsonVariation`
-where the flag key, fallback, and OpenFeature client binding are statically explicit.
-Detail methods, dynamic keys, bulk calls, and unknown fallback types are reported for manual review.
-Browser SDKs, React SDKs, and non-LaunchDarkly providers are outside current scope.
+---
+
+## Supported scope
+
+LaunchDarkly Node.js server-side SDK calls from `@launchdarkly/node-server-sdk` and `launchdarkly-node-server-sdk`. Both ESM and CommonJS. Node.js 20 or newer.
 
 Full coverage table: [Supported Scope](https://flaglint.dev/docs/reference/supported-scope)
 
@@ -121,29 +125,30 @@ Full coverage table: [Supported Scope](https://flaglint.dev/docs/reference/suppo
 
 ## Provider setup (one-time, manual)
 
-Before `--apply`, complete bootstrap setup once. Full instructions:
-[OpenFeature Provider Setup](https://flaglint.dev/docs/integrations/openfeature-provider)
+Before `migrate --apply`, complete provider bootstrap once:
 
-Key points:
-- `new LaunchDarklyProvider(process.env.LD_SDK_KEY!)` — SDK key constructor
-- Evaluation context accepts either `targetingKey` (OpenFeature-native) or an existing LaunchDarkly `key`
-- **Do not remove LaunchDarkly packages** — the OpenFeature provider depends on them at runtime
+```ts
+import { OpenFeature } from "@openfeature/server-sdk";
+import { LaunchDarklyProvider } from "@launchdarkly/openfeature-node-server";
 
----
+await OpenFeature.setProviderAndWait(
+  new LaunchDarklyProvider(process.env.LD_SDK_KEY!)
+);
+export const openFeatureClient = OpenFeature.getClient();
+```
 
-## Requirements
+Evaluation context accepts either `targetingKey` (OpenFeature-native) or an existing LaunchDarkly `key`. Do not remove LaunchDarkly packages — the OpenFeature provider depends on them at runtime.
 
-Node.js 20 or newer. No LaunchDarkly SDK key or credentials required for scan or migrate.
+Full instructions: [OpenFeature Provider Setup](https://flaglint.dev/docs/tutorials/add-openfeature-provider)
 
 ---
 
 ## Local analysis
 
-FlagLint runs entirely on your machine. No source code, flag keys, or file paths are
-transmitted to any external service. No outbound network connections during scan or migration.
+FlagLint runs entirely on your machine. No source code, flag keys, or file paths leave your environment. No LaunchDarkly API key or credentials are required for `audit`, `scan`, `migrate`, or `validate`.
 
 ---
 
 ## Links
 
-[Security](./SECURITY.md) · [Contributing](./CONTRIBUTING.md) · [Changelog](./CHANGELOG.md) · [License](./LICENSE) · [Full docs](https://flaglint.dev/docs)
+**[Docs](https://flaglint.dev/docs)** · **[Quickstart](https://flaglint.dev/docs/quickstart)** · **[Blog](https://flaglint.dev/blog)** · [Security](./SECURITY.md) · [Contributing](./CONTRIBUTING.md) · [Changelog](./CHANGELOG.md) · [License](./LICENSE)

package/dist/bin/flaglint.js

@@ -789,7 +789,7 @@ function formatHTML(result, options) {
     <div class="card"><div class="card-num orange">${manualCount}</div><div class="card-label">Manual Review (${manualPct}%)</div></div>
     <div class="card"><div class="card-num blue">${detailBulkCount}</div><div class="card-label">Detail/Bulk Calls</div></div>` : "";
   const title = options.title ? esc(options.title) : "FlagLint Scan Report";
-  const version = true ? "0.6.0" : "0.1.0";
+  const version = true ? "0.7.0" : "0.1.0";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -1116,6 +1116,89 @@ import { resolve as resolve5 } from "path";
 import chalk2 from "chalk";
 import ora2 from "ora";
 
+// src/readiness/readiness.ts
+var ISSUE_SPECS = [
+  {
+    code: "dynamic-key",
+    label: "Dynamic flag keys",
+    explanation: "Flag keys determined at runtime cannot be safely rewritten."
+  },
+  {
+    code: "detail-evaluation",
+    label: "Detail evaluations",
+    explanation: "Detail evaluation methods require manual migration to OpenFeature equivalents."
+  },
+  {
+    code: "bulk-evaluation",
+    label: "Bulk evaluations",
+    explanation: "Bulk flag evaluation calls have no direct OpenFeature equivalent."
+  },
+  {
+    code: "unknown-fallback",
+    label: "Unknown fallback values",
+    explanation: "Calls without a known fallback value type cannot be safely auto-migrated."
+  },
+  {
+    code: "ambiguous-client",
+    label: "Ambiguous client bindings",
+    explanation: "Calls without a proven OpenFeature client binding require manual setup."
+  }
+];
+function gradeFromScore(score) {
+  if (score >= 80) return "ready";
+  if (score >= 50) return "moderate";
+  return "complex";
+}
+function computeReadiness(usages, inventory) {
+  const totalCalls = inventory.length > 0 ? inventory.length : usages.length;
+  if (totalCalls === 0) {
+    return {
+      score: null,
+      grade: "not-applicable",
+      totalCalls: 0,
+      automatableCalls: 0,
+      manualReviewCalls: 0,
+      manualReviewBreakdown: []
+    };
+  }
+  const automatableCalls = inventory.length > 0 ? inventory.filter((i) => i.safelyAutomatable).length : usages.filter(
+    (u) => !u.isDynamic && u.callType !== "allFlags" && u.callType !== "allFlagsState" && !u.callType.includes("Detail") && u.callType !== "variationDetail"
+  ).length;
+  const manualReviewCalls = totalCalls - automatableCalls;
+  const score = totalCalls > 0 ? Math.max(0, Math.round(automatableCalls / totalCalls * 100)) : 0;
+  const dynamicKeyCount = inventory.length > 0 ? inventory.filter((i) => i.manualReviewReason === "dynamic-key").length : usages.filter((u) => u.isDynamic).length;
+  const detailEvalCount = inventory.length > 0 ? inventory.filter((i) => i.manualReviewReason === "detail-method").length : usages.filter((u) => u.callType.includes("Detail")).length;
+  const bulkEvalCount = inventory.length > 0 ? inventory.filter((i) => i.manualReviewReason === "bulk-inventory-call").length : usages.filter((u) => u.callType === "allFlags" || u.callType === "allFlagsState").length;
+  const unknownFallbackCount = inventory.length > 0 ? inventory.filter((i) => i.manualReviewReason === "unknown-fallback").length : 0;
+  const ambiguousClientCount = inventory.length > 0 ? inventory.filter((i) => !i.safelyAutomatable && i.manualReviewReason === void 0).length : 0;
+  const occurrences = {
+    "dynamic-key": dynamicKeyCount,
+    "detail-evaluation": detailEvalCount,
+    "bulk-evaluation": bulkEvalCount,
+    "unknown-fallback": unknownFallbackCount,
+    "ambiguous-client": ambiguousClientCount
+  };
+  const manualReviewBreakdown = [];
+  for (const spec of ISSUE_SPECS) {
+    const count = occurrences[spec.code] ?? 0;
+    if (count === 0) continue;
+    manualReviewBreakdown.push({
+      code: spec.code,
+      label: spec.label,
+      count,
+      explanation: spec.explanation
+    });
+  }
+  return {
+    score,
+    grade: gradeFromScore(score),
+    totalCalls,
+    automatableCalls,
+    manualReviewCalls,
+    manualReviewBreakdown
+  };
+}
+
 // src/migrator/index.ts
 function legacyInventoryFromUsage(usage) {
   const isBulk = usage.flagKey === "*" || usage.callType === "allFlags" || usage.callType === "allFlagsState";
@@ -1194,12 +1277,6 @@ function buildEvidenceItem(item) {
     reviewReason: item.safelyAutomatable ? void 0 : reasonLabel(item.manualReviewReason)
   };
 }
-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"] : [];
 }
@@ -1217,7 +1294,7 @@ function analyze(result) {
   ).length;
   const manualReviewCount = totalLaunchDarklyUsages - safelyAutomatableCount;
   const autoMigrateCount = safelyAutomatableCount;
-  const readinessScore = calcReadinessScore(inventoryItems);
+  const readinessScore = computeReadiness(result.usages, inventoryItems).score ?? 0;
   const requiredPackages = calcRequiredPackages(inventoryItems);
   return {
     readinessScore,
@@ -1245,7 +1322,7 @@ function formatMigrationReport(analysis) {
     unsupportedUnknownCount
   } = analysis;
   const date = (/* @__PURE__ */ new Date()).toLocaleDateString();
-  const version = true ? "0.6.0" : "0.1.0";
+  const version = true ? "0.7.0" : "0.1.0";
   const lines = [];
   lines.push("# OpenFeature Migration Inventory");
   lines.push(`Generated by FlagLint v${version} on ${date}`);
@@ -2117,18 +2194,34 @@ function buildAuditReport(scanResult, inventoryItems) {
     scannedAt: scanResult.scannedAt,
     scanRoot: scanResult.scanRoot
   };
-  return { summary, flags };
+  const readiness = computeReadiness(scanResult.usages, inventoryItems);
+  return { summary, flags, readiness };
+}
+
+// src/readiness/readiness-bar.ts
+function renderReadinessBar(score) {
+  const filled = Math.round(score / 100 * 25);
+  const empty = 25 - filled;
+  return "[" + "\u2588".repeat(filled) + "\u2591".repeat(empty) + "] " + score + "%";
 }
 
 // src/auditor/reporter.ts
 function esc2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function formatAuditJson(report) {
-  return JSON.stringify(report, null, 2);
+function displayFlagKey(flag) {
+  return flag.isDynamic ? "<dynamic key>" : flag.flagKey;
 }
-function formatAuditMarkdown(report) {
-  const { summary, flags } = report;
+function formatAuditJson(report, options) {
+  const { summary, flags, readiness } = report;
+  const obj = { summary, flags, readiness };
+  if (options !== void 0) {
+    obj["estimate"] = options.estimate ?? null;
+  }
+  return JSON.stringify(obj, null, 2);
+}
+function formatAuditMarkdown(report, options) {
+  const { summary, flags, readiness } = report;
   const lines = [];
   lines.push("# FlagLint Audit Report");
   lines.push("");
@@ -2139,11 +2232,19 @@ function formatAuditMarkdown(report) {
   lines.push("");
   lines.push("## Summary");
   lines.push("");
-  lines.push("| Total Flags | High Risk | Medium Risk | Low Risk | Total Usages |");
-  lines.push("|-------------|-----------|-------------|----------|--------------|");
-  lines.push(
-    `| ${summary.totalFlags} | ${summary.highRisk} | ${summary.mediumRisk} | ${summary.lowRisk} | ${summary.totalUsages} |`
-  );
+  if (summary.lowRisk > 0) {
+    lines.push("| Total Flags | High Risk | Medium Risk | Low Risk | Total Usages |");
+    lines.push("|-------------|-----------|-------------|----------|--------------|");
+    lines.push(
+      `| ${summary.totalFlags} | ${summary.highRisk} | ${summary.mediumRisk} | ${summary.lowRisk} | ${summary.totalUsages} |`
+    );
+  } else {
+    lines.push("| Total Flags | High Risk | Medium Risk | Total Usages |");
+    lines.push("|-------------|-----------|-------------|--------------|");
+    lines.push(
+      `| ${summary.totalFlags} | ${summary.highRisk} | ${summary.mediumRisk} | ${summary.totalUsages} |`
+    );
+  }
   lines.push("");
   lines.push(
     "| Dynamic Keys | Detail Evals | Bulk Calls | Stale Signals | Safely Automatable | Manual Review |"
@@ -2155,6 +2256,46 @@ function formatAuditMarkdown(report) {
     `| ${summary.dynamicKeys} | ${summary.detailEvaluations} | ${summary.bulkCalls} | ${summary.staleSignals} | ${summary.safelyAutomatable} | ${summary.manualReview} |`
   );
   lines.push("");
+  lines.push("## Migration Readiness");
+  lines.push("");
+  if (readiness.grade === "not-applicable") {
+    lines.push("Migration readiness: **N/A** \u2014 no direct LaunchDarkly calls detected.");
+  } else {
+    lines.push(`Migration readiness: **${readiness.score}/100** \xB7 ${readiness.grade}`);
+    lines.push("");
+    lines.push(renderReadinessBar(readiness.score));
+    lines.push("");
+    lines.push(
+      `${readiness.automatableCalls} safely automatable  \xB7  ${readiness.manualReviewCalls} require manual review`
+    );
+  }
+  lines.push("");
+  if (options?.estimate !== void 0) {
+    const est = options.estimate;
+    lines.push("## Estimated Migration Effort");
+    lines.push("");
+    if (est === null) {
+      lines.push("N/A \u2014 no direct LaunchDarkly calls detected.");
+    } else {
+      lines.push("| | Low | High |");
+      lines.push("|---|---|---|");
+      for (const item of est.breakdown) {
+        const callsLabel = item.calls > 0 ? ` (${item.calls} calls)` : "";
+        lines.push(`| ${item.label}${callsLabel} | ${item.hoursLow}h | ${item.hoursHigh}h |`);
+      }
+      lines.push(`| **Total** | **${est.hoursLow}h** | **${est.hoursHigh}h** |`);
+      lines.push("");
+      if (est.costLow !== void 0 && est.costHigh !== void 0) {
+        const fmt = (n) => "$" + n.toLocaleString("en-US");
+        lines.push(`Estimated cost: **${fmt(est.costLow)} \u2013 ${fmt(est.costHigh)}** (at $${est.hourlyRate}/hr)`);
+        lines.push("");
+      }
+      lines.push(`> ${est.disclaimer}`);
+      lines.push("");
+      lines.push("_Assumptions: configurable planning heuristics, not observed industry benchmarks._");
+    }
+    lines.push("");
+  }
   lines.push("## Flag Debt Inventory");
   lines.push("");
   lines.push("| Flag Key | Risk | Usages | Files | Call Types | Reasons |");
@@ -2166,8 +2307,9 @@ function formatAuditMarkdown(report) {
   };
   for (const flag of flags) {
     const reasons = flag.riskReasons.join(", ") || "\u2014";
+    const flagKey = displayFlagKey(flag);
     lines.push(
-      `| \`${flag.flagKey}\` | ${riskLabel[flag.riskLevel]} | ${flag.usageCount} | ${flag.fileCount} | ${flag.callTypes.join(", ")} | ${reasons} |`
+      `| \`${flagKey}\` | ${riskLabel[flag.riskLevel]} | ${flag.usageCount} | ${flag.fileCount} | ${flag.callTypes.join(", ")} | ${reasons} |`
     );
   }
   lines.push("");
@@ -2185,9 +2327,9 @@ function formatAuditMarkdown(report) {
   lines.push("");
   return lines.join("\n");
 }
-function formatAuditHtml(report) {
-  const { summary, flags } = report;
-  const version = true ? "0.6.0" : "0.1.0";
+function formatAuditHtml(report, options) {
+  const { summary, flags, readiness } = report;
+  const version = true ? "0.7.0" : "0.1.0";
   const date = new Date(summary.scannedAt).toLocaleString();
   const riskBadge = (level) => {
     if (level === "high")
@@ -2198,8 +2340,9 @@ function formatAuditHtml(report) {
   };
   const rows = flags.map((f) => {
     const reasons = f.riskReasons.length > 0 ? esc2(f.riskReasons.join(", ")) : "\u2014";
+    const flagKey = displayFlagKey(f);
     return `<tr>
-          <td><code>${esc2(f.flagKey)}</code></td>
+          <td><code>${esc2(flagKey)}</code></td>
           <td>${riskBadge(f.riskLevel)}</td>
           <td>${f.usageCount}</td>
           <td>${f.fileCount}</td>
@@ -2207,6 +2350,55 @@ function formatAuditHtml(report) {
           <td>${reasons}</td>
         </tr>`;
   }).join("\n        ");
+  const readinessScore = readiness.score ?? 0;
+  const readinessColor = readiness.grade === "not-applicable" ? "#6c757d" : readinessScore >= 80 ? "#16a34a" : readinessScore >= 50 ? "#d97706" : "#dc2626";
+  const readinessFillPct = readinessScore;
+  let estimateSection = "";
+  if (options?.estimate !== void 0) {
+    const est = options.estimate;
+    if (est === null) {
+      estimateSection = `
+  <h2>Estimated Migration Effort</h2>
+  <div class="estimate-block"><p style="color:var(--muted)">N/A \u2014 no direct LaunchDarkly calls detected.</p></div>`;
+    } else {
+      const fmtCost = (n) => "$" + n.toLocaleString("en-US");
+      const costLine = est.costLow !== void 0 && est.costHigh !== void 0 ? `<div class="estimate-cost">${fmtCost(est.costLow)} \u2013 ${fmtCost(est.costHigh)} <span style="font-weight:400;font-size:.8em">at $${est.hourlyRate}/hr</span></div>` : "";
+      const bRows = est.breakdown.map((item) => {
+        const callsLabel = item.calls > 0 ? ` <span style="color:var(--muted);font-size:.85em">(${item.calls} calls)</span>` : "";
+        return `<tr><td>${esc2(item.label)}${callsLabel}</td><td>${item.hoursLow}h</td><td>${item.hoursHigh}h</td><td style="color:var(--muted);font-size:.8em">${esc2(item.basis)}</td></tr>`;
+      }).join("\n        ");
+      const { assumptions } = est;
+      estimateSection = `
+  <h2>Estimated Migration Effort</h2>
+  <div class="estimate-block">
+    <div class="estimate-total">${est.hoursLow}h \u2013 ${est.hoursHigh}h</div>
+    ${costLine}
+    <table style="margin-top:.75rem">
+      <thead><tr><th>Work Item</th><th>Low</th><th>High</th><th>Basis</th></tr></thead>
+      <tbody>
+        ${bRows}
+      </tbody>
+    </table>
+    <details style="margin-top:.75rem;font-size:.8125rem">
+      <summary style="cursor:pointer;color:var(--muted);user-select:none">Estimation assumptions</summary>
+      <table style="margin-top:.5rem">
+        <thead><tr><th>Parameter</th><th>Value</th></tr></thead>
+        <tbody>
+          <tr><td>Automatable call</td><td>${assumptions.automationHoursPerCall}h</td></tr>
+          <tr><td>Manual-review call</td><td>${assumptions.manualReviewHoursPerCall}h</td></tr>
+          <tr><td>Validation</td><td>${assumptions.validationMultiplier * 100}% of migration work</td></tr>
+          <tr><td>Minimum estimate</td><td>${assumptions.minimumHours}h</td></tr>
+        </tbody>
+      </table>
+      <p style="margin-top:.5rem;color:var(--muted)">These are configurable planning heuristics, not observed industry benchmarks.</p>
+    </details>
+    <p class="estimate-disclaimer">${esc2(est.disclaimer)}</p>
+  </div>`;
+    }
+  }
+  const breakdownRows = readiness.manualReviewBreakdown.map(
+    (d) => `<tr><td>${esc2(d.label)}</td><td>${d.count}</td><td style="color:var(--muted);font-size:.8em">${esc2(d.explanation)}</td></tr>`
+  ).join("\n        ");
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -2231,6 +2423,14 @@ function formatAuditHtml(report) {
     .card-num.purple{color:#7c3aed}
     .card-num.orange{color:#ea580c}
     .card-label{color:var(--muted);font-size:.75rem;margin-top:.375rem;text-transform:uppercase;letter-spacing:.05em}
+    .readiness-block{background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:1.25rem;margin-bottom:1.5rem}
+    .readiness-score-line{display:flex;align-items:baseline;gap:.75rem;margin-bottom:.75rem}
+    .readiness-score-num{font-size:2.5rem;font-weight:700;line-height:1}
+    .readiness-grade{font-size:.875rem;font-weight:600;text-transform:uppercase;letter-spacing:.05em}
+    .readiness-bar-track{height:12px;background:var(--border);border-radius:6px;overflow:hidden;margin-bottom:.75rem}
+    .readiness-bar-fill{height:100%;border-radius:6px;transition:width .3s}
+    .readiness-stats{display:flex;gap:2rem;font-size:.875rem;color:var(--muted);flex-wrap:wrap}
+    .readiness-norm{margin-top:.5rem;font-size:.8em;color:var(--muted)}
     table{width:100%;border-collapse:collapse;font-size:.8125rem}
     th{text-align:left;padding:.625rem .75rem;background:var(--surface);border-bottom:2px solid var(--border);font-weight:600;white-space:nowrap}
     td{padding:.625rem .75rem;border-bottom:1px solid var(--border);vertical-align:top}
@@ -2244,6 +2444,10 @@ function formatAuditHtml(report) {
       .badge-medium{background:#78350f;color:#fcd34d}
       .badge-low{background:#14532d;color:#86efac}
     }
+    .estimate-block{background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:1.25rem;margin-bottom:1.5rem}
+    .estimate-total{font-size:1.5rem;font-weight:700;margin-bottom:.75rem}
+    .estimate-cost{font-size:1rem;font-weight:600;margin:.75rem 0;color:#3b82f6}
+    .estimate-disclaimer{margin-top:.75rem;font-size:.75rem;color:var(--muted);font-style:italic}
     .steps{margin:.75rem 0 1rem 1.25rem;line-height:2}
     footer{margin-top:3rem;padding-top:1rem;border-top:1px solid var(--border);color:var(--muted);font-size:.75rem;text-align:center}
     footer a{color:var(--muted)}
@@ -2260,11 +2464,38 @@ function formatAuditHtml(report) {
     <div class="card"><div class="card-num">${summary.totalFlags}</div><div class="card-label">Total Flags</div></div>
     <div class="card"><div class="card-num red">${summary.highRisk}</div><div class="card-label">High Risk</div></div>
     <div class="card"><div class="card-num amber">${summary.mediumRisk}</div><div class="card-label">Medium Risk</div></div>
-    <div class="card"><div class="card-num green">${summary.lowRisk}</div><div class="card-label">Low Risk</div></div>
+    ${summary.lowRisk > 0 ? `<div class="card"><div class="card-num green">${summary.lowRisk}</div><div class="card-label">Low Risk</div></div>` : ""}
     <div class="card"><div class="card-num purple">${summary.safelyAutomatable}</div><div class="card-label">Safely Automatable</div></div>
     <div class="card"><div class="card-num orange">${summary.manualReview}</div><div class="card-label">Manual Review</div></div>
   </div>
 
+  <h2>Migration Readiness</h2>
+  <div class="readiness-block">
+    ${readiness.grade === "not-applicable" ? `
+    <div class="readiness-stats">N/A \u2014 no direct LaunchDarkly calls detected.</div>` : `
+    <div class="readiness-score-line">
+      <span class="readiness-score-num" style="color:${readinessColor}">${readinessScore}</span>
+      <span style="color:var(--muted);font-size:1.25rem">/100</span>
+      <span class="readiness-grade" style="color:${readinessColor}">${readiness.grade}</span>
+    </div>
+    <div class="readiness-bar-track">
+      <div class="readiness-bar-fill" style="width:${readinessFillPct}%;background:${readinessColor}"></div>
+    </div>
+    <div class="readiness-stats">
+      <span>${readiness.automatableCalls} safely automatable</span>
+      <span>${readiness.manualReviewCalls} require manual review</span>
+      <span>${readiness.totalCalls} total calls</span>
+    </div>
+    ${readiness.manualReviewBreakdown.length > 0 ? `
+    <table style="margin-top:1rem">
+      <thead><tr><th>Issue</th><th>Occurrences</th><th>Explanation</th></tr></thead>
+      <tbody>
+        ${breakdownRows}
+      </tbody>
+    </table>` : ""}`}
+  </div>
+  ${estimateSection}
+
   <h2>Flag Debt Inventory</h2>
   <table>
     <thead>
@@ -2296,16 +2527,81 @@ function formatAuditHtml(report) {
 </html>`;
 }
 
+// src/estimate/estimate.ts
+var ESTIMATE_DISCLAIMER = "Estimates are directional planning guides based on call-site complexity. Actual effort depends on test coverage, team familiarity, and provider setup. FlagLint does not access runtime data or LaunchDarkly billing.";
+var DEFAULT_ASSUMPTIONS = {
+  automationHoursPerCall: 0.25,
+  manualReviewHoursPerCall: 1.5,
+  validationMultiplier: 0.3,
+  minimumHours: 4
+};
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+function computeEstimate(readiness, overrides, hourlyRate) {
+  if (readiness.grade === "not-applicable") return null;
+  const assumptions = { ...DEFAULT_ASSUMPTIONS, ...overrides };
+  const { automatableCalls, manualReviewCalls } = readiness;
+  const automationLow = automatableCalls * assumptions.automationHoursPerCall;
+  const automationHigh = automationLow * 1.5;
+  const manualLow = manualReviewCalls * assumptions.manualReviewHoursPerCall;
+  const manualHigh = manualLow * 2;
+  const validationLow = (automationLow + manualLow) * assumptions.validationMultiplier;
+  const validationHigh = (automationHigh + manualHigh) * assumptions.validationMultiplier;
+  const rawLow = automationLow + manualLow + validationLow;
+  const rawHigh = automationHigh + manualHigh + validationHigh;
+  const hoursLow = Math.max(assumptions.minimumHours, round1(rawLow));
+  const hoursHigh = Math.max(assumptions.minimumHours, round1(rawHigh));
+  const breakdown = [
+    {
+      label: "Automatable calls",
+      calls: automatableCalls,
+      hoursLow: round1(automationLow),
+      hoursHigh: round1(automationHigh),
+      basis: `${assumptions.automationHoursPerCall}h per automatable call`
+    },
+    {
+      label: "Manual review calls",
+      calls: manualReviewCalls,
+      hoursLow: round1(manualLow),
+      hoursHigh: round1(manualHigh),
+      basis: `${assumptions.manualReviewHoursPerCall}h per manual-review call`
+    },
+    {
+      label: "Validation & testing",
+      calls: 0,
+      hoursLow: round1(validationLow),
+      hoursHigh: round1(validationHigh),
+      basis: `${assumptions.validationMultiplier * 100}% of migration work`
+    }
+  ];
+  const result = {
+    hoursLow,
+    hoursHigh,
+    breakdown,
+    assumptions,
+    disclaimer: ESTIMATE_DISCLAIMER
+  };
+  if (hourlyRate !== void 0) {
+    result.hourlyRate = hourlyRate;
+    result.costLow = Math.round(hoursLow * hourlyRate);
+    result.costHigh = Math.round(hoursHigh * hourlyRate);
+  }
+  return result;
+}
+
 // src/commands/audit.ts
 var VALID_AUDIT_FORMATS = ["json", "markdown", "html"];
 function registerAuditCommand(program2) {
-  program2.command("audit").description("Generate a flag debt audit report").argument("[dir]", "directory to audit", process.cwd()).option("-f, --format <format>", "output format: json | markdown | html", "markdown").option("-o, --output <file>", "write report to file").option("-c, --config <path>", "path to .flaglintrc config file").option("--exclude-tests", "exclude test files (*.test.*, *.spec.*, __tests__/, tests/)").addHelpText(
+  program2.command("audit").description("Generate a flag debt audit report").argument("[dir]", "directory to audit", process.cwd()).option("-f, --format <format>", "output format: json | markdown | html", "markdown").option("-o, --output <file>", "write report to file").option("-c, --config <path>", "path to .flaglintrc config file").option("--exclude-tests", "exclude test files (*.test.*, *.spec.*, __tests__/, tests/)").option("--cost-estimate", "include a migration effort estimate in the report. The default assumptions are configurable planning heuristics, not observed industry benchmarks.").option("--hourly-rate <rate>", "hourly rate for cost projection (requires --cost-estimate)").addHelpText(
     "after",
     `
 Examples:
   $ flaglint audit                    generate flag debt audit report
   $ flaglint audit --format html     shareable HTML report
-  $ flaglint audit --output audit.md save to file`
+  $ flaglint audit --output audit.md save to file
+  $ flaglint audit --cost-estimate   include migration effort estimate
+  $ flaglint audit --cost-estimate --hourly-rate 125   include cost projection`
   ).action(
     async (dir, options) => {
       if (!VALID_AUDIT_FORMATS.includes(options.format)) {
@@ -2317,6 +2613,26 @@ Examples:
         );
         process.exit(2);
       }
+      let hourlyRate;
+      if (options.hourlyRate !== void 0) {
+        if (!options.costEstimate) {
+          process.stderr.write(
+            chalk4.yellow("warn: --hourly-rate has no effect without --cost-estimate\n")
+          );
+        } else {
+          const parsed = Number(options.hourlyRate);
+          if (!Number.isFinite(parsed) || parsed <= 0) {
+            process.stderr.write(
+              chalk4.red(
+                `Error: --hourly-rate must be a positive number, got: ${options.hourlyRate}
+`
+              )
+            );
+            process.exit(2);
+          }
+          hourlyRate = parsed;
+        }
+      }
       try {
         const s = await stat4(resolve8(dir));
         if (!s.isDirectory()) {
@@ -2394,19 +2710,27 @@ Examples:
 `
           )
         );
+        if (format === "json" && options.costEstimate) {
+          const emptyReport = buildAuditReport(scanResult, []);
+          process.stdout.write(formatAuditJson(emptyReport, { estimate: null }) + "\n");
+          process.stderr.write(chalk4.dim("Migration estimate: N/A\n"));
+        } else if (options.costEstimate) {
+          process.stderr.write(chalk4.dim("Migration estimate: N/A\n"));
+        }
         process.exit(0);
       }
       const auditReport = buildAuditReport(
         scanResult,
         scanResult.migrationInventory ?? []
       );
+      const renderOptions = options.costEstimate ? { estimate: computeEstimate(auditReport.readiness, void 0, hourlyRate) } : void 0;
       let output;
       if (format === "json") {
-        output = formatAuditJson(auditReport);
+        output = formatAuditJson(auditReport, renderOptions);
       } else if (format === "html") {
-        output = formatAuditHtml(auditReport);
+        output = formatAuditHtml(auditReport, renderOptions);
       } else {
-        output = formatAuditMarkdown(auditReport);
+        output = formatAuditMarkdown(auditReport, renderOptions);
       }
       if (options.output) {
         const outPath = resolve8(options.output);
@@ -2427,12 +2751,47 @@ Examples:
         process.stdout.write(output + "\n");
       }
       const { totalFlags, highRisk, mediumRisk, lowRisk } = auditReport.summary;
+      const lowRiskSegment = lowRisk > 0 ? `, ${lowRisk} low risk` : "";
       process.stderr.write(
         chalk4.green(
-          `\u2713 Audit complete: ${totalFlags} flags \u2014 ${highRisk} high risk, ${mediumRisk} medium risk, ${lowRisk} low risk
+          `\u2713 Audit complete: ${totalFlags} flags \u2014 ${highRisk} high risk, ${mediumRisk} medium risk${lowRiskSegment}
 `
         )
       );
+      const { readiness } = auditReport;
+      process.stderr.write("\n");
+      if (readiness.grade === "not-applicable") {
+        process.stderr.write(chalk4.dim("Migration readiness: N/A \u2014 no direct LaunchDarkly calls detected.\n"));
+        if (options.costEstimate) {
+          process.stderr.write(chalk4.dim("Migration estimate: N/A\n"));
+        }
+      } else {
+        const score = readiness.score;
+        const scoreColor = score >= 80 ? chalk4.green : score >= 50 ? chalk4.yellow : chalk4.red;
+        process.stderr.write(scoreColor(`Migration readiness: ${score}/100  \xB7  ${readiness.grade}
+`));
+        process.stderr.write(scoreColor(renderReadinessBar(score) + "\n"));
+        process.stderr.write(
+          chalk4.dim(
+            `${readiness.automatableCalls} safely automatable  \xB7  ${readiness.manualReviewCalls} require manual review
+`
+          )
+        );
+        if (options.costEstimate && renderOptions?.estimate) {
+          const est = renderOptions.estimate;
+          process.stderr.write("\n");
+          process.stderr.write(
+            chalk4.cyan(`Estimated migration effort: ${est.hoursLow}h \u2013 ${est.hoursHigh}h
+`)
+          );
+          if (est.costLow !== void 0 && est.costHigh !== void 0) {
+            const fmtCost = (n) => "$" + n.toLocaleString("en-US");
+            process.stderr.write(chalk4.cyan(`Estimated cost: ${fmtCost(est.costLow)} \u2013 ${fmtCost(est.costHigh)}
+`));
+          }
+          process.stderr.write(chalk4.dim("Estimates are directional. See the report for assumptions.\n"));
+        }
+      }
       process.exit(0);
     }
   );
@@ -2441,7 +2800,7 @@ Examples:
 // src/cli.ts
 function createCLI() {
   const program2 = new Command();
-  program2.name("flaglint").description("Scan LaunchDarkly Node.js SDK usage, generate safe OpenFeature migration diffs, and enforce the vendor boundary in CI.").version("0.6.0", "-v, --version", "output the current version").addHelpText(
+  program2.name("flaglint").description("Scan LaunchDarkly Node.js SDK usage, generate safe OpenFeature migration diffs, and enforce the vendor boundary in CI.").version("0.7.0", "-v, --version", "output the current version").addHelpText(
     "after",
     `
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flaglint",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Scan LaunchDarkly Node.js SDK usage, generate safe OpenFeature migration diffs, and enforce the vendor boundary in CI.",
   "type": "module",
   "bin": {
@@ -48,6 +48,9 @@
     "test:run": "vitest run",
     "pretest:coverage": "npm run build:cli",
     "test:coverage": "vitest run --coverage",
+    "preview:docs": "ASTRO_TELEMETRY_DISABLED=1 astro preview --port 4321",
+    "test:package": "tsx scripts/test-package.ts",
+    "test:smoke": "playwright test",
     "new-branch": "tsx scripts/new-branch.ts",
     "release:patch": "tsx scripts/release.ts patch",
     "release:minor": "tsx scripts/release.ts minor",
@@ -66,16 +69,17 @@
   },
   "devDependencies": {
     "@astrojs/starlight": "^0.39.2",
+    "@playwright/test": "^1.60.0",
     "@types/micromatch": "^4.0.10",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.6",
     "astro": "^6.3.8",
     "clipboardy": "^4.0.0",
     "png-to-ico": "^3.0.1",
+    "starlight-blog": "^0.26.1",
     "tsup": "^8.2.4",
     "tsx": "^4.19.0",
     "typescript": "^5.5.4",
-    "vitest": "^4.1.6",
-    "starlight-blog": "^0.26.1"
+    "vitest": "^4.1.6"
   }
 }