flaglint 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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]
+
+## [0.4.0] - 2026-05-24
+
+### Added
+
+- Release preparation: bump package version to 0.4.0, normalize repository URL, and adjust release workflow to publish only from manual GitHub Releases. No publish or tag created by this change.
+
+### Added
+
+- **`flaglint migrate --dry-run`**: Generates reviewable before/after diffs for every automatable
+  call-site, including inline provider setup guidance (packages, bootstrap file, `targetingKey`
+  context requirement). Does not write any files; output is to stdout.
+
+- **Docs**: Repositioned public copy and website messaging to explicitly state scope (LaunchDarkly Node.js server SDK only), clarify that `--apply` is guarded, confirm provider/bootstrap setup is manual, and limit precision/recall claims to the 120 deterministic benchmark cases within that supported scope.
+
+- **`flaglint migrate --apply`**: Applies only guarded, provably automatable transformations
+  in-place. Safety contracts: refuses on a dirty git working tree (override with `--allow-dirty`);
+  skips any file without a proven `openFeatureClient = OpenFeature.getClient()` binding from
+  `@openfeature/server-sdk` (AST-grounded, not regex); never rewrites detail methods, dynamic
+  keys, unknown fallbacks, or bulk calls; preserves `await` and all call arguments exactly;
+  idempotent (re-running a stale analysis is a no-op via range-content guard).
+
+- **`flaglint validate [dir]`**: New command for CI enforcement.
+  - Without `--no-direct-launchdarkly`: reports usages, always exits 0.
+  - `--no-direct-launchdarkly`: exits 1 if any direct LaunchDarkly Node server evaluation call
+    is found (static, dynamic, detail, or bulk — all count as violations).
+  - `--bootstrap-exclude <glob>` (repeatable): exclude provider bootstrap files from violations.
+    Supports exact paths, `*` (within one directory), `**` (across directories), and `?` wildcards.
+  - Never claims flags are stale or safe to delete.
+
+### Scope clarification
+
+Current scope: **LaunchDarkly Node.js server-side SDK** (`launchdarkly-node-server-sdk`).
+React hooks, HOC, and client-side SDK patterns are detected by `scan` but are not automatically
+migrated by `--apply`.
+
 ## [0.3.0] - 2026-05-23
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Your LaunchDarkly codebase has flag debt. FlagLint tells you exactly what and where.</strong>
+  <strong>LaunchDarkly Node.js server SDK -> OpenFeature migration</strong>
 </p>
 
 <p align="center">
@@ -21,35 +21,41 @@
   </a>
 </p>
 
+> ⚠️ **Early preview.** Current scope: **LaunchDarkly Node.js server-side SDK** only.
+> React hooks, HOC, and client-side SDK patterns are detected by `scan` but are not
+> automatically migrated.
 
 # FlagLint
 
-Find zombie flags. Eliminate flag debt. Generate your OpenFeature
-migration plan.
+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.
 
----
-
-## The problem
+**LaunchDarkly remains your provider. OpenFeature becomes the evaluation API your application code calls.**
 
-LaunchDarkly flags accumulate. Teams add them, forget to clean them up, and gradually build flag debt — dead code paths controlled by flags nobody manages. When you finally want to migrate to OpenFeature, you don't even know what you have.
+---
 
-Like Uber's Piranha — for any JS/TS codebase.
+## Workflow
 
-**FlagLint fixes this.** It scans your codebase, maps every flag usage, identifies stale candidates, and generates a step-by-step OpenFeature migration plan.
+| Step | Command | Purpose |
+|------|---------|---------|
+| 1 | `flaglint scan` | AST inventory of every direct LD Node server SDK call |
+| 2 | `flaglint migrate --dry-run` | Reviewable before/after diffs with provider setup guidance |
+| 3 | `flaglint migrate --apply` | Apply only guarded, provably automatable transformations |
+| 4 | `flaglint validate --no-direct-launchdarkly` | CI gate: exit 1 if direct LD calls remain |
 
 ---
 
 ## Quick start
 
 ```bash
-npx flaglint scan
+npx flaglint scan ./src
 ```
 
 Example output:
 
 ```text
 ✓ 15 flag usages found across 6 unique flags (48ms)
-⚠  5 potentially stale flag(s) — review recommended
 ℹ  1 dynamic flag key(s) require manual review
 ```
 
@@ -57,34 +63,25 @@ Markdown report excerpt:
 
 ```markdown
 ## Flag Inventory
-| Flag Key | Usages | Files | Call Types | Status |
-|----------|--------|-------|------------|--------|
-| show-banner | 1 | 1 | variation | ✓ Active |
-| old-checkout | 1 | 1 | variation | ⚠ Stale |
-| temp-debug-mode | 1 | 1 | variation | ⚠ Stale |
-
-## ⚠ Stale Flag Candidates
-| Flag Key | Reason | Location |
-|----------|--------|----------|
-| old-checkout | Contains "old" in key | ld-stale.ts:1 |
+| Flag Key | Usages | Files | Call Types |
+|----------|--------|-------|------------|
+| checkout-v2 | 3 | 2 | boolVariation |
+| color-theme | 1 | 1 | stringVariation |
+| timeout-ms  | 1 | 1 | numberVariation |
 ```
 
 ### JSON output (`--format json`)
 
-Pipe-friendly. Every usage includes file, line, call type,
-and structured staleness signals:
+Pipe-friendly. Every usage includes file, line, call type, and staleness signals:
 
 ```json
 {
-  "flagKey": "old-checkout",
+  "flagKey": "checkout-v2",
   "isDynamic": false,
-  "file": "src/components/Checkout.tsx",
+  "file": "src/services/checkout.ts",
   "line": 14,
-  "callType": "variation",
-  "stalenessSignals": [
-    { "source": "keyword", "keyword": "old" },
-    { "source": "minFileCount", "fileCount": 1, "threshold": 1 }
-  ]
+  "callType": "boolVariation",
+  "stalenessSignals": []
 }
 ```
 
@@ -104,7 +101,7 @@ npx flaglint
 
 ### `flaglint scan [dir]`
 
-Scans a directory for LaunchDarkly SDK usage.
+AST-based inventory of direct LaunchDarkly Node.js server SDK calls.
 
 ```bash
 flaglint scan ./src
@@ -120,7 +117,8 @@ flaglint scan --format sarif --output flaglint.sarif
 | `--config` | auto-detect | Path to a config file |
 | `--exclude-tests` | — | Exclude test files from scan results |
 
-Exit code `0` when no stale flags found, `1` when stale flags exist — enabling CI blocking.
+Exit code `0` when no staleness signals detected, `1` when staleness signals are present —
+enabling CI visibility into flag usage patterns.
 
 ---
 
@@ -129,17 +127,146 @@ Exit code `0` when no stale flags found, `1` when stale flags exist — enabling
 Analyzes migration readiness and generates an OpenFeature migration plan.
 
 ```bash
-flaglint migrate ./src
-flaglint migrate --dry-run
-flaglint migrate --output MIGRATION.md
+flaglint migrate ./src                     # write MIGRATION.md
+flaglint migrate --dry-run                 # reviewable diffs to stdout
+flaglint migrate --apply                   # guarded: apply only provably automatable transformations in-place
+flaglint migrate --apply --allow-dirty     # apply even on a dirty working tree
+flaglint migrate --output plan.md          # write to custom file
+flaglint migrate --exclude-tests           # skip test and spec files
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `--output` | `MIGRATION.md` | Write migration plan to file |
-| `--dry-run` | — | Print plan to stdout, do not write file |
+| `--dry-run` | — | Print reviewable diffs to stdout; includes provider setup guidance |
+| `--apply` | — | Apply automatable transformations in-place (requires clean git tree) |
+| `--allow-dirty` | — | Override dirty-tree guard for `--apply` |
+| `--config` | auto-detect | Path to a config file |
+| `--exclude-tests` | — | Skip `*.test.*`, `*.spec.*`, `__tests__/`, `tests/` |
+
+**`--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`)
+- 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
+
+---
+
+### `flaglint validate [dir]`
+
+Validates that your codebase complies with feature flag policy rules.
+Designed for CI enforcement after migration is complete.
+
+```bash
+flaglint validate                           # report usages, always exits 0
+flaglint validate --no-direct-launchdarkly  # exit 1 on any direct LD eval call
+flaglint validate --no-direct-launchdarkly \
+  --bootstrap-exclude src/provider/setup.ts # allow specific bootstrap file
+flaglint validate --no-direct-launchdarkly \
+  --bootstrap-exclude "src/provider/**"     # allow all provider-directory files
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--no-direct-launchdarkly` | — | Exit 1 if any direct LD Node server evaluation calls found |
+| `--bootstrap-exclude <glob>` | — | Repeatable glob; matching files excluded from violations |
 | `--config` | auto-detect | Path to a config file |
 
+Exit codes: `0` = passed, `1` = violations found, `130` = SIGINT.
+
+**Example pass output:**
+```
+✓ validate --no-direct-launchdarkly: no direct LaunchDarkly evaluation calls found.
+  Scanned 42 file(s).
+```
+
+**Example fail output:**
+```
+✗ validate --no-direct-launchdarkly: 2 direct LaunchDarkly evaluation call(s) found.
+
+  src/services/checkout.ts:42:8 — boolVariation("checkout-v2")
+  src/services/pricing.ts:17:4 — boolVariation(dynamic key — manual review required)
+
+These files must migrate to OpenFeature before this rule passes.
+Run `flaglint migrate --dry-run` to review the migration plan.
+```
+
+---
+
+## Supported API matrix
+
+**Scope: LaunchDarkly Node.js server-side SDK** (`launchdarkly-node-server-sdk`).
+
+| LaunchDarkly call | Automatable | OpenFeature equivalent |
+|---|---|---|
+| `ldClient.boolVariation(key, ctx, false)` | ✓ | `openFeatureClient.getBooleanValue(key, false, ctx)` |
+| `ldClient.stringVariation(key, ctx, "")` | ✓ | `openFeatureClient.getStringValue(key, "", ctx)` |
+| `ldClient.numberVariation(key, ctx, 0)` | ✓ | `openFeatureClient.getNumberValue(key, 0, ctx)` |
+| `ldClient.jsonVariation(key, ctx, {})` | ✓ | `openFeatureClient.getObjectValue(key, {}, ctx)` |
+| `ldClient.*VariationDetail(...)` | ✗ manual | Detail result shapes differ — requires manual review |
+| Dynamic flag key | ✗ manual | Key must be a static string literal |
+| `ldClient.allFlags()` / `allFlagsState()` | ✗ manual | Bulk calls — no single-flag codemod |
+| Unknown fallback type | ✗ manual | Fallback type must be determinable statically |
+| React `useFlags()`, `useLDClient()` | detect only | Client-side — outside Node.js server SDK scope |
+| React HOC / `<LDProvider>` | detect only | Client-side — outside Node.js server SDK scope |
+
+`flaglint scan` and `flaglint migrate --dry-run` report all detected patterns including manual-review cases.
+`flaglint migrate --apply` rewrites only the ✓ rows above.
+
+---
+
+## Provider setup (one-time manual step)
+
+`flaglint migrate --dry-run` includes this guidance inline. **Complete provider setup in
+one dedicated file before running `--apply`.**
+
+```bash
+npm install @openfeature/server-sdk \
+            @launchdarkly/node-server-sdk \
+            @launchdarkly/openfeature-node-server
+```
+
+Bootstrap file (do not apply automatically — bootstrap is intentionally manual):
+
+```typescript
+import LaunchDarkly from "@launchdarkly/node-server-sdk";
+import { LaunchDarklyProvider } from "@launchdarkly/openfeature-node-server";
+import { OpenFeature } from "@openfeature/server-sdk";
+
+const ldClient = LaunchDarkly.init(process.env.LD_SDK_KEY!);
+await OpenFeature.setProviderAndWait(new LaunchDarklyProvider(ldClient));
+
+// Evaluation context must include targetingKey (or key):
+// { targetingKey: user.id }
+export const openFeatureClient = OpenFeature.getClient();
+```
+
+**Do not remove any LaunchDarkly packages.** LaunchDarkly remains your feature flag provider;
+`@openfeature/server-sdk` becomes the evaluation interface your application code calls.
+
+---
+
+## Example transformation
+
+**Before — direct LaunchDarkly Node.js server SDK:**
+```typescript
+const enabled = await ldClient.boolVariation("checkout-v2", { key: user.id }, false);
+const theme   = await ldClient.stringVariation("color-theme", { key: user.id }, "light");
+const timeout = await ldClient.numberVariation("timeout-ms",  { key: user.id }, 5000);
+```
+
+**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 });
+```
+
+Flag key, fallback value, `await`, and evaluation context are preserved exactly.
+LaunchDarkly continues to serve the flags — only the call-site API changes.
+
 ---
 
 ## Configuration
@@ -161,8 +288,8 @@ Create `.flaglintrc`, `.flaglintrc.json`, or `flaglint.config.json` in your proj
 | `include` | `string[]` | `["**/*.{ts,tsx,js,jsx}"]` | Glob patterns to scan |
 | `exclude` | `string[]` | `["**/node_modules/**", ...]` | Glob patterns to ignore |
 | `provider` | `string` | `"launchdarkly"` | Feature flag provider |
-| `minFileCount` | `number` | `1` | A flag is stale if it appears in ≤ N files (default: 1) |
-| `wrappers` | `string[]` | `[]` | Function names that wrap LD SDK calls. FlagLint will detect calls to these functions as flag usages. Example: `["flagPredicate", "useFlag", "getFlag", "isEnabled"]` |
+| `minFileCount` | `number` | `1` | A flag is a staleness candidate if it appears in ≤ N files |
+| `wrappers` | `string[]` | `[]` | Function names wrapping LD SDK calls. Example: `["flagPredicate", "useFlag"]` |
 | `reportTitle` | `string` | — | Custom title for generated reports |
 | `outputDir` | `string` | `"."` | Default output directory |
 
@@ -172,18 +299,17 @@ FlagLint searches for config in this order: `--config` path → `.flaglintrc`
 
 ## CI Integration
 
-### Basic — block PRs on stale flags
+### Enforce OpenFeature migration: block PRs with direct LD calls
 
 ```yaml
-- name: Check for stale flags
-  run: npx flaglint scan --format json --output flaglint-report.json
-  # exits 1 if stale flags found, blocking the PR
+- name: Validate — no direct LaunchDarkly evaluations
+  run: |
+    npx flaglint validate --no-direct-launchdarkly \
+      --bootstrap-exclude "src/provider/setup.ts"
+  # exits 1 if any direct LD evaluation calls remain outside the bootstrap file
 ```
 
-### GitHub PR annotations via SARIF
-
-Stale flags appear as warnings directly in the PR diff —
-no dashboard, no separate tool.
+### Full migration CI pipeline with SARIF annotations
 
 ```yaml
 name: FlagLint
@@ -200,46 +326,32 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-      - name: Scan for flag debt
+
+      - name: Scan for LaunchDarkly SDK usage
         run: npx flaglint scan --format sarif --output flaglint.sarif
         continue-on-error: true
+
       - name: Upload to GitHub Code Scanning
         uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: flaglint.sarif
-```
-
-Stale flags show up as Code Scanning alerts on the exact file
-and line where the flag is used — reviewers see them in the PR
-without running anything locally.
 
----
-
-## What FlagLint detects
-
-- `ldClient.variation()` and `ldClient.variationDetail()`
-- `ldClient.allFlags()`
-- `useFlags()`, `useLDClient()` React hooks
-- `<LDProvider>` and `withLDConsumer()` patterns
-- Custom wrapper calls such as `flagPredicate("my-flag", false)` when configured with `wrappers`
-- Dynamic flag keys (runtime-determined, flagged for manual review)
+      - name: Enforce OpenFeature migration
+        run: |
+          npx flaglint validate --no-direct-launchdarkly \
+            --bootstrap-exclude "src/provider/setup.ts"
+```
 
-All detections include the **file path**, **line number**, **call type**, and staleness signals based on key names, file locations, and low file counts.
+Code Scanning alerts show the exact file and line of each direct LD call — reviewers see them in the PR without running anything locally.
 
 ---
 
-## OpenFeature Migration
+## Precision
 
-[OpenFeature](https://openfeature.dev) is the vendor-neutral standard for feature flagging (CNCF project). `flaglint migrate` maps your LaunchDarkly SDK calls to OpenFeature equivalents and generates an actionable `MIGRATION.md`:
+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.
 
-| LaunchDarkly | OpenFeature |
-|---|---|
-| `ldClient.variation(key, ctx, false)` | `client.getBooleanValue(key, false, ctx)` |
-| `ldClient.variationDetail(key, ctx, def)` | `client.getBooleanDetails(key, def, ctx)` |
-| `useFlags()` | `useFlag(key)` per flag |
-| `useLDClient()` | `useOpenFeatureClient()` |
-| `<LDProvider>` | `<OpenFeatureProvider provider={...}>` |
-| `withLDConsumer()(Component)` | `withOpenFeature()(Component)` |
+Detection is AST-based, not regex: client binding patterns, import aliases, CJS require forms,
+and custom wrappers are all resolved before matching.
 
 ---
 
@@ -249,14 +361,6 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ---
 
-## Free flag debt audit
-
-Running this on a real codebase?
-[Book a free 30-minute audit →](https://flaglint.dev#waitlist)
-I'll run FlagLint on your repo and walk you through the results.
-
----
-
 ## License
 
 MIT — see [LICENSE](./LICENSE).