FlagLint | FlagLint Blog

Feature Flag Technical Debt in TypeScript: Find, Measure, and Clear It

Thu, 25 Jun 2026 00:00:00 GMT

TypeScript’s type system enforces interface contracts and catches argument-type mismatches at compile time — but it cannot see which of your modules still depend on the LaunchDarkly SDK, which of those call sites can be automatically rewritten, or how many engineer-hours the migration backlog represents.

Feature flag technical debt in TypeScript codebases compounds quietly. A team ships a boolean flag behind ldClient.boolVariation, the rollout succeeds, and the code moves on. Six months later the flag is still evaluated on every request. The surrounding code has grown around it. The LaunchDarkly SDK is a locked-in transitive dependency for the entire module that contains it. And no one has a reliable count of how many of these exist, because the only tool most teams reach for is a grep that conflates static flag keys, wrapper functions, and bulk calls into one undifferentiated list.

FlagLint is a free open-source CLI that parses TypeScript source files using an AST scanner to enumerate every LaunchDarkly SDK call site, classify each one by call type and risk, compute a readiness score, and output a migration plan to OpenFeature. No LaunchDarkly API key required.

Why grep misses TypeScript feature flag technical debt

Running grep -r "ldClient" ./src gives you a count. It does not give you a classification. Every result looks equivalent in grep output, but three structurally different situations hide behind the same pattern:

Static flag key, direct call — the flag key is a string literal; the call type is boolVariation, stringVariation, or numberVariation; the return type is known. FlagLint can generate a safe rewrite for this automatically.
Wrapper function with a dynamic key — the function accepts a flagKey parameter and calls the LaunchDarkly SDK internally. FlagLint cannot statically determine which flag is being evaluated, verify the call type, or confirm the return type. This is a high-risk call type.
Detail evaluation or bulk call — boolVariationDetail and allFlagsState have no direct OpenFeature provider equivalent and cannot be safely transformed by a static rewriter.

All three groups require completely different migration approaches — but grep cannot distinguish them.

Run flaglint scan against your source directory to get the AST-based inventory:

npx flaglint scan ./src

Real output from the enterprise checkout service included with FlagLint (5 source files):

- Scanning examples/enterprise-checkout-service/src/...
✓ 19 flag usages found across 11 unique flags (65ms)
ℹ  1 dynamic flag key(s) require manual review
# FlagLint Scan Report

**Scanned:** 5 files in 65ms
**Flag usages:** 19 across 11 unique flags
**Stale candidates:** 0 flags flagged for review

## Flag Inventory
| Flag Key              | Usages | Files | Call Types                                                 | Status   |
|-----------------------|--------|-------|------------------------------------------------------------|----------|
| (dynamic key)         | 7      | 3     | variationDetail, boolVariation, stringVariation, ...       | ✓ Active |
| checkout-experiment   | 1      | 1     | boolVariationDetail                                        | ✓ Active |
| (dynamic key)         | 1      | 1     | allFlagsState                                              | ✓ Active |
| checkout-v2           | 1      | 1     | boolVariation                                              | ✓ Active |
| payment-provider      | 1      | 1     | stringVariation                                            | ✓ Active |
| one-click-checkout    | 1      | 1     | boolVariation                                              | ✓ Active |
| checkout-currency     | 1      | 1     | stringVariation                                            | ✓ Active |
| discount-percentage   | 1      | 1     | numberVariation                                            | ✓ Active |
| max-discount-amount   | 1      | 1     | numberVariation                                            | ✓ Active |
| discount-config       | 1      | 1     | jsonVariation                                              | ✓ Active |
| pricing-tier-config   | 1      | 1     | jsonVariation                                              | ✓ Active |
| recommendations-variant | 1    | 1     | stringVariation                                            | ✓ Active |
| bulk-discount-enabled | 1      | 1     | boolVariation                                              | ✓ Active |

Seven of the nineteen usages resolve to a dynamic flag key. All seven originate from flags-wrapper.ts, which accepts flagKey as a parameter and proxies calls to the LaunchDarkly SDK. Grep would list those seven as equivalent entries alongside the statically-keyed calls in checkout.ts and pricing.ts. The AST scanner surfaces the wrapper boundary.

Measuring the flag debt

flaglint scan gives you the inventory. flaglint audit adds risk classification, a readiness score, and an optional effort estimate in engineer-hours:

npx flaglint audit examples/enterprise-checkout-service/

Real output:

- Auditing examples/enterprise-checkout-service/...
# FlagLint Audit Report

**Files scanned:** 16
**Duration:** 97ms

## Summary

| Total Flags | High Risk | Medium Risk | Total Usages |
|-------------|-----------|-------------|--------------|
| 13          | 3         | 10          | 27           |

| Dynamic Keys | Detail Evals | Bulk Calls | Stale Signals | Safely Automatable | Manual Review |
|--------------|--------------|------------|---------------|--------------------|---------------|
| 7            | 1            | 1          | 0             | 18                 | 9             |

> **Staleness:** No staleness signals detected. Heuristics checked: keyword match
> (flag key contains old/deprecated/legacy/temp/tmp/test/demo), path pattern
> (test/spec/mock files, deprecated/old/legacy directories), and minFileCount threshold.
> Git-history-based staleness (last evaluation date) requires git metadata and is not
> available in a pure static scan.

## Migration Readiness

Migration readiness: **67/100** · moderate

[█████████████████░░░░░░░░] 67%

18 safely automatable  ·  9 require manual review

The readiness score is the fraction of direct LaunchDarkly SDK call sites that FlagLint can rewrite automatically. A score of 67 means 18 of the 27 call sites are safely transformable. The remaining 9 require a human to resolve before an automated pass can run on those files.

The staleness signal column surfaces flag keys whose names carry heuristic staleness signal — keywords like old, deprecated, legacy, or tmp in the flag key itself. Zero here means no staleness signal at the source level. Staleness detection does not require a LaunchDarkly API key or runtime data.

Add --effort-estimate to convert the count into a planning number:

npx flaglint audit ./src --effort-estimate

This appends a three-phase estimate: automatable call sites at approximately 0.25 engineer-hours each, manual review call sites at 1.5–3 hours each, plus 30% overhead for validation and testing. Supplying --hourly-rate 150 appends a dollar range to the summary. The estimate is a planning heuristic calibrated to call-site complexity, not a billing projection.

The three risk tiers in the flag debt inventory

Every flag key in the audit report lands in one of three tiers:

High risk — cannot be automated:

<dynamic key> (7 usages across 3 files) — the flag key is a runtime variable, not a string literal. FlagLint marks every dynamic flag key as high risk because it cannot statically determine which flag is being evaluated, verify the call type, or confirm the return type. The resolution is to trace back to the call sites that supply the key parameter, then extract each unique flag key to a named constant. Re-running flaglint audit after that change will reclassify the previously-dynamic entries as automatable.

checkout-experiment (1 usage) — boolVariationDetail is a detail evaluation call type. OpenFeature has a getBooleanDetails equivalent, but the reason vocabulary differs: the LaunchDarkly SDK returns TARGETING_MATCH and RULE_MATCH; OpenFeature uses its own reason strings. Code that inspects reason.kind or reason.ruleId must be updated by hand alongside the call site.

* (1 usage) — allFlagsState is a bulk call with no OpenFeature provider equivalent. The resolution is to enumerate the specific flag keys the bulk call feeds and replace them with individual named-key calls. If full flag state at application startup is genuinely required, retain the LaunchDarkly SDK client for that bootstrap path while migrating all other call sites.

Medium risk — automatable with review:

discount-config and pricing-tier-config are jsonVariation call types. They are safely automatable, but OpenFeature’s object value API returns unknown. After the rewrite, confirm that any code that casts or destructures the return value still compiles and behaves correctly.

Automatable — safe to transform:

Eight flag keys — checkout-v2, payment-provider, one-click-checkout, checkout-currency, discount-percentage, max-discount-amount, recommendations-variant, and bulk-discount-enabled — are called with boolVariation, stringVariation, or numberVariation using static string literal flag keys. FlagLint can rewrite all of these.

The argument order inversion

The automatable rewrite is not a text substitution. The LaunchDarkly SDK and OpenFeature provider place the fallback value and evaluation context in different argument positions:

// LaunchDarkly SDK — (flagKey, context, fallback)
const enabled = await ldClient.boolVariation("checkout-v2", ctx, false);

// OpenFeature provider — (flagKey, fallback, context)
const enabled = await openFeatureClient.getBooleanValue("checkout-v2", false, ctx);

The flag key is identical. The fallback value and evaluation context swap positions. A naive find-and-replace migration that does not track argument order evaluates every flag with the wrong context on the first request and returns the wrong result silently. FlagLint’s AST rewriter moves all three arguments to the correct positions for each automatable call type.

Preview every transformation before any file is touched:

npx flaglint migrate --dry-run ./src

The dry-run output shows a reviewable diff for each automatable call site alongside the OpenFeature provider setup steps. No files are modified.

Applying the migration plan and enforcing the boundary

Once you have reviewed the dry-run output and set up the OpenFeature provider:

npx flaglint migrate --apply ./src

This applies all safe rewrites in-place. Run your test suite after the apply. Then lock the boundary in CI:

npx flaglint validate --no-direct-launchdarkly ./src

flaglint validate exits non-zero when any direct LaunchDarkly SDK call is detected. Add it to your GitHub Actions workflow and direct LaunchDarkly SDK calls become a build failure from that point forward, blocking regressions as the migration lands across multiple PRs.

Clearing the manual review backlog incrementally

Work through the high-risk items in batches. After each batch, re-run flaglint audit to watch the readiness score climb. At 80 or above, the remaining feature flag technical debt in TypeScript can be handled in a single automated pass — flaglint migrate --apply clears it and flaglint validate --no-direct-launchdarkly confirms the boundary is clean.

The audit plus the CI gate is a closed loop: audit measures what exists, migrate rewrites what is safe, validate blocks regressions, audit confirms progress. You can run the full cycle on a large codebase before writing a single line of migration code. The readiness score tells you up front whether you are looking at a two-sprint effort or a six-month program, and the migration plan tells you exactly which call sites require which kind of attention.

Next steps

LaunchDarkly to OpenFeature Node.js migration guide — the six-step workflow: audit, provider setup, dry-run, apply, validate
Manual review patterns — resolving dynamic flag keys, detail evaluations, and bulk calls before running migrate
flaglint audit CLI reference — all options, output formats (JSON, Markdown, HTML), and exit codes
Migration readiness concept — grade thresholds and the formula behind the readiness score
Enforce in GitHub Actions — CI workflow to block direct LaunchDarkly SDK regressions

Enforcing Your LaunchDarkly to OpenFeature Migration in GitHub Actions

Wed, 24 Jun 2026 00:00:00 GMT

You started your LaunchDarkly to OpenFeature migration three weeks ago. The first sprint went well—five files converted, OpenFeature provider wired in, existing tests green. Then a teammate opened a PR for a new service. Inside it: two fresh ldClient.boolVariation() calls. Not malicious. They just forgot. You merge it anyway because it is not worth blocking the PR over. Two weeks later there are six more.

This is migration drift. It is the most common reason LaunchDarkly to OpenFeature migration projects stall: there is no gate on new direct LaunchDarkly SDK calls landing in main. Without a CI check that fails on any new call site, every PR can quietly add to the flag debt you are actively paying down.

FlagLint addresses this with two commands—audit to measure the existing flag debt and validate to enforce the boundary—and a one-step GitHub Actions integration that adds the gate with two lines of YAML.

Step 1: Baseline your flag debt before you gate

Before you block anything in CI, run flaglint audit against your source directory. This produces a readiness score and a per-flag-key inventory—the snapshot you will measure progress against, and the list you need when deciding what to exclude during the transition period.

npx flaglint audit ./src

Real output from the src/ directory of the enterprise checkout service shipped with FlagLint examples:

- Auditing examples/enterprise-checkout-service/src/...
# FlagLint Audit Report

**Scanned at:** 2026-06-24T03:20:27.050Z
**Scan root:** /home/user/flaglint/examples/enterprise-checkout-service/src
**Files scanned:** 5
**Duration:** 63ms

## Summary

| Total Flags | High Risk | Medium Risk | Total Usages |
|-------------|-----------|-------------|--------------|
| 13 | 3 | 10 | 19 |

| Dynamic Keys | Detail Evals | Bulk Calls | Stale Signals | Safely Automatable | Manual Review |
|--------------|--------------|------------|---------------|-------------------|---------------|
| 7 | 1 | 1 | 0 | 10 | 9 |

## Migration Readiness

Migration readiness: **53/100** · moderate

[█████████████░░░░░░░░░░░░] 53%

10 safely automatable  ·  9 require manual review

## Flag Debt Inventory

| Flag Key | Risk | Usages | Files | Call Types | Reasons |
|----------|------|--------|-------|------------|---------|
| `<dynamic key>` | 🔴 High | 7 | 3 | variationDetail, boolVariation, stringVariation, numberVariation, jsonVariation | dynamic key |
| `checkout-experiment` | 🔴 High | 1 | 1 | boolVariationDetail | detail evaluation |
| `*` | 🔴 High | 1 | 1 | allFlagsState | bulk call |
| `checkout-v2` | 🟢 Automatable | 1 | 1 | boolVariation | safely automatable |
| `payment-provider` | 🟢 Automatable | 1 | 1 | stringVariation | safely automatable |
| `one-click-checkout` | 🟢 Automatable | 1 | 1 | boolVariation | safely automatable |
| `checkout-currency` | 🟢 Automatable | 1 | 1 | stringVariation | safely automatable |
| `discount-percentage` | 🟢 Automatable | 1 | 1 | numberVariation | safely automatable |
| `max-discount-amount` | 🟢 Automatable | 1 | 1 | numberVariation | safely automatable |
| `discount-config` | 🟡 Medium | 1 | 1 | jsonVariation | safely automatable, json variation |
| `pricing-tier-config` | 🟡 Medium | 1 | 1 | jsonVariation | safely automatable, json variation |
| `recommendations-variant` | 🟢 Automatable | 1 | 1 | stringVariation | safely automatable |
| `bulk-discount-enabled` | 🟢 Automatable | 1 | 1 | boolVariation | safely automatable |

✓ Audit complete: 13 flags — 3 high risk, 10 medium risk

Migration readiness: 53/100  ·  moderate
[█████████████░░░░░░░░░░░░] 53%
10 safely automatable  ·  9 require manual review

The readiness score of 53 means 10 of the 19 direct LaunchDarkly SDK call sites can be automatically rewritten by flaglint migrate --apply. The remaining 9 require manual work: 7 use a dynamic flag key (a variable, not a string literal), 1 is a detail evaluation returning reason metadata, and 1 is a bulk allFlagsState call with no single-flag OpenFeature equivalent. The staleness signal count of zero means no flag keys carry source-level stale signal—no keys contain old, deprecated, legacy, or tmp.

Save this output as your progress baseline.

Step 2: Run the validate command locally

flaglint validate --no-direct-launchdarkly exits non-zero when any direct LaunchDarkly SDK call is found in the scanned directory. Before wiring it into CI, run it locally so you know exactly what the gate will report:

npx flaglint validate ./src --no-direct-launchdarkly

Real output from the same src/ directory:

- Scanning examples/enterprise-checkout-service/src/...
✗ validate --no-direct-launchdarkly: 19 direct LaunchDarkly evaluation call(s) found.

  analytics.ts:51:43 — variationDetail("(dynamic key)")
  analytics.ts:76:23 — boolVariationDetail("checkout-experiment")
  analytics.ts:104:22 — allFlagsState(bulk inventory)
  checkout.ts:40:9 — boolVariation("checkout-v2")
  checkout.ts:49:9 — stringVariation("payment-provider")
  checkout.ts:58:9 — boolVariation("one-click-checkout")
  checkout.ts:67:9 — stringVariation("checkout-currency")
  flags-wrapper.ts:48:9 — boolVariation("(dynamic key)")
  flags-wrapper.ts:67:11 — boolVariation("(dynamic key)")
  flags-wrapper.ts:70:11 — stringVariation("(dynamic key)")
  flags-wrapper.ts:73:11 — numberVariation("(dynamic key)")
  flags-wrapper.ts:75:9 — jsonVariation("(dynamic key)")
  pricing.ts:46:9 — numberVariation("discount-percentage")
  pricing.ts:55:9 — numberVariation("max-discount-amount")
  pricing.ts:69:9 — jsonVariation("discount-config")
  pricing.ts:83:9 — jsonVariation("pricing-tier-config")
  product.ts:52:9 — boolVariation("(dynamic key)")
  product.ts:61:9 — stringVariation("recommendations-variant")
  product.ts:70:9 — boolVariation("bulk-discount-enabled")

These files must migrate to OpenFeature before this rule passes.
Run `flaglint migrate --dry-run` to review the migration plan.

Each finding shows file path, line number, column, call type, and flag key. All call types are tracked: boolVariation, stringVariation, numberVariation, jsonVariation, variationDetail, boolVariationDetail, and allFlagsState. Dynamic flag keys appear as (dynamic key).

The gate exits non-zero the moment any direct LaunchDarkly SDK call is detected, blocking any new flag from bypassing the OpenFeature provider. When validate finds zero violations, it exits cleanly:

✓ validate --no-direct-launchdarkly: no direct LaunchDarkly evaluation calls found.

That line is what you are working toward.

Step 3: Add the GitHub Actions gate

FlagLint ships a composite GitHub Actions action. The minimum setup is two lines:

name: FlagLint

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: flaglint/flaglint@main
        with:
          directory: ./src

The action runs flaglint validate ./src --no-direct-launchdarkly and exits 1 when any direct call is found. Do not set continue-on-error: true on the FlagLint step. The job failing is the mechanism—that is what blocks the PR.

Excluding the bootstrap file

Your OpenFeature provider setup module legitimately imports from the LaunchDarkly SDK to instantiate the provider. Exclude it with --bootstrap-exclude so the gate does not fire on it:

- uses: flaglint/flaglint@main
  with:
    directory: ./src
    extra-args: '--bootstrap-exclude "src/provider/setup.ts"'

You can pass multiple exclusion patterns:

extra-args: >-
  --bootstrap-exclude "src/provider/setup.ts"
  --bootstrap-exclude "src/bootstrap/**"

The excluded files can call the LaunchDarkly SDK directly. Everything else cannot. The --bootstrap-exclude flag accepts glob patterns, so a single "src/provider/**" covers a provider directory with multiple files.

Step 4: Add SARIF annotations for inline PR diff visibility

Job-level failure tells engineers something is wrong. SARIF annotations tell them exactly which line is wrong, directly in the PR diff. Add the SARIF upload step alongside the gate:

name: FlagLint Policy

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4

      - name: Validate no direct LaunchDarkly calls
        id: flaglint
        uses: flaglint/flaglint@main
        with:
          directory: ./src
          extra-args: >-
            --bootstrap-exclude "src/provider/setup.ts"
            --format sarif
            --output flaglint-validation.sarif

      - name: Upload validation SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: flaglint-validation.sarif

SARIF findings use rule id flaglint.direct-launchdarkly. With security-events: write, GitHub annotates each violation inline on the relevant PR diff line as a code scanning alert. Set if: always() on the upload step—not on the validate step—so GitHub receives the SARIF file even after the job fails, and annotations appear regardless of whether the PR passes.

Managing the transition period

If your service already has 19 direct LaunchDarkly SDK calls when you add the gate, CI will immediately fail. Two approaches handle the transition:

Start with SARIF-only, then harden. Set continue-on-error: true temporarily on the validate step so violations surface as code scanning alerts without blocking merges. Remove continue-on-error once you have migrated the bulk of existing call sites.

Exclude directories that are mid-migration. Use --bootstrap-exclude patterns to allow files already in the migration queue through the gate while blocking any new file from adding a direct LaunchDarkly SDK call. Remove each exclusion as you migrate that directory.

Re-run the audit after each sprint to track how the readiness score moves. The goal is a validate run that exits cleanly:

✓ validate --no-direct-launchdarkly: no direct LaunchDarkly evaluation calls found.

When that is the consistent CI result, the LaunchDarkly to OpenFeature migration is structurally complete. No new direct call sites can land, and the codebase no longer carries flag debt pointing at the LaunchDarkly SDK.

Next steps

LaunchDarkly to OpenFeature Node.js migration guide — the full end-to-end workflow: audit, provider setup, dry-run, apply, validate
Manual Review Patterns — how to resolve dynamic flag keys, detail evaluations, and bulk calls before migrate --apply can handle them automatically
flaglint audit CLI reference — all options, output formats (JSON, Markdown, HTML), and exit behavior
Migration Readiness concept — how the readiness score is calculated and what the grade thresholds mean
GitHub Actions integration reference — full option table for the composite action, SARIF configuration, and rule id reference

LaunchDarkly Flag Debt: Audit, Estimate, and Prioritize Your Migration

Tue, 23 Jun 2026 00:00:00 GMT

LaunchDarkly flag debt accumulates quietly. A team ships a feature behind a flag, verifies the rollout, and moves on. The flag stays. Six months later it is still being evaluated on every request — carrying the original business logic, an implicit dependency on the LaunchDarkly SDK, and a refactoring cost that compounds with every passing sprint.

At scale, the problem becomes a planning question as much as a technical one. Grepping for ldClient gives you a count, but it misses wrappers, misclassifies risk levels, and gives no indication of how long cleanup will actually take. Before you can schedule the work or make the case to your engineering manager, you need a measurement: how many direct LaunchDarkly SDK calls exist, which ones are safe to automate, and how many engineer-hours does this represent?

FlagLint produces that measurement from static source analysis alone. No LaunchDarkly API key required.

Step 1: Get the flag debt inventory

Run flaglint audit against your source directory:

npx flaglint audit ./src

Real output from the enterprise checkout service shipped with FlagLint (5 source files, run from examples/enterprise-checkout-service/):

- Auditing src/...
# FlagLint Audit Report

**Files scanned:** 5
**Duration:** 64ms

## Summary

| Total Flags | High Risk | Medium Risk | Total Usages |
|-------------|-----------|-------------|--------------|
| 13 | 3 | 10 | 20 |

| Dynamic Keys | Detail Evals | Bulk Calls | Stale Signals | Safely Automatable | Manual Review |
|--------------|--------------|------------|---------------|-------------------|---------------|
| 8 | 1 | 1 | 0 | 10 | 10 |

## Migration Readiness

Migration readiness: **50/100** · moderate

[█████████████░░░░░░░░░░░░] 50%

10 safely automatable  ·  10 require manual review

The readiness score answers the foundational question before any migration begins: what fraction of your direct LaunchDarkly SDK call sites can a tool rewrite automatically? A score of 50 — moderate — means exactly half require a human to review before any automated step runs. A score below 50 is graded complex; 80 or above is ready, meaning the migration can proceed with minimal manual effort.

The stale signals column surfaces flag keys that carry staleness signal — flag keys containing keywords like old, deprecated, legacy, or tmp. Zero here means no flag key names carry obvious staleness signal at the source level. Git-based staleness detection, which checks last-evaluation date against git history, is outside the scope of a static scan.

Step 2: Measure the LaunchDarkly flag debt in engineer-hours

A risk count tells you what you have. It does not tell you what it will cost to fix. Add --effort-estimate to get a directional planning number:

npx flaglint audit ./src --effort-estimate

Real output:

## Estimated Migration Effort

| | Low | High |
|---|---|---|
| Automatable calls (10 calls) | 2.5h | 3.8h |
| Manual review calls (10 calls) | 15h | 30h |
| Validation & testing | 5.3h | 10.1h |
| **Total** | **22.8h** | **43.9h** |

> Estimates are directional planning guides based on call-site complexity. Actual effort
> depends on test coverage, team familiarity, and provider setup. FlagLint does not access
> runtime data or LaunchDarkly billing.

Migration readiness: 50/100  ·  moderate
[█████████████░░░░░░░░░░░░] 50%
10 safely automatable  ·  10 require manual review

Estimated migration effort: 22.8h – 43.9h
Estimates are directional. See the report for assumptions.

The estimate breaks into three phases. Automation covers running flaglint migrate --apply, reviewing the generated diffs, and merging — roughly 0.25 engineer-hours per automatable call site. Manual review is where the range widens: each call site that requires human inspection is estimated at 1.5–3h, because the effort depends on what the surrounding code does with the evaluated value and how complex the flag key resolution is. Validation adds 30% of the combined automation and manual total for test runs, CI, and integration checks.

Supplying --hourly-rate converts the estimate to an engineering cost range:

npx flaglint audit ./src --effort-estimate --hourly-rate 150

This appends Estimated cost: $3,420 – $6,585 to the summary output. It is a planning heuristic calibrated to call-site complexity, not a billing projection.

Step 3: Read the flag debt inventory

The audit report includes a per-flag breakdown. This is where you translate the summary numbers into a concrete migration plan:

| Flag Key              | Risk           | Usages | Call Types                           | Reasons                     |
|-----------------------|----------------|--------|--------------------------------------|-----------------------------|
| `<dynamic key>`       | 🔴 High        | 8      | boolVariation, stringVariation, ...  | dynamic key, wrapper usage  |
| `checkout-experiment` | 🔴 High        | 1      | boolVariationDetail                  | detail evaluation           |
| `*`                   | 🔴 High        | 1      | allFlagsState                        | bulk call                   |
| `checkout-v2`         | 🟢 Automatable | 1      | boolVariation                        | safely automatable          |
| `payment-provider`    | 🟢 Automatable | 1      | stringVariation                      | safely automatable          |
| `discount-config`     | 🟡 Medium      | 1      | jsonVariation                        | safely automatable, json variation |

Three call types drive the high-risk category in this service:

Dynamic flag key (8 usages across 3 files) — the flag key is a variable or template literal rather than a string literal. In this service, flags-wrapper.ts is the source: it accepts flagKey as a parameter and calls the LaunchDarkly SDK internally. FlagLint classifies it as a wrapper and marks every call through it as high risk because it cannot statically determine which flag is being evaluated, verify the call type, or confirm the return type. The resolution is to extract each dynamic key path to a named constant per call site so subsequent flaglint audit runs can classify them as automatable.

Detail evaluation (1 usage) — boolVariationDetail returns an evaluation reason object alongside the flag value. OpenFeature has a getBooleanDetails equivalent, but the reason vocabulary differs from the LaunchDarkly SDK (TARGETING_MATCH vs RULE_MATCH). Code that inspects reason.kind or reason.ruleId must be updated alongside the call site. FlagLint cannot safely generate that transformation.

Bulk call (1 usage) — allFlagsState has no OpenFeature provider equivalent. This call type requires an architecture decision before the migration can proceed: enumerate the specific flag keys needed explicitly, or retain the LaunchDarkly SDK client for the bootstrap path while migrating all other call sites to OpenFeature.

The call-site difference between a high-risk and an automatable entry is visible in source:

// High risk — dynamic flag key, cannot be rewritten automatically
const result = await ldClient.boolVariation(flagKey, ctx, false);

// Automatable — static flag key, safely rewritable
const enabled = await ldClient.boolVariation("checkout-v2", ctx, false);
// becomes:
const enabled = await openFeatureClient.getBooleanValue("checkout-v2", false, ctx);

The only structural difference in the automatable rewrite is argument order: the OpenFeature provider convention places the fallback value at position two and the evaluation context at position three. The flag key is preserved exactly. No flag evaluation logic at LaunchDarkly changes.

Step 4: Generate a shareable HTML report

For teams that need to share the findings with engineering leads or allocate sprint capacity, --format html produces a self-contained file with no external dependencies:

npx flaglint audit ./src --effort-estimate --format html --output flag-debt.html

The file includes the summary card row, the effort estimate table, and the sortable flag debt inventory. It can be attached to a JIRA ticket, linked in a PR description, or opened locally. No LaunchDarkly credentials appear in the output — the report contains only what the static scan detected.

Step 5: Track progress toward zero flag debt

After migrating a batch of call sites, run flaglint validate to confirm the OpenFeature boundary holds:

npx flaglint validate ./src --no-direct-launchdarkly

Real output before migration begins:

✗ validate --no-direct-launchdarkly: 20 direct LaunchDarkly evaluation call(s) found.

  analytics.ts:51:43 — variationDetail("(dynamic key)")
  analytics.ts:76:23 — boolVariationDetail("checkout-experiment")
  analytics.ts:104:22 — allFlagsState(bulk inventory)
  checkout.ts:40:9 — boolVariation("checkout-v2")
  checkout.ts:49:9 — stringVariation("payment-provider")
  checkout.ts:58:9 — boolVariation("one-click-checkout")
  checkout.ts:67:9 — stringVariation("checkout-currency")
  ...

These files must migrate to OpenFeature before this rule passes.
Run `flaglint migrate --dry-run` to review the migration plan.

Add this command to your CI pipeline. flaglint validate --no-direct-launchdarkly exits non-zero when any direct LaunchDarkly SDK call is detected, blocking regressions as the migration lands across multiple PRs. The validate gate is the mechanism that turns a migration plan into a contract.

As you resolve manual-review call sites — extracting dynamic flag keys to named constants, migrating detail evaluations by hand, replacing bulk calls with enumerated evaluations — re-run the audit to watch the readiness score climb. At 80 or above, flaglint migrate --apply can handle the remaining LaunchDarkly flag debt in a single automated pass, and the CI validate gate will confirm the boundary is clean.

Next steps

LaunchDarkly to OpenFeature Node.js migration guide — six-step end-to-end workflow: audit, provider setup, dry-run, apply, validate
Manual Review Patterns — how to resolve dynamic flag keys, detail evaluations, and bulk calls before running migrate
flaglint audit CLI reference — all options, output formats (JSON, Markdown, HTML), and exit behavior
Migration Readiness concept — grade thresholds and the formula behind the readiness score
Enforce in GitHub Actions — ready-made CI workflow to block direct LaunchDarkly regressions

Five LaunchDarkly SDK Patterns That Block Automatic Migration to OpenFeature

Sat, 06 Jun 2026 00:00:00 GMT

Run flaglint migrate ./src --dry-run and you will see two kinds of results: call sites with a generated diff and call sites marked skip — manual review required. The skipped calls are not bugs in the tool. They are patterns where a mechanical rewrite would change runtime behavior in ways the tool cannot prove are safe.

This article covers the five patterns that produce skips and what you need to do for each.

What makes a call automatable

FlagLint rewrites a call automatically only when it can prove three things:

The flag key is a static string literal.
The fallback value type is known (boolean, string, number, or json).
A verified OpenFeature client binding is present in scope.

If any proof fails, the call is left unchanged and flagged for manual review. The conservative stance is intentional: a wrong rewrite is worse than no rewrite.

Pattern 1 — Dynamic flag keys

What it looks like:

// key comes from a variable
const key = user.experimentGroup === 'A' ? 'checkout-v2' : 'checkout-v1';
const enabled = await ldClient.boolVariation(key, ctx, false);

// key comes from a function call
const discount = await ldClient.numberVariation(getFlagKey(user.tier), ctx, 0);

// key is assembled at runtime
const variant = await ldClient.stringVariation(`feature-${region}-rollout`, ctx, 'control');

Why it blocks migration:

OpenFeature’s evaluation methods are structurally identical to LaunchDarkly’s for this case — both take (key, defaultValue, context). But if the key is dynamic, FlagLint cannot know which flag is being evaluated, which means it cannot verify that the OpenFeature provider has that flag configured, cannot determine the correct return type, and cannot guarantee the fallback default is the right type for that specific flag.

How to resolve:

Extract the dynamic selection into an explicit switch or map, then call evaluation with a known static key per branch:

// Before
const discount = await ldClient.numberVariation(getFlagKey(user.tier), ctx, 0);

// After
const FLAG_BY_TIER: Record<string, string> = {
  free: 'discount-free-tier',
  pro: 'discount-pro-tier',
  enterprise: 'discount-enterprise-tier',
};
const flagKey = FLAG_BY_TIER[user.tier] ?? 'discount-free-tier';
const discount = await openFeatureClient.getNumberValue(flagKey, 0, ctx);

Once the key is static in each branch, the surrounding calls become automatable in the next migrate run.

Pattern 2 — Detail evaluations

What it looks like:

const detail = await ldClient.boolVariationDetail('show-banner', ctx, false);
// detail.value — the evaluated value
// detail.reason — WHY it was that value (RULE_MATCH, FALLTHROUGH, etc.)
// detail.variationIndex — index into the flag's variation list

const result = await ldClient.variationDetail('checkout-experiment', ctx, 'control');

Why it blocks migration:

OpenFeature has an equivalent — getBooleanDetails() returns a { value, reason, errorCode } object. But the reason structure is different. LaunchDarkly’s EvaluationReason includes ruleId, ruleIndex, bigSegmentsStatus, and prerequisiteKey. OpenFeature’s ResolutionDetails uses a smaller vocabulary (CACHED, DEFAULT, ERROR, SPLIT, STATIC, TARGETING_MATCH, UNKNOWN).

Code that consumes detail.reason.kind === 'RULE_MATCH' or detail.reason.ruleId will need to be updated alongside the evaluation call. FlagLint cannot safely generate that transformation because the consuming code varies too much.

How to resolve:

Migrate these calls manually. For each variationDetail call:

Replace the evaluation with getBooleanDetails() / getStringDetails() etc.
Update any consumers of reason.kind, reason.ruleId, or variationIndex to use OpenFeature’s reason vocabulary.
Add tests that cover the specific reason codes your business logic depends on.

// Before
const detail = await ldClient.boolVariationDetail('show-banner', ctx, false);
if (detail.reason.kind === 'RULE_MATCH') { track('rule-matched'); }

// After
const detail = await openFeatureClient.getBooleanDetails('show-banner', false, ctx);
if (detail.reason === 'TARGETING_MATCH') { track('rule-matched'); }

Pattern 3 — Bulk state calls

What it looks like:

// Server-side bootstrap — sends all flag values to the client
const allFlags = ldClient.allFlags(ctx);
const state = await ldClient.allFlagsState(ctx);

// Common in SSR: inject all flags into the page for client-side hydration
res.locals.flags = ldClient.allFlags(ctx);

Why it blocks migration:

OpenFeature has no equivalent to allFlags() or allFlagsState(). The OpenFeature specification deliberately does not include bulk evaluation — providers are expected to surface individual flags, and bulk retrieval is a vendor-specific concern.

The LaunchDarkly OpenFeature provider does not expose allFlags through the OpenFeature client interface. If your code relies on bulk evaluation to bootstrap a client-side SDK or build a flag snapshot, that architecture requires rethinking, not just rewriting.

How to resolve:

Option A — Enumerate the flags explicitly. If you know which flags are needed at the injection point, evaluate them individually and bundle the results:

const FLAGS_TO_BOOTSTRAP = ['show-banner', 'checkout-v2', 'new-pricing'] as const;

const flagSnapshot = Object.fromEntries(
  await Promise.all(
    FLAGS_TO_BOOTSTRAP.map(async (key) => [
      key,
      await openFeatureClient.getBooleanValue(key, false, ctx),
    ])
  )
);

Option B — Use the LaunchDarkly provider directly for bootstrapping. The OpenFeature provider wraps the LD Node.js SDK. You can access the underlying client for the specific bootstrap call while migrating all other evaluation calls to OpenFeature:

import { LaunchDarklyProvider } from '@launchdarkly/openfeature-node-server';

const provider = new LaunchDarklyProvider(process.env.LD_SDK_KEY!);
await OpenFeature.setProviderAndWait(provider);

// Access the underlying LD client only for bulk bootstrap
const ldClient = (provider as any).getClient(); // type-cast needed; provider internals are not public API
const allFlags = ldClient.allFlags(ctx);

Option B is a transitional pattern. The goal is to eliminate it once you’ve enumerated the flags that actually need bootstrapping.

Pattern 4 — Configured wrappers

What it looks like:

// A shared evaluation helper used across services
export function isFeatureEnabled(flagKey: string, ctx: LDContext): Promise<boolean> {
  return ldClient.boolVariation(flagKey, ctx, false);
}

// Custom wrapper that adds logging and metrics
export async function evaluateFlag<T>(key: string, ctx: LDContext, fallback: T): Promise<T> {
  const result = await ldClient.variation(key, ctx, fallback);
  metrics.record('flag.evaluation', { key, result });
  return result as T;
}

Why it blocks migration:

FlagLint detects wrappers configured in .flaglintrc under the wrappers key. When a wrapper is detected, the call is surfaced in the audit and scan output but never auto-rewritten — because rewriting the call site does not solve the problem. The wrapper itself contains the direct LD SDK call that needs to change.

How to resolve:

Migrate the wrapper implementation, not the call sites. The call sites stay the same; only the internals of the wrapper change:

// Before
export function isFeatureEnabled(flagKey: string, ctx: LDContext): Promise<boolean> {
  return ldClient.boolVariation(flagKey, ctx, false);
}

// After — wrapper now delegates to OpenFeature
export function isFeatureEnabled(flagKey: string, ctx: EvaluationContext): Promise<boolean> {
  return openFeatureClient.getBooleanValue(flagKey, false, ctx);
}

After the wrapper implementation is migrated, configure FlagLint to recognise the wrapper’s result type so downstream scan output is accurate:

{
  "wrappers": ["isFeatureEnabled", "evaluateFlag"]
}

Wrappers that accept a dynamic flagKey parameter will still appear in reports — that is correct behaviour. The scanner surfaces them for the same reason it surfaces dynamic keys: it cannot prove which flag is being evaluated.

Pattern 5 — Unknown fallback types (`jsonVariation`)

What it looks like:

// Untyped JSON — fallback type is object but the shape is unknown
const config = await ldClient.jsonVariation('pricing-config', ctx, {});

// Typed JSON with a complex or union shape
const rules = await ldClient.jsonVariation('routing-rules', ctx, { routes: [] });

Why it blocks migration:

OpenFeature’s equivalent is getObjectValue(), which returns JsonValue — a union of string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue }. When the fallback is {} or another untyped object, FlagLint cannot determine the correct generic type to use, and it cannot verify that the calling code handles the JsonValue type correctly rather than a narrower application-specific type.

How to resolve:

Add explicit type annotations to the fallback and the result, then migrate manually:

// Define the expected shape
interface PricingConfig {
  basePrice: number;
  currency: string;
  tiers: { name: string; discount: number }[];
}

const DEFAULT_CONFIG: PricingConfig = { basePrice: 0, currency: 'USD', tiers: [] };

// Before
const config = await ldClient.jsonVariation('pricing-config', ctx, DEFAULT_CONFIG);

// After
const config = await openFeatureClient.getObjectValue(
  'pricing-config',
  DEFAULT_CONFIG,
  ctx
) as PricingConfig;

The explicit cast is safe because the provider returns whatever LaunchDarkly sends, and the schema is defined in the LaunchDarkly dashboard. If the shape might not match, add a runtime validator (Zod works well here) at the call site.

Seeing the full breakdown before you start

Before migrating, run flaglint audit ./src to see how many calls fall into each category and why:

✓ Audit complete: 18 flags — 5 high risk, 13 medium risk

| Flag Key              | Risk   | Usages | Reasons                           |
|-----------------------|--------|--------|-----------------------------------|
| <dynamic key>         | High   | 9      | key cannot be resolved statically |
| checkout-experiment   | High   | 1      | detail evaluation                 |
| *                     | High   | 1      | bulk call                         |
| <wrappers>            | High   | 4      | configured wrapper                |
| pricing-config        | Medium | 1      | json — unknown shape              |
| checkout-v2           | Medium | 1      | safely automatable                |

The five patterns above account for every high-risk category. Resolving them one at a time — starting with wrappers, then dynamic keys — progressively reduces the manual review surface until migrate --apply can handle the rest automatically.

After the LaunchDarkly Outage: Adding a Vendor-Neutral Abstraction Without a Full Migration

Fri, 29 May 2026 00:00:00 GMT

A provider outage can expose how deeply application code depends on a single feature-flag SDK. OpenFeature creates a neutral application boundary without forcing teams to abandon LaunchDarkly.

This article walks through the local audit, migration preview, and CI enforcement path that lets teams add that boundary incrementally.

The Vendor Lock-In Problem

Direct SDK calls look like this:

import LaunchDarkly from 'launchdarkly-node-server-sdk';
const ldClient = LaunchDarkly.init(process.env.LD_SDK_KEY);

const enabled = await ldClient.boolVariation('checkout-v2', ctx, false);

Your application code is coupled to LaunchDarkly’s API surface. Switching providers means rewriting every evaluation call.

OpenFeature decouples this. Your application calls the OpenFeature API. The provider (LaunchDarkly, or anything else) is a configuration detail.

The Migration That Stalls

Most teams agree to add OpenFeature. Most migrations take 6+ weeks and nearly break production at least once.

The reasons:

No inventory of where direct SDK calls live
Argument-order differences cause subtle production bugs
Phased migrations partially reverse when new engineers join
No CI enforcement to prevent new direct calls

One of those reasons is an API difference that breaks even careful rewrites — the argument-order trap between LaunchDarkly and OpenFeature →

What FlagLint Does

Before you can migrate, you need to know what you’re migrating.

npx flaglint scan ./src

AST-based inventory of every direct LaunchDarkly SDK call. File, line, call type, flag key, whether it’s safely automatable.

Then:

flaglint migrate ./src --dry-run

Reviewable diffs for safe call sites. Argument order corrected. Dynamic keys, detail methods, and bulk calls reported for manual review.

Then:

flaglint validate ./src --no-direct-launchdarkly

CI gate. Fails the build if any new direct LD call appears. The migration doesn’t rot.

LaunchDarkly Stays As Your Provider

This is not a migration away from LaunchDarkly.

LaunchDarkly offers an official OpenFeature provider. After the migration, LaunchDarkly still evaluates your flags — you’re just calling the OpenFeature API instead of the LaunchDarkly SDK directly.

The difference: if you need to switch providers, you change the provider configuration. Your application code doesn’t change.

→ Start with the scan
→ GitHub

Why LaunchDarkly → OpenFeature Migrations Break in Production

Fri, 29 May 2026 00:00:00 GMT

LaunchDarkly and OpenFeature both evaluate flags with three arguments, but the fallback and context positions are reversed. A naive codemod can produce valid-looking code that silently changes runtime behavior.

This article shows the argument-order trap and why FlagLint uses AST analysis before rewriting any call site.

The Agreement That Takes 30 Minutes

Teams agree on OpenFeature quickly. It makes sense — vendor-neutral, CNCF-backed, clean abstraction. The decision is easy.

The migration is not.

Halfway through, most teams hit a bug that looks like this in production: a subset of users sees the wrong feature state. The flag evaluation is returning unexpected values. Everything looked correct in code review.

The cause is almost always the same thing.

The Argument-Order Trap

LaunchDarkly and OpenFeature share method names but differ in argument order:

// LaunchDarkly
ldClient.boolVariation(flagKey, context, fallback)

// OpenFeature
openFeatureClient.getBooleanValue(flagKey, fallback, context)

context and fallback are swapped.

A search-and-replace migration silently puts context where fallback should be, and fallback where context should be — across every call site in your codebase.

In production: users in your evaluation context see the fallback value. In code review: the signature looks correct because the argument count matches. In the post-mortem: nobody can identify when it was introduced.

Why Grep Misses It

The typical manual approach:

Search for launchdarkly-node-server-sdk imports
Find all ldClient references
Search-and-replace method names

This finds the calls. It does not understand argument semantics.

A grep-based migration will correctly rename boolVariation to getBooleanValue and miss the argument order entirely. The test suite often misses it too because the values are both valid types — context and fallback are both objects.

What AST Analysis Catches

Abstract Syntax Tree (AST) analysis parses your code the same way a compiler does. It doesn’t match text — it understands structure.

For a call like:

const result = await ldClient.boolVariation('checkout-v2', ctx, false);

AST analysis identifies:

The import binding (ldClient → launchdarkly-node-server-sdk)
The method name (boolVariation)
The argument at position 0: flag key ('checkout-v2' — string literal)
The argument at position 1: context (ctx — object reference)
The argument at position 2: fallback (false — boolean literal)

When generating the OpenFeature equivalent, it knows to produce:

const result = await openFeatureClient.getBooleanValue('checkout-v2', false, ctx);

Argument 2 goes to position 1. Argument 1 goes to position 2. Argument order corrected. Type preserved. Await preserved.

When AST Analysis Refuses to Rewrite

Not every call can be safely automated. FlagLint identifies these and routes them to manual review instead of silently rewriting them:

Dynamic flag keys:

const flagKey = `feature-${featureName}`;
await ldClient.boolVariation(flagKey, ctx, false);

The key is not statically knowable. Automated rewrite could produce incorrect OpenFeature client binding.

Detail methods:

await ldClient.boolVariationDetail('checkout-v2', ctx, false);

boolVariationDetail returns metadata not directly equivalent in OpenFeature. Requires a different migration pattern.

Bulk state calls:

await ldClient.allFlagsState(ctx);

No direct OpenFeature equivalent. Architecture decision required.

For all of these, FlagLint reports the location and reason — it never silently rewrites them.

The CI Gate

Generating diffs is only half the problem. Migration rot is the other half.

After a phased migration, new engineers joining the codebase don’t know the rule. They reach for ldClient because that’s what they know. Six months later, you have new direct LD calls and the migration has partially reversed.

flaglint validate --no-direct-launchdarkly exits 1 if any direct LaunchDarkly evaluation call appears outside the bootstrap file.

Add it to your GitHub Actions workflow:

- name: Enforce OpenFeature boundary
  run: npx flaglint@latest validate ./src --no-direct-launchdarkly

Any new ldClient.boolVariation() call fails the build. The boundary holds.

Try It Now

npx flaglint audit ./src

Runs locally, no SDK key needed, nothing changes. Gives you a risk-ranked inventory of every direct LaunchDarkly SDK call in your codebase — dynamic keys, detail methods, and bulk state calls included — with a migration readiness score.

npx flaglint migrate ./src --dry-run

Shows the before/after diff for every safely automatable call site. Dynamic keys and detail methods are reported separately for manual review.

FlagLint is free, open source, MIT licensed.

→ GitHub
→ npm
→ Quickstart

FlagLint | FlagLint Blog

Feature Flag Technical Debt in TypeScript: Find, Measure, and Clear It

Why grep misses TypeScript feature flag technical debt

Measuring the flag debt

The three risk tiers in the flag debt inventory

The argument order inversion

Applying the migration plan and enforcing the boundary

Clearing the manual review backlog incrementally

Next steps

Enforcing Your LaunchDarkly to OpenFeature Migration in GitHub Actions

Step 1: Baseline your flag debt before you gate

Step 2: Run the validate command locally

Step 3: Add the GitHub Actions gate

Excluding the bootstrap file

Step 4: Add SARIF annotations for inline PR diff visibility

Managing the transition period

Next steps

LaunchDarkly Flag Debt: Audit, Estimate, and Prioritize Your Migration

Step 1: Get the flag debt inventory

Step 2: Measure the LaunchDarkly flag debt in engineer-hours

Step 3: Read the flag debt inventory

Step 4: Generate a shareable HTML report

Step 5: Track progress toward zero flag debt

Next steps

Five LaunchDarkly SDK Patterns That Block Automatic Migration to OpenFeature

What makes a call automatable

Pattern 1 — Dynamic flag keys

Pattern 2 — Detail evaluations

Pattern 3 — Bulk state calls

Pattern 4 — Configured wrappers

Pattern 5 — Unknown fallback types (jsonVariation)

Seeing the full breakdown before you start

After the LaunchDarkly Outage: Adding a Vendor-Neutral Abstraction Without a Full Migration

The Vendor Lock-In Problem

The Migration That Stalls

What FlagLint Does

LaunchDarkly Stays As Your Provider

Why LaunchDarkly → OpenFeature Migrations Break in Production

The Agreement That Takes 30 Minutes

The Argument-Order Trap

Why Grep Misses It

What AST Analysis Catches

When AST Analysis Refuses to Rewrite

The CI Gate

Try It Now

Pattern 5 — Unknown fallback types (`jsonVariation`)