@flagshark/core 2.2.1 → 2.3.0

package/dist/providers/cross-reference.js

@@ -1,30 +1,61 @@
 /**
- * Pure function: joins detected flag keys against a platform's flag list,
- * emits PlatformSignals based on the platform's view of each flag.
+ * Render an env attribution suffix for a multi-env signal description.
  *
- * Signal precedence (most-specific wins; only one primary signal per flag):
- *   1. missing-in-platform   — flag not in platform at all (error)
- *   2. archived-in-platform  — flag archived (warning)
- *   3. platform-launched     — LD says single variation for 7+ days (error)
- *   4. platform-inactive     — LD says no eval events for 7+ days (warning)
- *   5. platform-permanent    — user marked permanent (control signal)
- *   6. platform-too-old      — created > thresholdDays ago (warning)
+ *   fmtEnvs(['production'], ['production', 'staging'])  // 'in production'
+ *   fmtEnvs(['production', 'staging'], ['production', 'staging'])  // 'everywhere'
  *
- * Permanent + too-old can coexist; permanent + inactive can coexist;
- * permanent is the strongest CONTROL signal (it suppresses code-side
- * heuristics) but doesn't displace platform-side activity signals.
+ * Order of envs in the output follows the order of `all` (i.e. the
+ * config-declared order, since that's the order the orchestrator builds
+ * the inner perEnv map in).
+ */
+function fmtEnvs(triggered, all) {
+    // Both empty would render 'everywhere' without the second guard, which
+    // is semantically wrong. Current call sites all gate on triggered.length > 0
+    // before invoking; the guard is defensive insurance for future callers.
+    if (triggered.length === all.length && triggered.length > 0)
+        return 'everywhere';
+    const ordered = all.filter((e) => triggered.includes(e));
+    return `in ${ordered.join(', ')}`;
+}
+/**
+ * Pure function: joins detected flag keys against per-env platform flag data,
+ * emits PlatformSignals based on each platform's view of each flag.
+ *
+ * Two early-exit signals are sole signals when they fire:
+ *   - missing-in-platform   — flag absent from EVERY env (error)
+ *   - archived-in-platform  — flag archived in the platform (warning)
+ *
+ * All other signals stack — a single flag can carry several at once:
+ *   - platform-permanent          — user marked the flag permanent (info,
+ *                                   control signal; filtered from user output)
+ *   - platform-too-old            — created > thresholdDays ago (warning)
+ *   - platform-launched           — at least one env reports the flag as
+ *                                   served-single-variation for 7+ days (error)
+ *   - platform-inactive           — at least one env reports no evaluations in
+ *                                   7+ days, AND no env is platform-launched
+ *                                   (warning)
+ *   - platform-zero-evaluations   — at least one env has 0 evaluations over
+ *                                   the 30-day window (error)
+ *   - platform-low-evaluations    — at least one env is below the threshold,
+ *                                   AND no env is at zero (warning)
+ *   - platform-untouched-stale    — EVERY env's audit log confirmed zero
+ *                                   activity within the window (warning, the
+ *                                   one strict-all-envs rule)
+ *
+ * For multi-env scans, signal descriptions carry env attribution
+ * ('everywhere' when all envs agree, 'in env1, env2' otherwise) via the
+ * fmtEnvs helper above.
  *
  * Does NOT surface platform flags with no code reference — that's a separate
  * "orphan platform flags" feature, out of scope.
  */
-export function crossReference(detectedFlags, platformFlags, platformDisplayName, options = {}) {
-    const platformByKey = new Map(platformFlags.map((f) => [f.key, f]));
+export function crossReference(detectedFlags, platformFlagsByEnv, platformDisplayName, options = {}) {
     const out = new Map();
     const now = Date.now();
     const thresholdMs = options.thresholdDays != null ? options.thresholdDays * 86_400_000 : null;
     for (const key of detectedFlags.keys()) {
-        const platform = platformByKey.get(key);
-        if (!platform) {
+        const envMap = platformFlagsByEnv.get(key);
+        if (!envMap || envMap.size === 0) {
             out.set(key, [
                 {
                     type: 'missing-in-platform',
@@ -34,7 +65,11 @@ export function crossReference(detectedFlags, platformFlags, platformDisplayName
             ]);
             continue;
         }
-        if (platform.archived) {
+        // Flag-level fields (archived, permanent, tags, maintainer, createdAt)
+        // are identical across envs in LD's data model. Read them from the
+        // first env's entry.
+        const firstEntry = envMap.values().next().value;
+        if (firstEntry.archived) {
             out.set(key, [
                 {
                     type: 'archived-in-platform',
@@ -44,24 +79,35 @@ export function crossReference(detectedFlags, platformFlags, platformDisplayName
             ]);
             continue;
         }
-        // Stack-able signals: platform-permanent (control), platform-too-old,
-        // platform-inactive/launched. A single flag can carry multiple.
         const signals = [];
-        if (platform.status === 'launched') {
+        const allEnvs = Array.from(envMap.keys());
+        // platform-launched: fire-on-any with env attribution. Inactive is
+        // handled in a separate block below so we can suppress it when any
+        // env is launched (they're contradictory states).
+        const launchedEnvs = allEnvs.filter((e) => envMap.get(e).status === 'launched');
+        if (launchedEnvs.length > 0) {
+            const where = fmtEnvs(launchedEnvs, allEnvs);
             signals.push({
                 type: 'platform-launched',
                 severity: 'error',
-                description: `${platformDisplayName} reports this flag has served one variation for 7+ days — likely ready for removal`,
+                description: `${platformDisplayName} reports this flag has served one variation for 7+ days ${where} — likely ready for removal`,
             });
         }
-        else if (platform.status === 'inactive') {
-            signals.push({
-                type: 'platform-inactive',
-                severity: 'warning',
-                description: `no evaluations recorded in ${platformDisplayName} in the last 7+ days`,
-            });
+        // platform-inactive: fire-on-any-env, BUT suppress when any env is
+        // launched (they're contradictory; launched is the more severe
+        // and more actionable signal).
+        if (launchedEnvs.length === 0) {
+            const inactiveEnvs = allEnvs.filter((e) => envMap.get(e).status === 'inactive');
+            if (inactiveEnvs.length > 0) {
+                const where = fmtEnvs(inactiveEnvs, allEnvs);
+                signals.push({
+                    type: 'platform-inactive',
+                    severity: 'warning',
+                    description: `no evaluations recorded in ${platformDisplayName} ${where} in the last 7+ days`,
+                });
+            }
         }
-        if (platform.permanent) {
+        if (firstEntry.permanent) {
             // Control signal: tells staleness.ts to suppress age + low-usage
             // signals. Filtered out of the user-facing StaleFlag.signals array
             // before display. Kill-switches and other intentionally permanent
@@ -77,11 +123,11 @@ export function crossReference(detectedFlags, platformFlags, platformDisplayName
         // exposed a createdAt timestamp. Permanent flags suppress this too —
         // the user explicitly chose to keep a long-lived flag, so don't
         // contradict them with a too-old warning.
-        if (!platform.permanent &&
+        if (!firstEntry.permanent &&
             thresholdMs != null &&
-            platform.createdAt &&
-            now - platform.createdAt.getTime() > thresholdMs) {
-            const ageDays = Math.floor((now - platform.createdAt.getTime()) / 86_400_000);
+            firstEntry.createdAt &&
+            now - firstEntry.createdAt.getTime() > thresholdMs) {
+            const ageDays = Math.floor((now - firstEntry.createdAt.getTime()) / 86_400_000);
             signals.push({
                 type: 'platform-too-old',
                 severity: 'warning',
@@ -97,38 +143,106 @@ export function crossReference(detectedFlags, platformFlags, platformDisplayName
         // `undefined` means the feature isn't available for this account
         // (tier-gated / endpoint 404'd); `null` means available but no
         // window data yet. Both fall through to no signal.
-        if (!platform.permanent && typeof platform.evaluations30d === 'number') {
-            if (platform.evaluations30d === 0) {
+        //
+        // platform-zero-evaluations: fire-on-any with env attribution.
+        // platform-low-evaluations: fire-on-any with env attribution, BUT
+        // suppress when any env reports zero (zero is the stronger signal;
+        // emitting both creates noise without adding information).
+        if (!firstEntry.permanent) {
+            const zeroEnvs = [];
+            const lowByEnv = [];
+            const threshold = options.evaluationThreshold ?? 10;
+            for (const env of allEnvs) {
+                const evals = envMap.get(env).evaluations30d;
+                if (typeof evals !== 'number')
+                    continue;
+                if (evals === 0) {
+                    zeroEnvs.push(env);
+                }
+                else if (evals < threshold) {
+                    lowByEnv.push({ env, count: evals });
+                }
+            }
+            if (zeroEnvs.length > 0) {
+                const where = fmtEnvs(zeroEnvs, allEnvs);
                 signals.push({
                     type: 'platform-zero-evaluations',
                     severity: 'error',
-                    description: `0 evaluations in ${platformDisplayName} over the last 30 days — code path is unused`,
+                    description: `${platformDisplayName} reports 0 evaluations ${where} over the last 30 days — code path is unused`,
                 });
             }
-            else {
-                const threshold = options.evaluationThreshold ?? 10;
-                if (platform.evaluations30d < threshold) {
-                    signals.push({
-                        type: 'platform-low-evaluations',
-                        severity: 'warning',
-                        description: `only ${platform.evaluations30d} evaluation${platform.evaluations30d === 1 ? '' : 's'} in ${platformDisplayName} over the last 30 days (below threshold ${threshold})`,
-                    });
-                }
+            else if (lowByEnv.length > 0) {
+                // Pick the env with the LOWEST count for the canonical
+                // description; render the env list when multiple envs are low.
+                const lowEnvs = lowByEnv.map((e) => e.env);
+                const lowest = lowByEnv.reduce((a, b) => (a.count <= b.count ? a : b));
+                const where = fmtEnvs(lowEnvs, allEnvs);
+                // When multiple envs are low with different counts, "only N" is
+                // ambiguous (reads as 'each env has N'). "as few as N" makes the
+                // minimum-across-envs framing explicit. With one low env, "only N"
+                // is the right phrasing — exactly N evaluations in exactly that env.
+                const countPhrase = lowByEnv.length > 1
+                    ? `as few as ${lowest.count}`
+                    : `only ${lowest.count}`;
+                signals.push({
+                    type: 'platform-low-evaluations',
+                    severity: 'warning',
+                    description: `${platformDisplayName} reports ${countPhrase} evaluation${lowest.count === 1 ? '' : 's'} ${where} over the last 30 days (below threshold ${threshold})`,
+                });
             }
         }
-        // platform-untouched-stale: the audit log confirmed no activity
-        // (toggles, edits, targeting changes) for this flag within the
-        // platform's lookback window. Unlike most signals, this is NOT
-        // suppressed for permanent flags — a kill switch untouched for
-        // 3 years should still get a periodic review even if the user
-        // intends to keep it permanent.
-        if (platform.lastTouched === null) {
+        // platform-untouched-stale: STRICT all-envs rule.
+        // Untouched only counts if EVERY env's audit log was successfully
+        // fetched AND showed zero activity (lastTouched === null exactly —
+        // not undefined, which means the fetch couldn't confirm). A flag
+        // toggled in staging counts as touched; a flag whose staging audit
+        // log we couldn't read is "unknown", not "untouched".
+        //
+        // Unlike most signals, this is NOT suppressed for permanent flags —
+        // a kill switch untouched for 3 years should still get a periodic
+        // review even if the user intends to keep it permanent.
+        const allUntouched = allEnvs.length > 0
+            && allEnvs.every((e) => envMap.get(e).lastTouched === null);
+        if (allUntouched) {
+            // TODO: '90+ days' is hardcoded to AUDIT_LOG_WINDOW_DAYS in the LD
+            // client (packages/core/src/providers/launchdarkly/client.ts). If
+            // the window becomes a config knob, plumb the actual value through
+            // here so the description doesn't lie.
             signals.push({
                 type: 'platform-untouched-stale',
                 severity: 'warning',
-                description: `no activity in ${platformDisplayName} for 90+ days (audit log)`,
+                description: `no activity in ${platformDisplayName} ${fmtEnvs(allEnvs, allEnvs)} for 90+ days (audit log)`,
             });
         }
+        // coverage-gap-vs-platform: LD's code-refs feature reports more
+        // references for this flag than FlagShark detected. The delta is
+        // detector blind spots — code patterns LD recognizes that our
+        // language detectors missed. Info severity: doesn't make the flag
+        // stale, just surfaces a detection-quality issue for triage.
+        //
+        // Fires only LD-says-more. Reverse direction (FlagShark finds more)
+        // is expected: LD's ld-find-code-refs CLI excludes test files,
+        // node_modules, etc. by default — FlagShark scans them.
+        //
+        // Three states of codeReferences (read from firstEntry — the field
+        // is flag-level, identical across envs in LD's data model):
+        //   - undefined → feature unavailable, no signal
+        //   - null      → LD says 0 (no gap possible — FlagShark count is ≥ 0)
+        //   - { count } → compare count vs FlagShark's detection count
+        if (firstEntry.codeReferences && firstEntry.codeReferences.count > 0) {
+            /* v8 ignore next — ?? 0 fallback not exercised by current fixtures */
+            const detected = detectedFlags.get(key)?.length ?? 0;
+            if (firstEntry.codeReferences.count > detected) {
+                const gap = firstEntry.codeReferences.count - detected;
+                const platCount = firstEntry.codeReferences.count;
+                signals.push({
+                    type: 'coverage-gap-vs-platform',
+                    severity: 'info',
+                    description: `${platformDisplayName} detected ${platCount} reference${platCount === 1 ? '' : 's'} ` +
+                        `for this flag; FlagShark detected ${detected} (gap: ${gap})`,
+                });
+            }
+        }
         if (signals.length > 0) {
             out.set(key, signals);
         }

package/dist/providers/cross-reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"cross-reference.js","sourceRoot":"","sources":["../../src/providers/cross-reference.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cross-reference.js","sourceRoot":"","sources":["../../src/providers/cross-reference.ts"],"names":[],"mappings":"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"}

package/dist/providers/index.d.ts

@@ -1,5 +1,7 @@
 export type { PlatformFlag, PlatformClient, PlatformDefinition, PlatformSignal, } from './interface.js';
 export { platformRegistry, findPlatform } from './registry.js';
 export { crossReference, mergePlatformSignals } from './cross-reference.js';
+export type { PerEnvFlags } from './cross-reference.js';
+export type { PerFlagEnvironmentData } from './orchestrate.js';
 export { computeCacheKey, readCache, writeCache, loadPlatformFlagsCached, type CacheOptions, } from './cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EACL,eAAe,EACf,SAAS,EACT,UAAU,EACV,uBAAuB,EACvB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,cAAc,GACf,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EACL,eAAe,EACf,SAAS,EACT,UAAU,EACV,uBAAuB,EACvB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAA"}

package/dist/providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EACL,eAAe,EACf,SAAS,EACT,UAAU,EACV,uBAAuB,GAExB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAG3E,OAAO,EACL,eAAe,EACf,SAAS,EACT,UAAU,EACV,uBAAuB,GAExB,MAAM,YAAY,CAAA"}

package/dist/providers/interface.d.ts

@@ -1,4 +1,18 @@
-import type { ZodType } from 'zod';
+import type { ZodType, ZodTypeDef } from 'zod';
+import type { ScanLogger } from '../scan-repo.js';
+/**
+ * One variation definition on a flag. The `value` is the runtime value
+ * the variation serves (boolean, string, number, JSON object — anything
+ * the SDK supports). The `name` is the user-defined label shown in the
+ * LD UI ("on", "off", "treatment", etc.).
+ *
+ * Cleanup pipelines look up the substitute value by index — see
+ * PlatformFlag.fallthroughVariation and offVariation.
+ */
+export type FlagVariation = {
+    value: unknown;
+    name?: string;
+};
 /** A flag entry as reported by a flag-management platform's API. */
 export interface PlatformFlag {
     key: string;
@@ -112,6 +126,73 @@ export interface PlatformFlag {
      * surfacing.
      */
     lastTouched?: Date | null;
+    /**
+     * Variation definitions for this flag — flag-level (identical across envs
+     * in LD's data model). Indexed by the same integer the per-env
+     * `fallthroughVariation` and `offVariation` fields point at. SaaS-side
+     * cleanup pipelines look up the substitute value via these indices
+     * instead of guessing from code-side default arguments.
+     *
+     * Undefined when the platform doesn't expose variation data (other
+     * providers without an equivalent concept) or when the flag-list
+     * response unexpectedly omits the field.
+     */
+    variations?: FlagVariation[];
+    /**
+     * Whether the flag is enabled in the configured env. When false, LD
+     * serves `offVariation` regardless of fallthrough/targeting rules.
+     * Per-env field — the LD client populates this from the configured env's
+     * data on each per-env fetch the orchestrator runs.
+     *
+     * Undefined when envData itself is absent (archived flags or unexpected
+     * API responses).
+     */
+    on?: boolean;
+    /**
+     * Variation index served by fallthrough when no targeting/rule matches
+     * AND `on: true`.
+     *   - number → 100% rollout to that variation
+     *   - null   → split rollout (`fallthrough.rollout` shape) or fallthrough
+     *              absent. **Preserve null literally in output** — SaaS uses
+     *              it to detect "can't substitute" and fail closed.
+     *
+     * Non-optional: the LD client's `?? null` normalization guarantees this
+     * field is always set (either a number or null) on every returned flag.
+     */
+    fallthroughVariation: number | null;
+    /**
+     * Variation index served when `on: false`. Required by LD on every
+     * active flag (LD's API rejects flag creation without it). Undefined
+     * when the platform omits the field (archived flags or unexpected API
+     * responses).
+     */
+    offVariation?: number;
+    /**
+     * Cross-check data from LaunchDarkly's own code-references feature.
+     * LD's `ld-find-code-refs` CLI scans repos and reports how many code
+     * references exist for each flag. FlagShark cross-checks LD's count
+     * against its own detection count to surface detector blind spots —
+     * flags LD found 12 references for but FlagShark only found 8 indicate
+     * 4 hunks our patterns missed.
+     *
+     * Three-state (matches the evaluations30d convention):
+     *   - undefined → feature not available (tier-gated, not configured for
+     *                 this project, or the aux fetch errored). No signal
+     *                 emitted; the LD client logs a single advisory per scan.
+     *   - null      → feature available; LD has zero references for this
+     *                 flag. No signal — zero refs cannot be a "gap"; FlagShark's
+     *                 detection count is necessarily ≥ 0.
+     *   - { count } → LD found `count` references for this flag (sum of
+     *                 hunkCount across all repos LD scanned).
+     *
+     * Used by cross-reference to emit `coverage-gap-vs-platform` when
+     * count > FlagShark's detection count. LD-says-more direction only —
+     * reverse direction is expected: FlagShark scans test files that
+     * ld-find-code-refs excludes by default.
+     */
+    codeReferences?: {
+        count: number;
+    } | null;
 }
 /** Runtime client for a configured platform. Returned by PlatformDefinition.createClient. */
 export interface PlatformClient {
@@ -121,6 +202,7 @@ export interface PlatformClient {
     displayName: string;
     listFlags(opts?: {
         signal?: AbortSignal;
+        logger?: ScanLogger;
     }): Promise<PlatformFlag[]>;
 }
 /** Registry entry. Each platform implementation exports exactly one of these. */
@@ -131,7 +213,7 @@ export interface PlatformDefinition<TConfig = unknown> {
     /** Env var read for the secret token. User can override via token_env. */
     defaultTokenEnv: string;
     /** Zod schema validating this platform's config block. */
-    configSchema: ZodType<TConfig>;
+    configSchema: ZodType<TConfig, ZodTypeDef, unknown>;
     /** Factory — validated config + resolved token → runtime client. No IO until listFlags() is called. */
     createClient: (config: TConfig, token: string) => PlatformClient;
 }
@@ -165,8 +247,14 @@ export interface PlatformSignal {
      *   because it's based on actual usage, not heuristics.
      * - `platform-low-evaluations` (warning): evaluations below the
      *   configured threshold over the window. Default threshold: 10/30d.
+     * - `coverage-gap-vs-platform` (info): LD's own code-refs feature reports
+     *   more references for this flag than FlagShark detected. Surfaces detector
+     *   blind spots — code patterns LD recognizes that our language detectors
+     *   missed. Doesn't make the flag stale; informational only. Fires only
+     *   when LD count > FlagShark count; reverse direction (FlagShark counts
+     *   more) is expected for projects that test-file-exclude in LD.
      */
-    type: 'missing-in-platform' | 'archived-in-platform' | 'platform-permanent' | 'platform-too-old' | 'platform-inactive' | 'platform-launched' | 'platform-zero-evaluations' | 'platform-low-evaluations' | 'platform-untouched-stale';
+    type: 'missing-in-platform' | 'archived-in-platform' | 'platform-permanent' | 'platform-too-old' | 'platform-inactive' | 'platform-launched' | 'platform-zero-evaluations' | 'platform-low-evaluations' | 'platform-untouched-stale' | 'coverage-gap-vs-platform';
     severity: 'error' | 'warning' | 'info';
     description: string;
 }

package/dist/providers/interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/providers/interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAElC,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IACjB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAA;IACzB;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IAEvB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IAEf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAA;IAEnD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IAE3B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAE9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;CAC1B;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;CACpE;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,OAAO;IACnD,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAA;IACvB,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IAC9B,uGAAuG;IACvG,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,cAAc,CAAA;CACjE;AAED,gGAAgG;AAChG,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,IAAI,EACA,qBAAqB,GACrB,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,mBAAmB,GACnB,mBAAmB,GACnB,2BAA2B,GAC3B,0BAA0B,GAC1B,0BAA0B,CAAA;IAC9B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IACtC,WAAW,EAAE,MAAM,CAAA;CACpB"}
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/providers/interface.ts"],"names":[],"mappings":"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"}

package/dist/providers/launchdarkly/client.d.ts

@@ -1,4 +1,5 @@
 import type { PlatformFlag } from '../interface.js';
+import type { ScanLogger } from '../../scan-repo.js';
 export interface FetchAllFlagsConfig {
     project: string;
     environment: string;
@@ -8,6 +9,13 @@ export interface FetchAllFlagsOptions {
     apiBase?: string;
     fetch?: typeof globalThis.fetch;
     signal?: AbortSignal;
+    /**
+     * Optional logger for one-line advisory messages emitted by aux
+     * fetches (e.g. code-refs not configured). When unset, advisories
+     * are silently dropped — useful for tests and direct callers that
+     * don't go through the orchestrator.
+     */
+    logger?: ScanLogger;
 }
 /**
  * Fetches every flag in `config.project` (active + archived), then enriches

package/dist/providers/launchdarkly/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/launchdarkly/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAgCnD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,YAAY,EAAE,CAAC,CAuHzB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/launchdarkly/client.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,iBAAiB,CAAA;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAgCpD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,YAAY,EAAE,CAAC,CAuJzB"}

package/dist/providers/launchdarkly/client.js

@@ -1,5 +1,5 @@
 import pLimit from 'p-limit';
-import { AuditLogResponseSchema, EvaluationsResponseSchema, FlagsResponseSchema, FlagStatusesResponseSchema, MembersResponseSchema, } from './types.js';
+import { AuditLogResponseSchema, CodeRefsStatisticsResponseSchema, EvaluationsResponseSchema, FlagsResponseSchema, FlagStatusesResponseSchema, MembersResponseSchema, } from './types.js';
 import { LdApiError } from './errors.js';
 const DEFAULT_API_BASE = 'https://app.launchdarkly.com';
 const LD_API_VERSION = '20240415';
@@ -79,6 +79,14 @@ export async function fetchAllFlags(config, opts = {}) {
                     // Resolved below from the /members lookup; left as the opaque id
                     // for now so the producer/consumer split stays clean.
                     maintainer: item.maintainerId,
+                    // The cast narrows the inferred type from `VariationSchema.passthrough()`
+                    // (which infers `Record<string, unknown>` for extra fields) back to the
+                    // declared `PlatformFlag.variations` shape. The runtime data is
+                    // identical; the cast is a structural type-narrowing only.
+                    variations: item.variations,
+                    on: envData?.on,
+                    fallthroughVariation: envData?.fallthrough?.variation ?? null,
+                    offVariation: envData?.offVariation,
                 });
             }
             path = parsed._links?.next?.href;
@@ -146,6 +154,29 @@ export async function fetchAllFlags(config, opts = {}) {
             flag.lastTouched = lastTouched.get(flag.key) ?? null;
         }
     }
+    // Aux 5: LD code-references (cross-check against our own detection).
+    // Single project-scoped call; not env-scoped. Surfaces detector blind
+    // spots when LD finds more references than FlagShark detected. Opt-in
+    // LD feature; when unavailable we log an advisory pointing customers
+    // at the setup docs.
+    const codeRefs = await fetchCodeReferences(config, apiBase, headers, fetchFn, opts.signal);
+    if (codeRefs === null) {
+        // Feature unavailable — single advisory line. info-severity (not
+        // warn) because this isn't a failure, just a missed-opportunity
+        // nudge. The existing logger threading from Task 1 delivers it
+        // through the orchestrator into the scan output.
+        opts.logger?.info(`LaunchDarkly code-references not available for this project — enable it in LD ` +
+            `(Code references → Connect repository) to get coverage-gap diagnostics. ` +
+            `See https://launchdarkly.com/docs/home/observability/code-references for setup.`);
+    }
+    else {
+        for (const flag of out) {
+            if (flag.archived)
+                continue;
+            const count = codeRefs.get(flag.key) ?? 0;
+            flag.codeReferences = count > 0 ? { count } : null;
+        }
+    }
     return out;
 }
 /**
@@ -217,7 +248,12 @@ function buildFirstPath(project, environment, archived = false) {
         env: environment,
         limit: '100',
         offset: '0',
-        summary: '1',
+        // summary=0 returns full flag objects with variations + per-env
+        // fallthrough/on/offVariation. summary=1 (the previous default) only
+        // returned key/tags/lastModified, which was insufficient for SaaS
+        // Piranha to substitute the correct value during cleanup. Payload
+        // grows ~1-5KB per flag — well within reasonable for paginated fetch.
+        summary: '0',
     });
     if (archived)
         params.set('archived', 'true');
@@ -368,4 +404,50 @@ async function fetchLastTouchedMap(config, apiBase, headers, fetchFn, signal) {
         return null;
     return lastTouched;
 }
+/**
+ * Best-effort fetch of LD's per-flag code-references statistics.
+ *
+ * Returns:
+ *   - Map<flagKey, totalHunkCount> on success (possibly empty if no flag
+ *     has refs yet — e.g. CI ran but matched nothing)
+ *   - null when:
+ *       - 401/403/404 (tier-gated / not configured for this project)
+ *       - 5xx / 429 (transient errors)
+ *       - network or JSON parse failure
+ *
+ * Caller distinguishes:
+ *   - null               → feature unavailable; leave codeReferences undefined
+ *                          per flag AND emit the "not configured" advisory
+ *   - empty Map          → feature available but no refs yet; flags get null
+ *   - populated Map      → join by flag key; flags absent get null
+ */
+async function fetchCodeReferences(config, apiBase, headers, fetchFn, signal) {
+    try {
+        const url = new URL(`/api/v2/code-refs/statistics/${encodeURIComponent(config.project)}`, apiBase);
+        const res = await fetchFn(url, { headers, signal });
+        if (res.status === 401 || res.status === 403 || res.status === 404) {
+            return null;
+        }
+        /* v8 ignore next — non-401/403/404 error status; not exercised by current fixtures. */
+        if (!res.ok)
+            return null;
+        const parsed = CodeRefsStatisticsResponseSchema.parse(await res.json());
+        const out = new Map();
+        for (const [flagKey, repoEntries] of Object.entries(parsed.flags)) {
+            let total = 0;
+            for (const entry of repoEntries) {
+                if (typeof entry.hunkCount === 'number')
+                    total += entry.hunkCount;
+            }
+            out.set(flagKey, total);
+        }
+        return out;
+        /* v8 ignore start — defensive catch for malformed JSON / schema
+           drift; not exercised by current fixtures. */
+    }
+    catch {
+        return null;
+    }
+    /* v8 ignore stop */
+}
 //# sourceMappingURL=client.js.map