flaglint 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -5,7 +5,49 @@ 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.2.2] - 2026-05-23
+## [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
+
+- **SARIF output**: `flaglint scan --format sarif --output flaglint.sarif` now emits SARIF 2.1.0 for GitHub Code Scanning / PR annotations.
+- **Persistent scan metadata**: `ScanResult` now includes `scannedAt` and `scanRoot`, giving JSON/SARIF/HTML reports a stable scan timestamp and source-root context.
 
 ### Fixed
 
@@ -13,6 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Typed scan warnings**: `ScanResult.warnings` is now a typed `ScanWarning` union (`read-failure` | `parse-failure`) instead of opaque strings, preserving structured data at the domain boundary.
 - **StalenessEvaluator wired**: The `StalenessEvaluator` interface now has a call site in `scan()` — pass an `evaluator` to inject API-based staleness signals without touching core scanner logic.
 - **ScanConfig boundary**: `scan()` now accepts `ScanConfig` (scan-relevant fields only) rather than the full `FlagLintConfig`, decoupling the scanner from CLI output concerns (`reportTitle`, `outputDir`).
+- **Report count consistency**: Markdown and HTML stale candidate counts now exclude wildcard (`*`) usages, matching the CLI summary.
 
 ## [0.2.1] - 2026-05-23
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Find stale feature flags. Detect flag debt. Plan your OpenFeature migration.</strong>
+  <strong>LaunchDarkly Node.js server SDK -> OpenFeature migration</strong>
 </p>
 
 <p align="center">
@@ -21,29 +21,68 @@
   </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 stale feature flags. Detect flag debt. Plan your OpenFeature migration.**
+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.
 
-[![CI](https://github.com/flaglint/flaglint/actions/workflows/ci.yml/badge.svg)](https://github.com/flaglint/flaglint/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/flaglint.svg)](https://www.npmjs.com/package/flaglint)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+**LaunchDarkly remains your provider. OpenFeature becomes the evaluation API your application code calls.**
 
 ---
 
-## The problem
+## Workflow
 
-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.
-
-**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)
+ℹ  1 dynamic flag key(s) require manual review
+```
+
+Markdown report excerpt:
+
+```markdown
+## Flag Inventory
+| 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 staleness signals:
+
+```json
+{
+  "flagKey": "checkout-v2",
+  "isDynamic": false,
+  "file": "src/services/checkout.ts",
+  "line": 14,
+  "callType": "boolVariation",
+  "stalenessSignals": []
+}
 ```
 
 ---
@@ -62,21 +101,24 @@ 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
 flaglint scan --format json --output report.json
 flaglint scan --format html --output report.html
+flaglint scan --format sarif --output flaglint.sarif
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--format` | `markdown` | Output format: `json`, `markdown`, `html` |
+| `--format` | `markdown` | Output format: `json`, `markdown`, `html`, `sarif` |
 | `--output` | stdout | Write report to file |
-| `--config` | auto-detect | Path to `.flaglintrc` |
+| `--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.
 
 ---
 
@@ -85,22 +127,151 @@ 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 |
-| `--config` | auto-detect | Path to `.flaglintrc` |
+| `--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
 
-Create `.flaglintrc` in your project root:
+Create `.flaglintrc`, `.flaglintrc.json`, or `flaglint.config.json` in your project root:
 
 ```json
 {
@@ -117,49 +288,70 @@ Create `.flaglintrc` in your project root:
 | `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 |
 
-FlagLint searches for config in this order: `--config` flag → `.flaglintrc` → `.flaglintrc.json` → `flaglint.config.json`.
+FlagLint searches for config in this order: `--config` path → `.flaglintrc` → `.flaglintrc.json` → `flaglint.config.json`.
 
 ---
 
 ## CI Integration
 
+### 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
 ```
 
----
-
-## What FlagLint detects
+### Full migration CI pipeline with SARIF annotations
 
-- `ldClient.variation()` and `ldClient.variationDetail()`
-- `ldClient.allFlags()`
-- `useFlags()`, `useLDClient()` React hooks
-- `<LDProvider>` and `withLDConsumer()` patterns
-- Dynamic flag keys (runtime-determined, flagged for manual review)
+```yaml
+name: FlagLint
+on: [pull_request]
+
+jobs:
+  flaglint:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - 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
+
+      - 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 a **stale heuristic** based on key names and file locations.
+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.
 
 ---