flaglint 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -5,7 +5,87 @@ 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).
 
-## [Unreleased]
+## Unreleased
+
+## [0.5.0] - 2026-05-26
+
+### Added
+
+- **Configured imported OpenFeature client bindings** (`openFeatureClientBindings` in `.flaglintrc`):
+  Declare shared OpenFeature client exports by import name and glob module pattern.
+  `migrate --apply` recognises these imports as proven bindings without requiring every
+  service file to call `OpenFeature.getClient()` locally.
+  ```json
+  {
+    "openFeatureClientBindings": [
+      { "importName": "openFeatureClient", "modulePatterns": ["**/platform/feature-flags"] }
+    ]
+  }
+  ```
+
+- **TypeScript ESM `.js` import compatibility**: `modulePatterns` globs now match TypeScript
+  source imports that carry a `.js` extension at the specifier level
+  (`import { openFeatureClient } from "../platform/feature-flags.js"`) even when the
+  configured pattern omits the extension (`**/platform/feature-flags`).
+
+- **`validate --format sarif`**: `flaglint validate --no-direct-launchdarkly --format sarif
+  --output flaglint.sarif` emits SARIF 2.1.0 with rule id `flaglint.direct-launchdarkly`
+  and level `error`. Designed for GitHub Code Scanning upload — each direct LaunchDarkly
+  evaluation call produces a PR annotation. Zero violations produces a valid SARIF document
+  that GitHub Code Scanning interprets as "all clear".
+
+- **Enterprise HTML audit report**: `flaglint scan --format html` now includes an Executive
+  Summary (total call-sites, unique flags, auto-migratable vs. manual-review breakdown),
+  Findings by Directory table, Recommended Next Steps workflow, and a Copy Markdown Summary
+  clipboard button.
+
+- **Enterprise OpenFeature migration demo** (`examples/enterprise-checkout-service/`): end-to-end
+  walkthrough across five Node.js services (checkout, pricing, analytics, product, flags-wrapper).
+  Includes `before/`/`after/` snapshots, `after-complete/` (fully migrated, passes hard gate),
+  generated reports, `.flaglintrc` config, and a sample GitHub Actions CI workflow.
+
+- **Docs site** (`www/docs/`): nine documentation pages covering getting started, all three
+  commands, supported scope, OpenFeature provider setup, CI/GitHub Actions integration,
+  OpenTelemetry observability guidance, safety model, and the enterprise demo.
+
+- **Enterprise trust documentation**: `SECURITY.md`, `CONTRIBUTING.md`, and `CODE_OF_CONDUCT.md`
+  with SARIF rule-ID reference for the `flaglint.direct-launchdarkly` policy rule.
+
+- **OpenFeature + OpenTelemetry observability guidance** (`www/docs/opentelemetry.html`):
+  documents how to instrument OpenFeature flag evaluations with OpenTelemetry using the
+  OpenFeature hooks API. FlagLint does not emit runtime telemetry; this page explains the
+  complementary integration pattern.
+
+### Fixed
+
+- **Deterministic test execution from clean checkout**: `vitest` configuration no longer
+  relies on `process.env.INIT_CWD` for test file discovery, ensuring the test suite
+  is reproducible on first-time `npm ci && npm test` runs.
+
+### Changed
+
+- Reposition README and homepage messaging around standardizing LaunchDarkly usage on
+  OpenFeature while keeping LaunchDarkly as the provider.
+- Document the focused automation scope: LaunchDarkly Node.js server-side evaluation calls
+  in TypeScript and JavaScript, with dynamic keys, detail evaluations, bulk calls, browser
+  SDKs, React usage, and ambiguous patterns reported for manual review.
+- Align supported runtime documentation and package metadata to Node.js `>=20`.
+  Resolves the Node.js engine metadata mismatch in `flaglint@0.4.1` (published as `>=22`).
+
+### Security
+
+- Add Node.js 20/22 CI coverage, CodeQL analysis, Dependabot configuration, and vulnerability
+  reporting instructions.
+- Update npm release workflow for Trusted Publishing/OIDC without long-lived npm publish tokens.
+
+### Scope boundaries (non-claims)
+
+The following are explicitly out of scope for this release:
+- LaunchDarkly replacement — LaunchDarkly remains the feature flag provider throughout.
+- Automatic provider/bootstrap setup — `migrate --apply` never generates bootstrap files.
+- Flag deletion or billing reduction — FlagLint does not evaluate live flag values.
+- Built-in runtime OpenTelemetry instrumentation — see `www/docs/opentelemetry.html` for
+  the complementary integration pattern using OpenFeature hooks.
 
 ## [0.4.1] - 2026-05-25
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>LaunchDarkly Node.js server SDK -> OpenFeature migration</strong>
+  <strong>Standardize LaunchDarkly usage on OpenFeature.</strong>
 </p>
 
 <p align="center">
@@ -21,21 +21,19 @@
   </a>
 </p>
 
-> [!WARNING]
-> FlagLint is currently an early preview.
->
-> Automatic migration currently supports LaunchDarkly Node.js server-side SDK evaluation calls only. Generated changes must be reviewed and tested before merging.
->
-> React hooks, higher-order components, browser/client-side SDK usage, bulk flag-state calls, detail evaluations, dynamic keys, and custom wrappers are not automatically migrated in this release.
-
 # FlagLint
 
-FlagLint inventories direct LaunchDarkly Node.js server SDK calls in your TypeScript/JavaScript
-codebase, generates reviewable OpenFeature migration diffs, applies only guarded transformations,
-and enforces migration state in CI.
+Standardize LaunchDarkly usage on OpenFeature.
+
+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.**
 
+Docs: [Getting Started](https://flaglint.dev/docs/getting-started) · [Commands](https://flaglint.dev/docs/commands/scan) · [Supported Scope](https://flaglint.dev/docs/supported-scope) · [CI Integration](https://flaglint.dev/docs/ci-github-actions) · [Enterprise Demo](https://flaglint.dev/docs/demo)
+
+[View enterprise demo source ->](./examples/enterprise-checkout-service)
+
 ---
 
 ## Workflow
@@ -98,6 +96,8 @@ npm install -g flaglint
 npx flaglint
 ```
 
+Requires Node.js 20 or newer. CI validates FlagLint on Node.js 20 and 22.
+
 ---
 
 ## Commands
@@ -149,8 +149,13 @@ flaglint migrate --exclude-tests           # skip test and spec files
 
 **`--apply` safety contracts:**
 - Refuses on a dirty git working tree unless `--allow-dirty`
-- Skips any file that does not already contain a proven `openFeatureClient` binding
-  (`openFeatureClient = OpenFeature.getClient()` from `@openfeature/server-sdk`)
+- Skips any file that does not contain a proven OpenFeature client binding:
+  either a local `OpenFeature.getClient()` binding or a configured imported
+  shared client allowlisted with `openFeatureClientBindings`
+- Imported client matching uses glob-safe `modulePatterns`; aliased imports
+  preserve the local identifier; TypeScript ESM `.js` runtime import specifiers
+  are recognized; ambiguous or unconfigured imports skip safely
+- Provider/bootstrap setup is never inserted automatically
 - Never touches detail methods, dynamic keys, unknown fallbacks, or bulk calls
 - Preserves `await` and original call arguments exactly
 - Idempotent: re-running with the same analysis has no effect
@@ -198,6 +203,17 @@ Run `flaglint migrate --dry-run` to review the migration plan.
 
 ---
 
+## Focused scope for safe automation
+
+Automatic migration currently supports LaunchDarkly Node.js server-side evaluation calls in
+TypeScript and JavaScript. That narrow scope is intentional: FlagLint only rewrites call sites
+where the value type, static flag key, fallback, evaluation context, and OpenFeature client
+binding are explicit enough to preserve.
+
+Dynamic keys, detail evaluations, bulk flag-state calls, browser SDKs, React usage, and ambiguous
+patterns are reported for manual review. They are inventoried so teams can plan the migration,
+but they are not automatically transformed.
+
 ## Supported API matrix
 
 **Scope: LaunchDarkly Node.js server-side SDK** (`launchdarkly-node-server-sdk`).
@@ -249,6 +265,62 @@ export const openFeatureClient = OpenFeature.getClient();
 
 ---
 
+## Using an existing shared OpenFeature client
+
+If your platform team already exports an OpenFeature client from a shared internal module
+(e.g. `platform/feature-flags.ts`), FlagLint can use that import as the proven binding for
+`--apply` — no local `OpenFeature.getClient()` call is required in every file.
+
+Declare the allowed import in `.flaglintrc`:
+
+```json
+{
+  "openFeatureClientBindings": [
+    {
+      "importName": "openFeatureClient",
+      "modulePatterns": ["**/platform/feature-flags"]
+    }
+  ]
+}
+```
+
+`modulePatterns` are **glob patterns** matched against the module import specifier
+(leading `./` and `../` traversal is stripped before matching). A pattern of
+`"**/platform/feature-flags"` matches `"../platform/feature-flags"` and
+`"../../shared/platform/feature-flags"`, but **not** `"../platform/feature-flags-legacy"` or
+`"../other/platform/feature-flags-backup"`.
+For TypeScript ESM projects, configured module patterns without `.js` also recognize
+the corresponding `.js` runtime import specifier.
+
+**Before:**
+```typescript
+// services/checkout.ts
+import { openFeatureClient } from "../platform/feature-flags";
+import LaunchDarkly from "launchdarkly-node-server-sdk";
+
+const enabled = ldClient.boolVariation("checkout-v2", { key: user.id }, false);
+```
+
+**After (`flaglint migrate --apply`):**
+```typescript
+// services/checkout.ts
+import { openFeatureClient } from "../platform/feature-flags";
+import LaunchDarkly from "launchdarkly-node-server-sdk";
+
+const enabled = openFeatureClient.getBooleanValue("checkout-v2", false, { key: user.id });
+```
+
+If the import is aliased (e.g. `import { openFeatureClient as flags } from "..."`), FlagLint
+previews and applies the transformation using the **local alias name** (`flags.getBooleanValue(...)`).
+
+When two configured bindings both match a file, FlagLint considers the result ambiguous and
+**skips that file** rather than guessing. Skipped files are reported in `--dry-run` output.
+
+Provider initialization remains the platform team's responsibility. FlagLint never inserts or
+modifies bootstrap/provider setup code.
+
+---
+
 ## Example transformation
 
 **Before — direct LaunchDarkly Node.js server SDK:**
@@ -260,13 +332,16 @@ const timeout = await ldClient.numberVariation("timeout-ms",  { key: user.id },
 
 **After — OpenFeature via LaunchDarkly provider:**
 ```typescript
-const enabled = await openFeatureClient.getBooleanValue("checkout-v2", false, { targetingKey: user.id });
-const theme   = await openFeatureClient.getStringValue("color-theme", "light", { targetingKey: user.id });
-const timeout = await openFeatureClient.getNumberValue("timeout-ms",  5000,    { targetingKey: user.id });
+const enabled = await openFeatureClient.getBooleanValue("checkout-v2", false, { key: user.id });
+const theme   = await openFeatureClient.getStringValue("color-theme", "light", { key: user.id });
+const timeout = await openFeatureClient.getNumberValue("timeout-ms",  5000,    { key: user.id });
 ```
 
 Flag key, fallback value, `await`, and evaluation context are preserved exactly.
 LaunchDarkly continues to serve the flags — only the call-site API changes.
+When authoring new OpenFeature-native bootstrap or application code, you may use
+OpenFeature `targetingKey`; FlagLint does not silently rewrite existing
+LaunchDarkly `key` contexts.
 
 ---
 
@@ -291,6 +366,7 @@ Create `.flaglintrc`, `.flaglintrc.json`, or `flaglint.config.json` in your proj
 | `provider` | `string` | `"launchdarkly"` | Feature flag provider |
 | `minFileCount` | `number` | `0` | Opt-in staleness heuristic. When set above 0, a flag is a staleness candidate if it appears in ≤ N files |
 | `wrappers` | `string[]` | `[]` | Function names wrapping LD SDK calls. Example: `["flagPredicate", "useFlag"]` |
+| `openFeatureClientBindings` | `{ importName: string; modulePatterns: string[] }[]` | `[]` | Allowlist shared imported OpenFeature client bindings for `--apply` eligibility. See [Using an existing shared OpenFeature client](#using-an-existing-shared-openfeature-client). |
 | `reportTitle` | `string` | — | Custom title for generated reports |
 | `outputDir` | `string` | `"."` | Default output directory |
 
@@ -328,22 +404,34 @@ jobs:
         with:
           node-version: 20
 
-      - name: Scan for LaunchDarkly SDK usage
-        run: npx flaglint scan --format sarif --output flaglint.sarif
+      - name: Inventory LaunchDarkly SDK usage
+        run: npx flaglint scan ./src --format html --output flaglint-inventory.html
+        continue-on-error: true
+
+      - name: Plan OpenFeature migration
+        run: npx flaglint migrate ./src --dry-run --output flaglint-migration.md
+        continue-on-error: true
+
+      - name: Validate direct LaunchDarkly policy
+        run: |
+          npx flaglint validate ./src \
+            --no-direct-launchdarkly \
+            --bootstrap-exclude "src/provider/setup.ts" \
+            --format sarif \
+            --output flaglint-validation.sarif
         continue-on-error: true
 
       - name: Upload to GitHub Code Scanning
         uses: github/codeql-action/upload-sarif@v3
         with:
-          sarif_file: flaglint.sarif
-
-      - name: Enforce OpenFeature migration
-        run: |
-          npx flaglint validate --no-direct-launchdarkly \
-            --bootstrap-exclude "src/provider/setup.ts"
+          sarif_file: flaglint-validation.sarif
 ```
 
-Code Scanning alerts show the exact file and line of each direct LD call — reviewers see them in the PR without running anything locally.
+`scan` is for inventory and reporting. `migrate --dry-run` is for migration
+planning. `validate --no-direct-launchdarkly --format sarif` is for CI policy
+annotations and enforcement. Code Scanning alerts show the exact file and line of
+each direct LD call under the SARIF rule id `flaglint.direct-launchdarkly` —
+reviewers see them in the PR without running anything locally.
 
 ---
 
@@ -351,8 +439,48 @@ Code Scanning alerts show the exact file and line of each direct LD call — rev
 
 Validated against 120 deterministic benchmark cases within the supported LaunchDarkly Node.js server-side SDK scope. 100% precision and recall are limited to those 120 tested cases and to the Node.js server-side SDK call patterns explicitly listed in the Supported API matrix above.
 
-Detection is AST-based, not regex: client binding patterns, import aliases, CJS require forms,
-and custom wrappers are all resolved before matching.
+Detection is AST-based, not regex: client binding patterns, import aliases, and CJS require
+forms are resolved before matching.
+
+---
+
+## Enterprise demo
+
+See a realistic end-to-end migration walkthrough — multiple Node.js services,
+mixed automatable and manual-review patterns, SARIF output, and CI enforcement:
+
+**[View enterprise demo](./examples/enterprise-checkout-service/README.md)**
+
+The demo shows scan inventory, exact dry-run preview, guarded apply,
+migration-in-progress advisory findings, and a completed-state validation hard
+gate.
+
+---
+
+## Security and trust
+
+FlagLint runs entirely on your machine. No source code, flag keys, or file paths
+are transmitted to any external service. The tool makes no outbound network
+connections during a flag scan or migration. No LaunchDarkly SDK key or any
+credentials are required.
+
+`flaglint migrate --apply` refuses to write files on a dirty git working tree
+(unless `--allow-dirty` is passed), requires a proven OpenFeature client binding
+before touching a file, and verifies each source range against the original call
+expression before rewriting.
+
+The project release workflow is configured to publish through GitHub Actions
+using npm Trusted Publishing/OIDC. The publish job uses Node 24 because npm
+Trusted Publishing has stricter runtime requirements; FlagLint runtime support
+remains Node.js >=20. npm-side Trusted Publisher configuration must be completed
+before the first OIDC-based publication unless it has already been configured
+and verified.
+
+Core behavior is covered by automated tests executed in CI on supported Node
+versions.
+
+For vulnerability reports, see [SECURITY.md](./SECURITY.md).
+For a full trust and provenance statement, see [docs/trust.md](./docs/trust.md).
 
 ---
 

package/dist/apply-ZYLA2N7Y.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  ApplyError,
+  applyMigration,
+  getOpenFeatureClientBindingName,
+  hasOpenFeatureClientBinding
+} from "./chunk-MJLXM6GZ.js";
+export {
+  ApplyError,
+  applyMigration,
+  getOpenFeatureClientBindingName,
+  hasOpenFeatureClientBinding
+};

package/dist/bin/flaglint.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import {
+  ApplyError,
+  applyMigration
+} from "../chunk-MJLXM6GZ.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -672,6 +676,16 @@ function formatSARIF(result) {
     2
   );
 }
+function usagesByDirectory(usages) {
+  const map = /* @__PURE__ */ new Map();
+  for (const u of usages) {
+    const parts = u.file.replace(/\\/g, "/").split("/");
+    const dir = parts.length > 1 ? parts.slice(0, Math.min(2, parts.length - 1)).join("/") : ".";
+    if (!map.has(dir)) map.set(dir, []);
+    map.get(dir).push(u);
+  }
+  return new Map([...map.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
 function formatHTML(result, options) {
   const { scannedFiles, totalUsages, uniqueFlags, usages, scanDurationMs } = result;
   const staleCount = new Set(
@@ -679,6 +693,34 @@ function formatHTML(result, options) {
   ).size;
   const dynamicCount = usages.filter((u) => u.isDynamic).length;
   const date = new Date(result.scannedAt).toLocaleString();
+  const inv = result.migrationInventory ?? [];
+  const automatableCount = inv.filter((i) => i.safelyAutomatable).length;
+  const manualCount = inv.filter((i) => !i.safelyAutomatable).length;
+  const detailBulkCount = inv.filter(
+    (i) => i.manualReviewReason === "detail-method" || i.manualReviewReason === "bulk-inventory-call"
+  ).length;
+  const affectedFiles = new Set(usages.map((u) => u.file)).size;
+  const automatablePct = inv.length > 0 ? Math.round(automatableCount / inv.length * 100) : 0;
+  const manualPct = inv.length > 0 ? Math.round(manualCount / inv.length * 100) : 0;
+  const markdownSummary = [
+    "## FlagLint Audit Summary",
+    "",
+    `- **Total call-sites:** ${totalUsages}`,
+    `- **Unique flags:** ${uniqueFlags.length}`,
+    `- **Files affected:** ${affectedFiles}`,
+    ...inv.length > 0 ? [
+      `- **Safely automatable:** ${automatableCount} (${automatablePct}%)`,
+      `- **Manual review required:** ${manualCount} (${manualPct}%)`,
+      `- **Dynamic keys:** ${dynamicCount}`,
+      `- **Detail/bulk calls:** ${detailBulkCount}`
+    ] : [`- **Dynamic keys:** ${dynamicCount}`, `- **Stale candidates:** ${staleCount}`],
+    "",
+    "### Recommended next steps",
+    "1. Configure OpenFeature provider (one-time manual step)",
+    "2. Review migration plan: `flaglint migrate --dry-run`",
+    "3. Apply automatable transformations: `flaglint migrate --apply`",
+    "4. Add CI enforcement: `flaglint validate --no-direct-launchdarkly`"
+  ].join("\\n");
   const flagMap = buildFlagMap(usages);
   const sorted = sortedFlagEntries(flagMap);
   const rows = sorted.map(([key, data]) => {
@@ -687,8 +729,18 @@ function formatHTML(result, options) {
     const fileList = [...data.files].map((f) => esc(f)).join("<br>");
     return `<tr class="${cls}"><td><code>${esc(key)}</code></td><td>${data.usages.length}</td><td>${fileList}</td><td>${[...data.callTypes].map(esc).join(", ")}</td><td>${status}</td></tr>`;
   }).join("\n      ");
+  const byDir = usagesByDirectory(usages);
+  const dirRows = [...byDir.entries()].map(([dir, dirUsages]) => {
+    const flagKeys = new Set(dirUsages.map((u) => u.flagKey)).size;
+    const callTypes = new Set(dirUsages.map((u) => u.callType));
+    return `<tr><td><code>${esc(dir)}</code></td><td>${dirUsages.length}</td><td>${flagKeys}</td><td>${[...callTypes].map(esc).join(", ")}</td></tr>`;
+  }).join("\n      ");
+  const auditCards = inv.length > 0 ? `
+    <div class="card"><div class="card-num green">${automatableCount}</div><div class="card-label">Auto-Migratable (${automatablePct}%)</div></div>
+    <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.4.1" : "0.1.0";
+  const version = true ? "0.5.0" : "0.1.0";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -702,12 +754,15 @@ function formatHTML(result, options) {
     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)}
+    h3{font-size:.9375rem;margin:1.5rem 0 .5rem;color:var(--muted)}
     .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.yellow{color:#d97706}
     .card-num.blue{color:#3b82f6}
+    .card-num.green{color:#16a34a}
+    .card-num.orange{color:#ea580c}
     .card-label{color:var(--muted);font-size:.75rem;margin-top:.375rem;text-transform:uppercase;letter-spacing:.05em}
     .filter-wrap{margin-bottom:.75rem}
     #filter{width:100%;padding:.5rem .75rem;border:1px solid var(--border);border-radius:6px;background:var(--surface);color:var(--text);font-size:.875rem;outline:none}
@@ -718,19 +773,25 @@ function formatHTML(result, options) {
     tr.stale td{background:var(--stale-bg)}
     tr.dynamic td{background:var(--dyn-bg)}
     code{font-family:ui-monospace,monospace;font-size:.8em;background:var(--surface);padding:.1em .3em;border-radius:3px}
+    .steps{margin:.75rem 0 1rem 1.25rem;line-height:2}
+    .steps li{margin-bottom:.25rem}
+    .btn{display:inline-flex;align-items:center;gap:.4rem;background:#6366f1;color:#fff;border:none;border-radius:6px;padding:.5rem 1rem;font-size:.8125rem;cursor:pointer;margin-top:.75rem}
+    .btn:hover{background:#4f46e5}
+    .btn.copied{background:#16a34a}
     footer{margin-top:3rem;padding-top:1rem;border-top:1px solid var(--border);color:var(--muted);font-size:.75rem;text-align:center}
   </style>
 </head>
 <body>
   <h1>${title}</h1>
-  <p class="subtitle">Scanned ${scannedFiles} files in ${scanDurationMs}ms</p>
+  <p class="subtitle">Scanned ${scannedFiles} files in ${scanDurationMs}ms \xB7 ${esc(date)}</p>
 
+  <h2>Executive Summary</h2>
   <div class="cards">
-    <div class="card"><div class="card-num">${scannedFiles}</div><div class="card-label">Files Scanned</div></div>
+    <div class="card"><div class="card-num">${totalUsages}</div><div class="card-label">Total Call-Sites</div></div>
     <div class="card"><div class="card-num">${uniqueFlags.length}</div><div class="card-label">Unique Flags</div></div>
-    <div class="card"><div class="card-num">${totalUsages}</div><div class="card-label">Total Usages</div></div>
+    <div class="card"><div class="card-num">${affectedFiles}</div><div class="card-label">Files Affected</div></div>
     <div class="card"><div class="card-num yellow">${staleCount}</div><div class="card-label">Stale Candidates</div></div>
-    <div class="card"><div class="card-num blue">${dynamicCount}</div><div class="card-label">Dynamic Keys</div></div>
+    <div class="card"><div class="card-num blue">${dynamicCount}</div><div class="card-label">Dynamic Keys</div></div>${auditCards}
   </div>
 
   <h2>Flag Inventory</h2>
@@ -744,15 +805,41 @@ function formatHTML(result, options) {
     </tbody>
   </table>
 
-  <footer>Generated by FlagLint ${esc(version)} on ${esc(date)}</footer>
+  <h2>Findings by Directory</h2>
+  <table id="dir-table">
+    <thead><tr><th>Directory</th><th>Call-Sites</th><th>Unique Flags</th><th>Call Types</th></tr></thead>
+    <tbody>
+      ${dirRows}
+    </tbody>
+  </table>
+
+  <h2>Recommended Next Steps</h2>
+  <ol class="steps">
+    <li>Configure the OpenFeature provider once at application startup (manual \u2014 see <code>flaglint migrate --dry-run</code> for guidance)</li>
+    <li>Review the migration plan: <code>flaglint migrate --dry-run</code></li>
+    <li>Apply automatable transformations: <code>flaglint migrate --apply</code></li>
+    <li>Add CI policy enforcement: <code>flaglint validate --no-direct-launchdarkly</code></li>
+  </ol>
+  <button class="btn" id="copy-btn" onclick="copyMarkdown()">\u{1F4CB} Copy Markdown Summary</button>
+
+  <footer>Generated by FlagLint ${esc(version)}</footer>
 
   <script>
     const input = document.getElementById('filter');
-    const rows = document.querySelectorAll('#flags-table tbody tr');
+    const tableRows = document.querySelectorAll('#flags-table tbody tr');
     input.addEventListener('input', () => {
       const q = input.value.toLowerCase();
-      rows.forEach(r => { r.style.display = r.textContent.toLowerCase().includes(q) ? '' : 'none'; });
+      tableRows.forEach(r => { r.style.display = r.textContent.toLowerCase().includes(q) ? '' : 'none'; });
     });
+    function copyMarkdown() {
+      const md = ${JSON.stringify(markdownSummary)}.replace(/\\\\n/g, '\\n');
+      navigator.clipboard.writeText(md).then(() => {
+        const btn = document.getElementById('copy-btn');
+        btn.textContent = '\u2713 Copied!';
+        btn.className = 'btn copied';
+        setTimeout(() => { btn.textContent = '\u{1F4CB} Copy Markdown Summary'; btn.className = 'btn'; }, 2000);
+      });
+    }
   </script>
 </body>
 </html>`;
@@ -788,6 +875,9 @@ var FlagLintConfigSchema = z.object({
   // TODO v0.3: replace minFileCount with real date-based staleness via git log
   minFileCount: z.number().int().min(0).default(0),
   wrappers: z.array(z.string()).default([]),
+  openFeatureClientBindings: z.array(
+    z.object({ importName: z.string(), modulePatterns: z.array(z.string()).default([]) })
+  ).default([]),
   reportTitle: z.string().optional(),
   outputDir: z.string().default(".")
 });
@@ -962,7 +1052,7 @@ Examples:
       } else {
         process.stdout.write(report + "\n");
       }
-      process.exit(staleCount > 0 ? 1 : 0);
+      process.exitCode = staleCount > 0 ? 1 : 0;
     }
   );
 }
@@ -1103,7 +1193,7 @@ function formatMigrationReport(analysis) {
     unsupportedUnknownCount
   } = analysis;
   const date = (/* @__PURE__ */ new Date()).toLocaleDateString();
-  const version = true ? "0.4.1" : "0.1.0";
+  const version = true ? "0.5.0" : "0.1.0";
   const lines = [];
   lines.push("# OpenFeature Migration Inventory");
   lines.push(`Generated by FlagLint v${version} on ${date}`);
@@ -1194,7 +1284,7 @@ function manualReason(item) {
   if (item.manualReviewReason === "bulk-inventory-call") return "bulk inventory call has no single-flag codemod";
   return "manual review required";
 }
-function buildReplacement(item) {
+function buildReplacement(item, clientBindingName) {
   if (DETAIL_METHODS.has(item.launchDarklyMethod)) {
     return {
       item,
@@ -1212,11 +1302,13 @@ function buildReplacement(item) {
   }
   const method = methodForType(item.valueType);
   if (!method) return { item, reason: "unsupported or unknown value type" };
-  const call = `openFeatureClient.${method}(${item.flagKeyExpression}, ${item.fallbackExpression}, ${item.evaluationContextExpression})`;
+  const placeholder = "openFeatureClient";
+  const target = clientBindingName ?? placeholder;
+  const call = `${target}.${method}(${item.flagKeyExpression}, ${item.fallbackExpression}, ${item.evaluationContextExpression})`;
   return {
     item,
     replacement: call,
-    requiresProviderSetup: true
+    requiresProviderSetup: clientBindingName == null
   };
 }
 function applyReplacements(code, replacements) {
@@ -1302,17 +1394,27 @@ function formatProviderSetupSection() {
   lines.push("");
   return lines;
 }
-async function formatDryRunDiff(analysis, source) {
+async function formatDryRunDiff(analysis, source, allowedBindings = []) {
   const replacementsByFile = /* @__PURE__ */ new Map();
   const skipped = [];
+  const itemsByFile = /* @__PURE__ */ new Map();
   for (const item of analysis.inventoryItems) {
-    const result = buildReplacement(item);
-    if ("reason" in result) {
-      skipped.push(result);
-      continue;
+    if (!itemsByFile.has(item.file)) itemsByFile.set(item.file, []);
+    itemsByFile.get(item.file).push(item);
+  }
+  for (const [file, items] of [...itemsByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const before = await source.readFile(file);
+    const { getOpenFeatureClientBindingName } = await import("../apply-ZYLA2N7Y.js");
+    const clientBindingName = getOpenFeatureClientBindingName(before, allowedBindings);
+    for (const item of items) {
+      const result = buildReplacement(item, clientBindingName);
+      if ("reason" in result) {
+        skipped.push(result);
+        continue;
+      }
+      if (!replacementsByFile.has(item.file)) replacementsByFile.set(item.file, []);
+      replacementsByFile.get(item.file).push(result);
     }
-    if (!replacementsByFile.has(item.file)) replacementsByFile.set(item.file, []);
-    replacementsByFile.get(item.file).push(result);
   }
   const lines = [];
   lines.push("# FlagLint migrate --dry-run");
@@ -1350,205 +1452,6 @@ async function formatDryRunDiff(analysis, source) {
   return lines.join("\n");
 }
 
-// src/migrator/apply.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-import { parse as parse2 } from "@typescript-eslint/typescript-estree";
-var execFileAsync = promisify(execFile);
-var ApplyError = class extends Error {
-  constructor(kind, message) {
-    super(message);
-    this.kind = kind;
-    this.name = "ApplyError";
-  }
-  kind;
-};
-var OF_SERVER_SDK = "@openfeature/server-sdk";
-function tryParse(code) {
-  for (const jsx of [false, true]) {
-    try {
-      return parse2(code, { jsx, comment: false });
-    } catch {
-    }
-  }
-  return null;
-}
-function walkNodes(root, visit) {
-  const stack = [root];
-  while (stack.length > 0) {
-    const node = stack.pop();
-    visit(node);
-    for (const val of Object.values(node)) {
-      if (Array.isArray(val)) {
-        for (const item of val) {
-          if (item !== null && typeof item === "object" && "type" in item) {
-            stack.push(item);
-          }
-        }
-      } else if (val !== null && typeof val === "object" && "type" in val) {
-        stack.push(val);
-      }
-    }
-  }
-}
-function hasOpenFeatureClientBinding(code) {
-  const ast = tryParse(code);
-  if (!ast) return false;
-  const ofApiNames = /* @__PURE__ */ new Set();
-  for (const stmt of ast.body) {
-    if (stmt.type === "ImportDeclaration" && stmt.source.value === OF_SERVER_SDK) {
-      for (const spec of stmt.specifiers) {
-        if (spec.type === "ImportSpecifier") {
-          const importedName = spec.imported.type === "Identifier" ? spec.imported.name : spec.imported.value;
-          if (importedName === "OpenFeature") {
-            ofApiNames.add(spec.local.name);
-          }
-        }
-      }
-      continue;
-    }
-    if (stmt.type === "VariableDeclaration") {
-      for (const decl of stmt.declarations) {
-        const init = decl.init;
-        if (init?.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "require" && init.arguments.length === 1 && init.arguments[0]?.type === "Literal" && init.arguments[0].value === OF_SERVER_SDK && decl.id.type === "ObjectPattern") {
-          for (const prop of decl.id.properties) {
-            if (prop.type === "Property" && prop.key.type === "Identifier" && prop.key.name === "OpenFeature" && prop.value.type === "Identifier") {
-              ofApiNames.add(prop.value.name);
-            }
-          }
-        }
-      }
-    }
-  }
-  if (ofApiNames.size === 0) return false;
-  let proven = false;
-  walkNodes(ast, (node) => {
-    if (proven) return;
-    if (node.type !== "VariableDeclarator") return;
-    const decl = node;
-    if (decl.id.type !== "Identifier") return;
-    if (decl.id.name !== "openFeatureClient") return;
-    if (decl.init?.type !== "CallExpression") return;
-    const call = decl.init;
-    if (call.callee.type !== "MemberExpression") return;
-    const member = call.callee;
-    if (member.computed) return;
-    if (member.object.type !== "Identifier") return;
-    if (!ofApiNames.has(member.object.name)) return;
-    if (member.property.type !== "Identifier") return;
-    if (member.property.name !== "getClient") return;
-    proven = true;
-  });
-  return proven;
-}
-var DETAIL_METHODS2 = /* @__PURE__ */ new Set([
-  "variationDetail",
-  "boolVariationDetail",
-  "stringVariationDetail",
-  "numberVariationDetail",
-  "jsonVariationDetail"
-]);
-function methodForType2(valueType) {
-  switch (valueType) {
-    case "boolean":
-      return "getBooleanValue";
-    case "string":
-      return "getStringValue";
-    case "number":
-      return "getNumberValue";
-    case "object":
-      return "getObjectValue";
-    case "unknown":
-      return null;
-  }
-}
-function buildReplacement2(item, code) {
-  if (DETAIL_METHODS2.has(item.launchDarklyMethod)) {
-    return {
-      item,
-      reason: "detail methods skipped: OpenFeature detail APIs exist, but LaunchDarkly/OpenFeature detail result parity requires manual review"
-    };
-  }
-  if (!item.safelyAutomatable) {
-    const reason = item.manualReviewReason === "dynamic-key" ? "dynamic key requires manual review" : item.manualReviewReason === "unknown-fallback" ? "unknown fallback type requires manual review" : item.manualReviewReason === "bulk-inventory-call" ? "bulk inventory call has no single-flag codemod" : "manual review required";
-    return { item, reason };
-  }
-  if (item.rangeStart == null || item.rangeEnd == null || !item.callExpression) {
-    return { item, reason: "missing source range for apply" };
-  }
-  const currentText = code.slice(item.rangeStart, item.rangeEnd);
-  if (currentText !== item.callExpression) {
-    return {
-      item,
-      reason: "range content does not match original call \u2014 already transformed or stale analysis; skipping"
-    };
-  }
-  if (!item.flagKeyExpression || !item.fallbackExpression || !item.evaluationContextExpression) {
-    return { item, reason: "missing flag key, fallback, or evaluation context evidence" };
-  }
-  const method = methodForType2(item.valueType);
-  if (!method) return { item, reason: "unsupported or unknown value type" };
-  const call = `openFeatureClient.${method}(${item.flagKeyExpression}, ${item.fallbackExpression}, ${item.evaluationContextExpression})`;
-  return { item, replacement: call };
-}
-function applyReplacements2(code, replacements) {
-  let next = code;
-  for (const r of [...replacements].sort((a, b) => b.item.rangeStart - a.item.rangeStart)) {
-    next = next.slice(0, r.item.rangeStart) + r.replacement + next.slice(r.item.rangeEnd);
-  }
-  return next;
-}
-async function defaultIsWorkingTreeDirty() {
-  try {
-    const { stdout } = await execFileAsync("git", ["status", "--porcelain"]);
-    return stdout.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-async function applyMigration(analysis, source, options = {}) {
-  if (!options.allowDirty) {
-    const checkDirty = options.isWorkingTreeDirty ?? defaultIsWorkingTreeDirty;
-    if (await checkDirty()) {
-      throw new ApplyError(
-        "dirty-tree",
-        "Working tree has uncommitted changes.\nCommit or stash your changes first, or pass --allow-dirty to override.\nReview `flaglint migrate --dry-run` for provider setup guidance before applying."
-      );
-    }
-  }
-  const itemsByFile = /* @__PURE__ */ new Map();
-  for (const item of analysis.inventoryItems) {
-    if (!itemsByFile.has(item.file)) itemsByFile.set(item.file, []);
-    itemsByFile.get(item.file).push(item);
-  }
-  const transformedFiles = [];
-  const skippedFiles = [];
-  let transformed = 0;
-  for (const [file, items] of [...itemsByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-    const code = await source.readFile(file);
-    if (!hasOpenFeatureClientBinding(code)) {
-      skippedFiles.push({
-        file,
-        reason: "skipped \u2014 OpenFeature client setup required. Review `flaglint migrate --dry-run` provider guidance first."
-      });
-      continue;
-    }
-    const replacements = [];
-    for (const item of items) {
-      const result = buildReplacement2(item, code);
-      if ("reason" in result) continue;
-      replacements.push(result);
-    }
-    if (replacements.length === 0) continue;
-    const newCode = applyReplacements2(code, replacements);
-    if (newCode === code) continue;
-    await source.writeFile(file, newCode);
-    transformedFiles.push(file);
-    transformed += replacements.length;
-  }
-  return { transformed, skipped: skippedFiles.length, transformedFiles, skippedFiles };
-}
-
 // src/commands/migrate.ts
 function registerMigrateCommand(program2) {
   program2.command("migrate").description("Analyze migration readiness and generate an OpenFeature migration plan").argument("[dir]", "directory to analyze", process.cwd()).option("-o, --output <file>", "write migration plan to file", "MIGRATION.md").option("-c, --config <path>", "path to .flaglintrc config file").option("--dry-run", "print reviewable diffs to stdout without writing files").option("--apply", "apply safe transformations to source files in-place").option("--allow-dirty", "allow --apply on a dirty git working tree").option("--exclude-tests", "exclude test files (*.test.*, *.spec.*, __tests__/, tests/)").addHelpText(
@@ -1655,14 +1558,14 @@ Examples:
         )
       );
       if (options.dryRun) {
-        const report2 = await formatDryRunDiff(analysis, source);
+        const report2 = await formatDryRunDiff(analysis, source, config.openFeatureClientBindings);
         process.stdout.write(report2 + "\n");
         process.exit(0);
       }
       if (options.apply) {
         let result;
         try {
-          result = await applyMigration(analysis, source, { allowDirty: options.allowDirty });
+          result = await applyMigration(analysis, source, { allowDirty: options.allowDirty, allowedOpenFeatureClientBindings: config.openFeatureClientBindings });
         } catch (err) {
           if (err instanceof ApplyError && err.kind === "dirty-tree") {
             process.stderr.write(chalk2.red(`
@@ -1725,12 +1628,15 @@ Error: ${err.message}
 }
 
 // src/commands/validate.ts
+import { writeFile as writeFile4 } from "fs/promises";
 import { stat as stat3 } from "fs/promises";
-import { resolve as resolve6 } from "path";
+import { resolve as resolve7 } from "path";
 import chalk3 from "chalk";
 import ora3 from "ora";
 
 // src/validator/index.ts
+import { resolve as resolve6 } from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
 function matchesBootstrapPattern(file, patterns) {
   const clean = (s) => s.replace(/^\.\//, "");
   const cleanFile = clean(file);
@@ -1801,8 +1707,106 @@ function formatValidationReport(result, options = {}) {
   lines.push("Run `flaglint migrate --dry-run` to review the migration plan.");
   return lines.join("\n") + "\n";
 }
+var SARIF_RULE_NO_DIRECT_LD = {
+  id: "flaglint.direct-launchdarkly",
+  name: "DirectLaunchDarklySDKUsage",
+  shortDescription: {
+    text: "Direct LaunchDarkly SDK evaluation call detected"
+  },
+  fullDescription: {
+    text: "A direct LaunchDarkly Node.js server SDK evaluation call was found. Migrate this call to OpenFeature so the codebase is provider-independent."
+  },
+  helpUri: "https://github.com/flaglint/flaglint#flaglint-validate-dir",
+  properties: {
+    tags: ["openfeature", "migration", "launchdarkly"]
+  }
+};
+function sarifViolationUri(file) {
+  return file.split(/[\\/]/).join("/");
+}
+function sarifScanRootUri(scanRoot) {
+  const uri = pathToFileURL2(resolve6(scanRoot)).href;
+  return uri.endsWith("/") ? uri : `${uri}/`;
+}
+function violationSarifMessage(v) {
+  if (v.isDynamic) {
+    return `Direct LaunchDarkly SDK call ${v.callType}() with a dynamic flag key at ${v.file}:${v.line}. Migrate to OpenFeature using flaglint migrate --dry-run.`;
+  }
+  if (v.flagKey === "*") {
+    return `Direct LaunchDarkly bulk inventory call ${v.callType}() at ${v.file}:${v.line}. Migrate to OpenFeature using flaglint migrate --dry-run.`;
+  }
+  return `Direct LaunchDarkly SDK call ${v.callType}("${v.flagKey}") at ${v.file}:${v.line}. Migrate to OpenFeature using flaglint migrate --dry-run.`;
+}
+function formatValidationSarif(result, scanRoot, scannedAt) {
+  return JSON.stringify(
+    {
+      $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: "FlagLint",
+              informationUri: "https://github.com/flaglint/flaglint",
+              rules: [SARIF_RULE_NO_DIRECT_LD]
+            }
+          },
+          invocations: [
+            {
+              executionSuccessful: true,
+              startTimeUtc: scannedAt,
+              properties: {
+                scannedFiles: result.scannedFiles,
+                totalUsages: result.totalUsages,
+                violations: result.violations.length,
+                passed: result.passed
+              }
+            }
+          ],
+          originalUriBaseIds: {
+            "%SRCROOT%": {
+              uri: sarifScanRootUri(scanRoot)
+            }
+          },
+          results: result.violations.map((v) => ({
+            ruleId: SARIF_RULE_NO_DIRECT_LD.id,
+            level: "error",
+            message: {
+              text: violationSarifMessage(v)
+            },
+            locations: [
+              {
+                physicalLocation: {
+                  artifactLocation: {
+                    uri: sarifViolationUri(v.file),
+                    uriBaseId: "%SRCROOT%"
+                  },
+                  region: {
+                    startLine: Math.max(v.line, 1),
+                    startColumn: Math.max(v.column + 1, 1)
+                  }
+                }
+              }
+            ],
+            partialFingerprints: {
+              "flagKey/v1": v.flagKey
+            },
+            properties: {
+              flagKey: v.flagKey,
+              callType: v.callType,
+              isDynamic: v.isDynamic
+            }
+          }))
+        }
+      ]
+    },
+    null,
+    2
+  );
+}
 
 // src/commands/validate.ts
+var VALID_VALIDATE_FORMATS = ["text", "sarif"];
 function registerValidateCommand(program2) {
   program2.command("validate").description("Validate that your codebase complies with feature flag usage policies").argument("[dir]", "directory to validate", process.cwd()).option(
     "--no-direct-launchdarkly",
@@ -1812,7 +1816,11 @@ function registerValidateCommand(program2) {
     "glob pattern for files allowed to use LaunchDarkly SDK directly (repeatable)",
     (val, prev) => [...prev, val],
     []
-  ).option("-c, --config <path>", "path to .flaglintrc config file").addHelpText(
+  ).option(
+    "-f, --format <format>",
+    "output format: text | sarif",
+    "text"
+  ).option("-o, --output <file>", "write report to file instead of stdout").option("-c, --config <path>", "path to .flaglintrc config file").addHelpText(
     "after",
     `
 Examples:
@@ -1822,13 +1830,25 @@ Examples:
       --bootstrap-exclude src/provider/setup.ts             allow bootstrap file
   $ flaglint validate --no-direct-launchdarkly \\
       --bootstrap-exclude "src/provider/**"                 allow all provider files
+  $ flaglint validate --no-direct-launchdarkly \\
+      --format sarif --output flaglint.sarif                emit SARIF for GitHub Code Scanning
   $ flaglint validate --no-direct-launchdarkly \\
       --bootstrap-exclude "src/provider/*.ts" \\
       --bootstrap-exclude "src/bootstrap/**"                multiple exclusion patterns`
   ).action(
     async (dir, options) => {
+      if (!VALID_VALIDATE_FORMATS.includes(options.format)) {
+        process.stderr.write(
+          chalk3.red(
+            `Error: Invalid format '${options.format}'. Must be one of: ${VALID_VALIDATE_FORMATS.join(", ")}
+`
+          )
+        );
+        process.exit(2);
+      }
+      const format = options.format;
       try {
-        const s = await stat3(resolve6(dir));
+        const s = await stat3(resolve7(dir));
         if (!s.isDirectory()) {
           process.stderr.write(chalk3.red(`Error: Not a directory: ${dir}
 `));
@@ -1883,8 +1903,34 @@ Examples:
         bootstrapExclude
       };
       const validationResult = validateScanResult(scanResult, validateOptions);
-      const report = formatValidationReport(validationResult, validateOptions);
-      process.stdout.write(report);
+      let report;
+      if (format === "sarif") {
+        report = formatValidationSarif(
+          validationResult,
+          scanResult.scanRoot,
+          scanResult.scannedAt
+        );
+      } else {
+        report = formatValidationReport(validationResult, validateOptions);
+      }
+      if (options.output) {
+        const outPath = resolve7(options.output);
+        try {
+          await writeFile4(outPath, report, "utf8");
+          process.stderr.write(chalk3.dim(`   Report written to ${options.output}
+`));
+        } catch (err) {
+          process.stderr.write(
+            chalk3.red(
+              `Error: Failed to write report to ${options.output}: ${err instanceof Error ? err.message : String(err)}
+`
+            )
+          );
+          process.exit(1);
+        }
+      } else {
+        process.stdout.write(report);
+      }
       if (!validationResult.passed) {
         process.exit(1);
       }
@@ -1896,7 +1942,7 @@ Examples:
 // src/cli.ts
 function createCLI() {
   const program2 = new Command();
-  program2.name("flaglint").description("LaunchDarkly Node.js server SDK -> OpenFeature migration.").version("0.4.1", "-v, --version", "output the current version").addHelpText(
+  program2.name("flaglint").description("LaunchDarkly Node.js server SDK -> OpenFeature migration.").version("0.5.0", "-v, --version", "output the current version").addHelpText(
     "after",
     `
 Examples:

package/dist/chunk-MJLXM6GZ.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+// src/migrator/apply.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { parse } from "@typescript-eslint/typescript-estree";
+import micromatch from "micromatch";
+function moduleSpecifierMatchesGlob(specifier, pattern) {
+  const normalizeRelative = (value) => value.replace(/^(?:\.\.?\/)+/, "");
+  const normalizedSpecifier = normalizeRelative(specifier);
+  const normalizedPattern = normalizeRelative(pattern);
+  if (micromatch.isMatch(normalizedSpecifier, normalizedPattern)) return true;
+  if (!normalizedSpecifier.endsWith(".js")) return false;
+  return micromatch.isMatch(normalizedSpecifier.slice(0, -3), normalizedPattern);
+}
+var execFileAsync = promisify(execFile);
+var ApplyError = class extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+    this.name = "ApplyError";
+  }
+  kind;
+};
+var OF_SERVER_SDK = "@openfeature/server-sdk";
+function tryParse(code) {
+  for (const jsx of [false, true]) {
+    try {
+      return parse(code, { jsx, comment: false });
+    } catch {
+    }
+  }
+  return null;
+}
+function walkNodes(root, visit) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    visit(node);
+    for (const val of Object.values(node)) {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item !== null && typeof item === "object" && "type" in item) {
+            stack.push(item);
+          }
+        }
+      } else if (val !== null && typeof val === "object" && "type" in val) {
+        stack.push(val);
+      }
+    }
+  }
+}
+function getOpenFeatureClientBindingName(code, allowedBindings = []) {
+  const ast = tryParse(code);
+  if (!ast) return null;
+  const ofApiNames = /* @__PURE__ */ new Set();
+  for (const stmt of ast.body) {
+    if (stmt.type === "ImportDeclaration" && stmt.source.value === OF_SERVER_SDK) {
+      for (const spec of stmt.specifiers) {
+        if (spec.type === "ImportSpecifier") {
+          const importedName = spec.imported.type === "Identifier" ? spec.imported.name : spec.imported.value;
+          if (importedName === "OpenFeature") {
+            ofApiNames.add(spec.local.name);
+          }
+        }
+      }
+      continue;
+    }
+    if (stmt.type === "VariableDeclaration") {
+      for (const decl of stmt.declarations) {
+        const init = decl.init;
+        if (init?.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "require" && init.arguments.length === 1 && init.arguments[0]?.type === "Literal" && init.arguments[0].value === OF_SERVER_SDK && decl.id.type === "ObjectPattern") {
+          for (const prop of decl.id.properties) {
+            if (prop.type === "Property" && prop.key.type === "Identifier" && prop.key.name === "OpenFeature" && prop.value.type === "Identifier") {
+              ofApiNames.add(prop.value.name);
+            }
+          }
+        }
+      }
+    }
+  }
+  const candidates = [];
+  walkNodes(ast, (node) => {
+    if (node.type !== "VariableDeclarator") return;
+    const decl = node;
+    if (decl.id.type !== "Identifier") return;
+    if (decl.init?.type !== "CallExpression") return;
+    const call = decl.init;
+    if (call.callee.type !== "MemberExpression") return;
+    const member = call.callee;
+    if (member.computed) return;
+    if (member.object.type !== "Identifier") return;
+    if (!ofApiNames.has(member.object.name)) return;
+    if (member.property.type !== "Identifier") return;
+    if (member.property.name !== "getClient") return;
+    candidates.push(decl.id.name);
+  });
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length > 1) return null;
+  for (const stmt of ast.body) {
+    if (stmt.type === "ImportDeclaration") {
+      const source = String(stmt.source.value || "");
+      if (!source.startsWith(".")) continue;
+      for (const spec of stmt.specifiers) {
+        if (spec.type === "ImportSpecifier") {
+          const importedName = spec.imported.type === "Identifier" ? spec.imported.name : spec.imported.value;
+          const allowed = allowedBindings.find((b) => b.importName === importedName);
+          if (!allowed) continue;
+          if (!allowed.modulePatterns.some((p) => moduleSpecifierMatchesGlob(source, p))) continue;
+          candidates.push(spec.local.name);
+        }
+        if (spec.type === "ImportDefaultSpecifier") {
+          const local = spec.local.name;
+          const allowed = allowedBindings.find((b) => b.importName === local);
+          if (!allowed) continue;
+          if (!allowed.modulePatterns.some((p) => moduleSpecifierMatchesGlob(source, p))) continue;
+          candidates.push(local);
+        }
+      }
+    }
+    if (stmt.type === "VariableDeclaration") {
+      for (const decl of stmt.declarations) {
+        const init = decl.init;
+        if (init?.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "require" && init.arguments.length === 1 && init.arguments[0]?.type === "Literal") {
+          const source = String(init.arguments[0].value || "");
+          if (!source.startsWith(".")) continue;
+          if (decl.id.type === "ObjectPattern") {
+            for (const prop of decl.id.properties) {
+              if (prop.type !== "Property" || prop.key.type !== "Identifier") continue;
+              const importedName = prop.key.name;
+              const local = prop.value.type === "Identifier" ? prop.value.name : null;
+              if (!local) continue;
+              const allowed = allowedBindings.find((b) => b.importName === importedName);
+              if (!allowed) continue;
+              if (!allowed.modulePatterns.some((p) => moduleSpecifierMatchesGlob(source, p))) continue;
+              candidates.push(local);
+            }
+          }
+        }
+      }
+    }
+  }
+  if (candidates.length === 1) return candidates[0];
+  return null;
+}
+function hasOpenFeatureClientBinding(code) {
+  return getOpenFeatureClientBindingName(code) != null;
+}
+var DETAIL_METHODS = /* @__PURE__ */ new Set([
+  "variationDetail",
+  "boolVariationDetail",
+  "stringVariationDetail",
+  "numberVariationDetail",
+  "jsonVariationDetail"
+]);
+function methodForType(valueType) {
+  switch (valueType) {
+    case "boolean":
+      return "getBooleanValue";
+    case "string":
+      return "getStringValue";
+    case "number":
+      return "getNumberValue";
+    case "object":
+      return "getObjectValue";
+    case "unknown":
+      return null;
+  }
+}
+function buildReplacement(item, code, clientBindingName) {
+  if (DETAIL_METHODS.has(item.launchDarklyMethod)) {
+    return {
+      item,
+      reason: "detail methods skipped: OpenFeature detail APIs exist, but LaunchDarkly/OpenFeature detail result parity requires manual review"
+    };
+  }
+  if (!item.safelyAutomatable) {
+    const reason = item.manualReviewReason === "dynamic-key" ? "dynamic key requires manual review" : item.manualReviewReason === "unknown-fallback" ? "unknown fallback type requires manual review" : item.manualReviewReason === "bulk-inventory-call" ? "bulk inventory call has no single-flag codemod" : "manual review required";
+    return { item, reason };
+  }
+  if (item.rangeStart == null || item.rangeEnd == null || !item.callExpression) {
+    return { item, reason: "missing source range for apply" };
+  }
+  const currentText = code.slice(item.rangeStart, item.rangeEnd);
+  if (currentText !== item.callExpression) {
+    return {
+      item,
+      reason: "range content does not match original call \u2014 already transformed or stale analysis; skipping"
+    };
+  }
+  if (!item.flagKeyExpression || !item.fallbackExpression || !item.evaluationContextExpression) {
+    return { item, reason: "missing flag key, fallback, or evaluation context evidence" };
+  }
+  const method = methodForType(item.valueType);
+  if (!method) return { item, reason: "unsupported or unknown value type" };
+  const call = `${clientBindingName}.${method}(${item.flagKeyExpression}, ${item.fallbackExpression}, ${item.evaluationContextExpression})`;
+  return { item, replacement: call };
+}
+function applyReplacements(code, replacements) {
+  let next = code;
+  for (const r of [...replacements].sort((a, b) => b.item.rangeStart - a.item.rangeStart)) {
+    next = next.slice(0, r.item.rangeStart) + r.replacement + next.slice(r.item.rangeEnd);
+  }
+  return next;
+}
+async function defaultIsWorkingTreeDirty() {
+  try {
+    const { stdout } = await execFileAsync("git", ["status", "--porcelain"]);
+    return stdout.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+async function applyMigration(analysis, source, options = {}) {
+  if (!options.allowDirty) {
+    const checkDirty = options.isWorkingTreeDirty ?? defaultIsWorkingTreeDirty;
+    if (await checkDirty()) {
+      throw new ApplyError(
+        "dirty-tree",
+        "Working tree has uncommitted changes.\nCommit or stash your changes first, or pass --allow-dirty to override.\nReview `flaglint migrate --dry-run` for provider setup guidance before applying."
+      );
+    }
+  }
+  const itemsByFile = /* @__PURE__ */ new Map();
+  for (const item of analysis.inventoryItems) {
+    if (!itemsByFile.has(item.file)) itemsByFile.set(item.file, []);
+    itemsByFile.get(item.file).push(item);
+  }
+  const transformedFiles = [];
+  const skippedFiles = [];
+  let transformed = 0;
+  for (const [file, items] of [...itemsByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const code = await source.readFile(file);
+    const bindingName = getOpenFeatureClientBindingName(code, options.allowedOpenFeatureClientBindings ?? []);
+    if (!bindingName) {
+      skippedFiles.push({
+        file,
+        reason: "skipped \u2014 OpenFeature client setup required. Review `flaglint migrate --dry-run` provider guidance first."
+      });
+      continue;
+    }
+    const replacements = [];
+    for (const item of items) {
+      const result = buildReplacement(item, code, bindingName);
+      if ("reason" in result) continue;
+      replacements.push(result);
+    }
+    if (replacements.length === 0) continue;
+    const newCode = applyReplacements(code, replacements);
+    if (newCode === code) continue;
+    await source.writeFile(file, newCode);
+    transformedFiles.push(file);
+    transformed += replacements.length;
+  }
+  return { transformed, skipped: skippedFiles.length, transformedFiles, skippedFiles };
+}
+
+export {
+  ApplyError,
+  getOpenFeatureClientBindingName,
+  hasOpenFeatureClientBinding,
+  applyMigration
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flaglint",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "LaunchDarkly Node.js server SDK -> OpenFeature migration.",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "keywords": [
     "feature-flags",
@@ -39,8 +39,11 @@
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "typecheck:agent": "tsc --project tsconfig.agent.json",
+    "pretest": "npm run build",
     "test": "vitest",
+    "pretest:run": "npm run build",
     "test:run": "vitest run",
+    "pretest:coverage": "npm run build",
     "test:coverage": "vitest run --coverage",
     "new-branch": "tsx scripts/new-branch.ts",
     "release:patch": "tsx scripts/release.ts patch",
@@ -53,11 +56,13 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
+    "micromatch": "^4.0.8",
     "ora": "^8.1.0",
     "p-limit": "^7.3.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@types/micromatch": "^4.0.10",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.6",
     "clipboardy": "^4.0.0",