flaglint 0.5.4 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,88 @@ 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
+
+- add flaglint audit command with risk-scored flag debt report
+- migrate homepage into Astro, unify site into single build
+- add dark/light/auto theme toggle + search to homepage
+- add Mermaid diagrams to Safety Model and How FlagLint Works
+- add Mermaid diagrams to Safety Model and How FlagLint Works
+- complete favicon stack for Google Search and mobile
+- replace plain-text architecture diagram with styled HTML flow
+- add JSON-LD SoftwareApplication structured data to homepage
+- align trust and privacy page nav with homepage nav
+- add Further Reading section to quickstart linking to blog posts
+- add cross-links between blog posts
+- rename blog to FlagLint Blog and set focused description
+- add Docs and Blog links to homepage nav and footer
+- add Blog link to marketing homepage nav
+- add blog to flaglint.dev using starlight-blog
+- add terminal demo GIF (scan, migrate --dry-run, validate CI gate)
+
+### Fixed
+
+- docs UX series P1-P9 (GIF, TOC, title, sidebar, cards, blog frames)
+- UX and codebase series (A1–A5, B1–B5)
+- sync package-lock.json after rebase (add png-to-ico)
+- UX and codebase series (A1–A5, B1–B5)
+- align dynamic key label with scan reporter terminology
+- restore branded README header and correct docs links
+
+### Changed
+
+- trigger cloudflare rebuild
+- untrack www/ build output + fix GIF paths + add Why FlagLint CTA
+- add excerpt markers to both blog posts for blog index truncation
+- rebuild after rebase onto main (PR #83 docs UX changes)
+- rebuild docs after rebase onto main (A1-A5/B1-B5 + favicon state)
+- rebuild docs after rebase onto main (favicon + blog state)
+- rebuild docs site with blog and demo GIF
+- add LinkedIn URL to blog post authors
+- remove debug artifacts from demo fixture folder
+- update version references to 0.5.4
+
+### Other
+
+- Merge feat/audit-command: add flaglint audit command
+- Merge pull request #86 from flaglint/feat/docs-ux-fixes
+- Merge pull request #85 from flaglint/fix/blog-excerpt-markers
+- Merge pull request #84 from flaglint/feat/homepage-theme-search
+- Merge pull request #83 from flaglint/fix/complete-series-p1-p12
+- Merge pull request #82 from flaglint/feat/favicon-stack
+- Merge pull request #80 from flaglint/fix/validate-dynamic-key-label
+- Merge pull request #78 from flaglint/feat/architecture-diagram
+- Merge pull request #77 from flaglint/feat/structured-data-jsonld
+- Merge pull request #76 from flaglint/feat/consistent-nav
+- Merge pull request #75 from flaglint/feat/quickstart-further-reading
+- Merge branch 'main' into feat/quickstart-further-reading
+- Merge pull request #74 from flaglint/feat/blog-cross-links
+- Merge pull request #73 from flaglint/feat/blog-title-description
+- Merge pull request #72 from flaglint/feat/nav-footer-blog-docs
+- Merge pull request #71 from flaglint/chore/bump-version-0.5.4
+- Update README.md
+- Merge pull request #70 from flaglint/chore/bump-version-0.5.4
+- Merge pull request #69 from flaglint/chore/bump-version-0.5.4
+- chore/bump-version-0.5.4
+
 ## Unreleased
 
 ### Fixed

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,82 +21,103 @@
   </a>
 </p>
 
-# FlagLint
+---
 
-**Standardize LaunchDarkly usage on OpenFeature.**
+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.
 
-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.
+```bash
+npx flaglint audit ./src
+```
 
-**[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)**
+```
+✓ Audit complete: 13 flags — 3 high risk, 10 medium risk
 
----
+Migration readiness: 50/100  ·  moderate
+[█████████████░░░░░░░░░░░░] 50%
+10 safely automatable  ·  10 require manual review
+```
 
-## Quick start
+Add `--cost-estimate` to include a directional planning estimate:
 
 ```bash
-npx flaglint scan ./src
+npx flaglint audit ./src --cost-estimate
 ```
 
 ```
-✔ 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
+
+Estimated migration effort: 22.8h – 43.9h
+Estimates are directional. See the report for assumptions.
 ```
 
-Preview the migration before changing anything:
+For the full report see `--format html`. [Documentation](https://flaglint.dev/docs) · [Quickstart](https://flaglint.dev/docs/quickstart) · [npm](https://npmjs.com/package/flaglint)
 
-```bash
-npx flaglint migrate ./src --dry-run
-```
+No API key. No source upload. LaunchDarkly stays your provider — OpenFeature becomes the evaluation API your application calls.
+
+---
+
+## The problem FlagLint solves
+
+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.
+
+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.
 
 ---
 
 ## Workflow
 
-| 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 |
+| 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)
 
@@ -104,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

@@ -303,6 +303,9 @@ function detectUsages(ast, code, filePath, wrappers) {
             callType: "isFeatureEnabled",
             stalenessSignals: sig ? [sig] : []
           });
+          migrationInventory.push(
+            buildMigrationInventoryItem(code, filePath, loc, call, "isFeatureEnabled", call.arguments, flagKey, isDynamic)
+          );
           return;
         }
         if (LD_HOOKS.has(name)) {
@@ -316,6 +319,25 @@ function detectUsages(ast, code, filePath, wrappers) {
             callType: name === "useFlags" ? "hook-useFlags" : "hook-useLDClient",
             stalenessSignals: sig ? [sig] : []
           });
+          const hookCallRange = expressionRange(call);
+          migrationInventory.push({
+            file: filePath,
+            line: loc.line,
+            column: loc.column,
+            launchDarklyMethod: name === "useFlags" ? "hook-useFlags" : "hook-useLDClient",
+            callExpression: expressionText(code, call),
+            rangeStart: hookCallRange?.[0],
+            rangeEnd: hookCallRange?.[1],
+            isAwaited: false,
+            flagKeyExpression: void 0,
+            staticFlagKey: void 0,
+            isDynamic: false,
+            valueType: "unknown",
+            fallbackExpression: void 0,
+            evaluationContextExpression: void 0,
+            safelyAutomatable: false,
+            manualReviewReason: "dynamic-key"
+          });
           return;
         }
       }
@@ -331,6 +353,9 @@ function detectUsages(ast, code, filePath, wrappers) {
           callType: "variation",
           stalenessSignals: sig ? [sig] : []
         });
+        migrationInventory.push(
+          buildMigrationInventoryItem(code, filePath, loc, call, "variation", call.arguments, flagKey, isDynamic)
+        );
         return;
       }
       if (callee.type === "CallExpression" && callee.callee.type === "Identifier" && callee.callee.name === "withLDConsumer") {
@@ -542,8 +567,9 @@ function formatMarkdown(result, options) {
   lines.push("|----------|--------|-------|------------|--------|");
   for (const [key, data] of sorted) {
     const status = data.isStale ? "\u26A0 Stale" : "\u2713 Active";
+    const displayKey = key === "*" || data.usages.some((u) => u.isDynamic && u.flagKey === key) ? "(dynamic key)" : key;
     lines.push(
-      `| ${key} | ${data.usages.length} | ${data.files.size} | ${[...data.callTypes].join(", ")} | ${status} |`
+      `| ${displayKey} | ${data.usages.length} | ${data.files.size} | ${[...data.callTypes].join(", ")} | ${status} |`
     );
   }
   lines.push("");
@@ -763,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.5.4" : "0.1.0";
+  const version = true ? "0.7.0" : "0.1.0";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -894,6 +920,9 @@ var FlagLintConfigSchema = z.object({
     "**/coverage/**",
     "**/*.d.ts"
   ]),
+  // Governs which vendor SDK the scanner targets.
+  // Currently only "launchdarkly" is wired in the scanner.
+  // Other values are accepted for forward compatibility (v0.7+).
   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(0),
@@ -1087,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";
@@ -1165,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"] : [];
 }
@@ -1188,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,
@@ -1216,7 +1322,7 @@ function formatMigrationReport(analysis) {
     unsupportedUnknownCount
   } = analysis;
   const date = (/* @__PURE__ */ new Date()).toLocaleDateString();
-  const version = true ? "0.5.4" : "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}`);
@@ -1713,7 +1819,7 @@ function validateScanResult(result, options = {}) {
   };
 }
 function violationLabel(v) {
-  if (v.isDynamic) return `${v.callType}(dynamic key \u2014 manual review required)`;
+  if (v.isDynamic) return `${v.callType}("(dynamic key)")`;
   if (v.flagKey === "*") return `${v.callType}(bulk inventory)`;
   return `${v.callType}("${v.flagKey}")`;
 }
@@ -1977,10 +2083,724 @@ Examples:
   );
 }
 
+// src/commands/audit.ts
+import { writeFile as writeFile5 } from "fs/promises";
+import { stat as stat4 } from "fs/promises";
+import { resolve as resolve8 } from "path";
+import chalk4 from "chalk";
+import ora4 from "ora";
+
+// src/auditor/index.ts
+function scoreFlag(usages, inventoryItems) {
+  const highReasons = [];
+  const mediumReasons = [];
+  if (usages.some((u) => u.isDynamic)) {
+    highReasons.push("dynamic key");
+  }
+  if (inventoryItems.some((i) => i.manualReviewReason === "detail-method")) {
+    highReasons.push("detail evaluation");
+  }
+  if (inventoryItems.some((i) => i.manualReviewReason === "bulk-inventory-call")) {
+    highReasons.push("bulk call");
+  }
+  if (usages.some((u) => u.stalenessSignals.length > 0)) {
+    highReasons.push("stale signal");
+  }
+  if (usages.some((u) => u.callType === "variation" && u.isDynamic)) {
+    if (!highReasons.includes("wrapper usage")) {
+      highReasons.push("wrapper usage");
+    }
+  }
+  if (usages.some(
+    (u) => u.callType === "hook-useFlags" || u.callType === "hook-useLDClient" || u.callType === "hoc" || u.callType === "provider"
+  )) {
+    highReasons.push("react/browser hook");
+  }
+  if (highReasons.length > 0) {
+    return { riskLevel: "high", riskReasons: highReasons };
+  }
+  if (inventoryItems.some((i) => i.safelyAutomatable)) {
+    mediumReasons.push("safely automatable");
+  }
+  if (inventoryItems.some((i) => i.valueType === "object")) {
+    mediumReasons.push("json variation");
+  }
+  if (inventoryItems.some((i) => i.manualReviewReason === "unknown-fallback")) {
+    mediumReasons.push("unknown fallback");
+  }
+  if (mediumReasons.length > 0) {
+    return { riskLevel: "medium", riskReasons: mediumReasons };
+  }
+  return { riskLevel: "low", riskReasons: [] };
+}
+function buildAuditReport(scanResult, inventoryItems) {
+  const usagesByFlag = /* @__PURE__ */ new Map();
+  for (const u of scanResult.usages) {
+    const key = u.flagKey;
+    if (!usagesByFlag.has(key)) usagesByFlag.set(key, []);
+    usagesByFlag.get(key).push(u);
+  }
+  const inventoryByFlag = /* @__PURE__ */ new Map();
+  for (const item of inventoryItems) {
+    const key = item.staticFlagKey ?? "*";
+    if (!inventoryByFlag.has(key)) inventoryByFlag.set(key, []);
+    inventoryByFlag.get(key).push(item);
+  }
+  const allFlagKeys = /* @__PURE__ */ new Set([...usagesByFlag.keys()]);
+  const flags = [];
+  for (const flagKey of allFlagKeys) {
+    const usages = usagesByFlag.get(flagKey) ?? [];
+    const items = inventoryByFlag.get(flagKey) ?? [];
+    const { riskLevel, riskReasons } = scoreFlag(usages, items);
+    const files = [...new Set(usages.map((u) => u.file))];
+    const callTypes = [...new Set(usages.map((u) => u.callType))];
+    flags.push({
+      flagKey,
+      riskLevel,
+      riskReasons,
+      callTypes,
+      fileCount: files.length,
+      usageCount: usages.length,
+      safelyAutomatable: items.some((i) => i.safelyAutomatable),
+      hasStaleSignal: usages.some((u) => u.stalenessSignals.length > 0),
+      isDynamic: usages.some((u) => u.isDynamic),
+      files
+    });
+  }
+  const riskOrder = { high: 0, medium: 1, low: 2 };
+  flags.sort((a, b) => {
+    const levelDiff = riskOrder[a.riskLevel] - riskOrder[b.riskLevel];
+    if (levelDiff !== 0) return levelDiff;
+    return b.usageCount - a.usageCount;
+  });
+  const highRisk = flags.filter((f) => f.riskLevel === "high").length;
+  const mediumRisk = flags.filter((f) => f.riskLevel === "medium").length;
+  const lowRisk = flags.filter((f) => f.riskLevel === "low").length;
+  const summary = {
+    totalFlags: flags.length,
+    highRisk,
+    mediumRisk,
+    lowRisk,
+    totalUsages: scanResult.totalUsages,
+    dynamicKeys: scanResult.usages.filter((u) => u.isDynamic).length,
+    detailEvaluations: inventoryItems.filter((i) => i.manualReviewReason === "detail-method").length,
+    bulkCalls: inventoryItems.filter((i) => i.manualReviewReason === "bulk-inventory-call").length,
+    wrapperUsages: scanResult.usages.filter((u) => u.callType === "variation").length,
+    staleSignals: scanResult.usages.filter((u) => u.stalenessSignals.length > 0).length,
+    safelyAutomatable: inventoryItems.filter((i) => i.safelyAutomatable).length,
+    manualReview: inventoryItems.filter((i) => !i.safelyAutomatable).length,
+    scannedFiles: scanResult.scannedFiles,
+    scanDurationMs: scanResult.scanDurationMs,
+    scannedAt: scanResult.scannedAt,
+    scanRoot: scanResult.scanRoot
+  };
+  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 displayFlagKey(flag) {
+  return flag.isDynamic ? "<dynamic key>" : flag.flagKey;
+}
+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("");
+  lines.push(`**Scanned at:** ${summary.scannedAt}  `);
+  lines.push(`**Scan root:** ${summary.scanRoot}  `);
+  lines.push(`**Files scanned:** ${summary.scannedFiles}  `);
+  lines.push(`**Duration:** ${summary.scanDurationMs}ms`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  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 |"
+  );
+  lines.push(
+    "|--------------|--------------|------------|---------------|-------------------|---------------|"
+  );
+  lines.push(
+    `| ${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 |");
+  lines.push("|----------|------|--------|-------|------------|---------|");
+  const riskLabel = {
+    high: "\u{1F534} High",
+    medium: "\u{1F7E1} Medium",
+    low: "\u{1F7E2} Low"
+  };
+  for (const flag of flags) {
+    const reasons = flag.riskReasons.join(", ") || "\u2014";
+    const flagKey = displayFlagKey(flag);
+    lines.push(
+      `| \`${flagKey}\` | ${riskLabel[flag.riskLevel]} | ${flag.usageCount} | ${flag.fileCount} | ${flag.callTypes.join(", ")} | ${reasons} |`
+    );
+  }
+  lines.push("");
+  lines.push("## Next Steps");
+  lines.push("");
+  lines.push(
+    "- Run `flaglint migrate --dry-run` to preview safe OpenFeature rewrites"
+  );
+  lines.push(
+    "- Run `flaglint validate --no-direct-launchdarkly` to enforce OF boundary in CI"
+  );
+  lines.push(
+    "- Review HIGH risk flags manually before any automated migration"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+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")
+      return '<span class="badge badge-high">High</span>';
+    if (level === "medium")
+      return '<span class="badge badge-medium">Medium</span>';
+    return '<span class="badge badge-low">Low</span>';
+  };
+  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(flagKey)}</code></td>
+          <td>${riskBadge(f.riskLevel)}</td>
+          <td>${f.usageCount}</td>
+          <td>${f.fileCount}</td>
+          <td>${f.callTypes.map(esc2).join(", ")}</td>
+          <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>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>FlagLint Audit Report</title>
+  <style>
+    :root{--bg:#fff;--surface:#f8f9fa;--border:#dee2e6;--text:#212529;--muted:#6c757d;--card-shadow:0 1px 3px rgba(0,0,0,.1)}
+    @media(prefers-color-scheme:dark){:root{--bg:#0f172a;--surface:#1e293b;--border:#334155;--text:#e2e8f0;--muted:#94a3b8;--card-shadow:0 1px 3px rgba(0,0,0,.4)}}
+    *{box-sizing:border-box;margin:0;padding:0}
+    body{background:var(--bg);color:var(--text);font-family:system-ui,-apple-system,sans-serif;padding:2rem;max-width:1200px;margin:0 auto;line-height:1.5}
+    h1{font-size:1.75rem;margin-bottom:.25rem}
+    h2{font-size:1.125rem;margin:2rem 0 .75rem;padding-bottom:.5rem;border-bottom:1px solid var(--border)}
+    .subtitle{color:var(--muted);margin-bottom:1.5rem;font-size:.875rem}
+    .cards{display:flex;gap:1rem;flex-wrap:wrap;margin-bottom:2rem}
+    .card{flex:1;min-width:140px;background:var(--surface);border:1px solid var(--border);border-radius:8px;padding:1rem;box-shadow:var(--card-shadow)}
+    .card-num{font-size:1.875rem;font-weight:700;line-height:1}
+    .card-num.red{color:#dc2626}
+    .card-num.amber{color:#d97706}
+    .card-num.green{color:#16a34a}
+    .card-num.blue{color:#3b82f6}
+    .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}
+    code{font-family:ui-monospace,monospace;font-size:.8em;background:var(--surface);padding:.1em .3em;border-radius:3px}
+    .badge{display:inline-block;padding:.2em .6em;border-radius:4px;font-size:.75rem;font-weight:600}
+    .badge-high{background:#fee2e2;color:#991b1b}
+    .badge-medium{background:#fef3c7;color:#92400e}
+    .badge-low{background:#dcfce7;color:#166534}
+    @media(prefers-color-scheme:dark){
+      .badge-high{background:#7f1d1d;color:#fca5a5}
+      .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)}
+  </style>
+</head>
+<body>
+  <h1>FlagLint Audit Report</h1>
+  <p class="subtitle">
+    ${esc2(summary.scanRoot)} &middot; ${esc2(summary.scannedFiles.toString())} files &middot; ${esc2(summary.scanDurationMs.toString())}ms &middot; ${esc2(date)}
+  </p>
+
+  <h2>Summary</h2>
+  <div class="cards">
+    <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>
+    ${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>
+      <tr>
+        <th>Flag Key</th>
+        <th>Risk</th>
+        <th>Usages</th>
+        <th>Files</th>
+        <th>Call Types</th>
+        <th>Risk Reasons</th>
+      </tr>
+    </thead>
+    <tbody>
+        ${rows}
+    </tbody>
+  </table>
+
+  <h2>Next Steps</h2>
+  <ol class="steps">
+    <li>Run <code>flaglint migrate --dry-run</code> to preview safe OpenFeature rewrites</li>
+    <li>Run <code>flaglint validate --no-direct-launchdarkly</code> to enforce OF boundary in CI</li>
+    <li>Review HIGH risk flags manually before any automated migration</li>
+  </ol>
+
+  <footer>
+    Generated by <a href="https://flaglint.dev">FlagLint</a> ${esc2(version)}
+  </footer>
+</body>
+</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/)").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 --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)) {
+        process.stderr.write(
+          chalk4.red(
+            `Error: Invalid format '${options.format}'. Must be one of: ${VALID_AUDIT_FORMATS.join(", ")}
+`
+          )
+        );
+        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()) {
+          process.stderr.write(chalk4.red(`Error: Not a directory: ${dir}
+`));
+          process.exit(1);
+        }
+      } catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+          process.stderr.write(chalk4.red(`Error: Directory not found: ${dir}
+`));
+        } else if (code === "EACCES") {
+          process.stderr.write(chalk4.red(`Error: Permission denied: ${dir}
+`));
+        } else {
+          process.stderr.write(chalk4.red(`Error: Cannot access directory: ${dir}
+`));
+        }
+        process.exit(1);
+      }
+      let config;
+      try {
+        config = await loadConfig(options.config);
+      } catch (err) {
+        process.stderr.write(
+          chalk4.red(String(err instanceof Error ? err.message : err)) + "\n"
+        );
+        process.exit(1);
+      }
+      const TEST_PATTERNS = [
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*.spec.ts",
+        "**/*.spec.tsx",
+        "**/__tests__/**",
+        "**/tests/**"
+      ];
+      const scanConfig = options.excludeTests ? { ...config, exclude: [...config.exclude, ...TEST_PATTERNS] } : config;
+      const format = options.format;
+      const spinner = ora4(`Auditing ${dir}...`).start();
+      process.once("SIGINT", () => {
+        spinner.stop();
+        process.exit(130);
+      });
+      let lastSpinnerUpdate = 0;
+      let scanResult;
+      try {
+        scanResult = await scan(new LocalFileSource(dir), scanConfig, (filesScanned) => {
+          if (filesScanned - lastSpinnerUpdate >= 50) {
+            spinner.text = `Scanning... (${filesScanned} files)`;
+            lastSpinnerUpdate = filesScanned;
+          }
+        });
+        spinner.stop();
+      } catch (err) {
+        spinner.fail("Audit scan failed");
+        process.stderr.write(chalk4.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(chalk4.yellow(msg + "\n"));
+      }
+      if (scanResult.scannedFiles === 0) {
+        process.stderr.write(
+          chalk4.yellow("No matching files found. Check your .flaglintrc include patterns.\n")
+        );
+        process.exit(0);
+      }
+      if (scanResult.totalUsages === 0) {
+        process.stderr.write(
+          chalk4.dim(
+            `No LaunchDarkly SDK usage detected in ${scanResult.scannedFiles} files.
+`
+          )
+        );
+        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, renderOptions);
+      } else if (format === "html") {
+        output = formatAuditHtml(auditReport, renderOptions);
+      } else {
+        output = formatAuditMarkdown(auditReport, renderOptions);
+      }
+      if (options.output) {
+        const outPath = resolve8(options.output);
+        try {
+          await writeFile5(outPath, output, "utf8");
+          process.stderr.write(chalk4.dim(`   Report written to ${options.output}
+`));
+        } catch (err) {
+          process.stderr.write(
+            chalk4.red(
+              `Error: Failed to write report to ${options.output}: ${err instanceof Error ? err.message : String(err)}
+`
+            )
+          );
+          process.exit(1);
+        }
+      } else {
+        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${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);
+    }
+  );
+}
+
 // src/cli.ts
 function createCLI() {
   const program2 = new Command();
-  program2.name("flaglint").description("LaunchDarkly Node.js server SDK -> OpenFeature migration.").version("0.5.4", "-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:
@@ -1990,11 +2810,15 @@ Examples:
   $ flaglint scan --output report.md save to file
   $ flaglint migrate                 generate migration plan
   $ flaglint migrate --dry-run       preview without writing
-  $ flaglint validate --no-direct-launchdarkly  enforce OF migration in CI`
+  $ flaglint validate --no-direct-launchdarkly  enforce OF migration in CI
+  $ flaglint audit                   generate flag debt audit report
+  $ flaglint audit --format html     shareable HTML report
+  $ flaglint audit --output audit.md save to file`
   );
   registerScanCommand(program2);
   registerMigrateCommand(program2);
   registerValidateCommand(program2);
+  registerAuditCommand(program2);
   return program2;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flaglint",
-  "version": "0.5.4",
-  "description": "LaunchDarkly Node.js server SDK -> OpenFeature migration.",
+  "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": {
     "flaglint": "dist/bin/flaglint.js"
@@ -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,11 +69,14 @@
   },
   "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",