flaglint 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,7 +5,98 @@ 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
+
+### Fixed
+
+- Detail evaluation methods are classified as manual review and excluded from safe auto-transform counts.
+- Generated LaunchDarkly OpenFeature provider setup now uses the SDK key constructor correctly.
+- Evaluation-context guidance now states that either OpenFeature `targetingKey` or existing LaunchDarkly `key` is accepted.
+- Default one-file flags no longer trigger staleness solely because they occur in one file; explicit `minFileCount: 1` remains available.
+- Reporter output now says `Flags with review signals` instead of implying flags are safe to remove.
+- Public early-preview messaging now states the Node.js server-side migration scope and review/testing requirement.
 
 ## [0.4.0] - 2026-05-24
 

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,18 +21,19 @@
   </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
 
-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
@@ -95,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
@@ -146,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
@@ -195,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`).
@@ -209,10 +228,8 @@ Run `flaglint migrate --dry-run` to review the migration plan.
 | 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 scan` and `flaglint migrate --dry-run` report detected LaunchDarkly Node.js server-side SDK patterns, including manual-review cases.
 `flaglint migrate --apply` rewrites only the ✓ rows above.
 
 ---
@@ -231,15 +248,15 @@ npm install @openfeature/server-sdk \
 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));
+const ldProvider = new LaunchDarklyProvider(process.env.LD_SDK_KEY!);
+await OpenFeature.setProviderAndWait(ldProvider);
 
-// Evaluation context must include targetingKey (or key):
-// { targetingKey: user.id }
+// Evaluation context needs a targeting key.
+// Use OpenFeature `targetingKey` or keep an existing LaunchDarkly `key`:
+// { targetingKey: user.id } or { key: user.id }
 export const openFeatureClient = OpenFeature.getClient();
 ```
 
@@ -248,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:**
@@ -259,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.
 
 ---
 
@@ -278,7 +354,7 @@ Create `.flaglintrc`, `.flaglintrc.json`, or `flaglint.config.json` in your proj
   "include": ["**/*.{ts,tsx,js,jsx}"],
   "exclude": ["**/node_modules/**", "**/dist/**"],
   "provider": "launchdarkly",
-  "minFileCount": 1,
+  "minFileCount": 0,
   "reportTitle": "My Project Flag Report"
 }
 ```
@@ -288,8 +364,9 @@ 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 a staleness candidate if it appears in ≤ N files |
+| `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 |
 
@@ -327,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.
 
 ---
 
@@ -350,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
+};