@flagshark/core 2.0.0 → 2.1.0

package/dist/output/text.js

@@ -33,10 +33,35 @@ function buildTable(flags) {
                 return 'missing-in-platform';
             if (s.type === 'archived-in-platform')
                 return 'archived-in-platform';
+            if (s.type === 'platform-too-old')
+                return 'platform-too-old';
+            if (s.type === 'platform-inactive')
+                return 'platform-inactive';
+            if (s.type === 'platform-launched')
+                return 'platform-launched';
             return s.description;
         })
             .join(', ');
         lines.push(`│ ${pad(sf.name, cols.flag)} │ ${pad(fileRef, cols.file)} │ ${pad(sf.age ?? 'unknown', cols.added)} │ ${pad(signalText, cols.signal)} │`);
+        // Compact second row when we have platform metadata to surface.
+        // Indented under the flag column, kept brief so the table doesn't
+        // explode in width. Skipped when there's nothing to say.
+        const metaParts = [];
+        if (sf.tags && sf.tags.length > 0) {
+            metaParts.push(`tags: ${sf.tags.join(', ')}`);
+        }
+        if (sf.maintainer) {
+            metaParts.push(`maintainer: ${sf.maintainer}`);
+        }
+        if (sf.platformStatus && sf.platformStatus !== 'active') {
+            metaParts.push(`platform-status: ${sf.platformStatus}`);
+        }
+        if (metaParts.length > 0) {
+            const metaText = metaParts.join(' • ');
+            // Wide layout — span all 4 column widths plus borders.
+            const totalWidth = cols.flag + cols.file + cols.added + cols.signal + 9; // 3 inner separators + 6 padding
+            lines.push(`│   ${pad('└─ ' + metaText, totalWidth)} │`);
+        }
     }
     lines.push(hBorder('└', '┴', '┘'));
     return lines.join('\n');
@@ -50,11 +75,53 @@ export function formatText(result, options) {
     if (result.excludedCount && result.excludedCount > 0) {
         lines.push(`(${result.excludedCount} excluded via .flagsharkignore + excludes)`);
     }
+    // Surface files where the detector errored. A small number is the long tail
+    // of edge cases (mid-edit syntax errors, exotic source files, etc.) — note
+    // it but don't shout. A large fraction means the analysis is materially
+    // incomplete (e.g. PostHog on 1.3.x: ~27% of files aborted from the python
+    // tree-sitter grammar) and the user needs to know before they trust the
+    // flag count or health score. Threshold of >5% picks up "noticeably broken"
+    // without firing on the dozen-files-out-of-ten-thousand case.
+    const parseErrorCount = result.parseErrorCount ?? 0;
+    if (parseErrorCount > 0 && result.filesScanned > 0) {
+        const pct = (parseErrorCount / result.filesScanned) * 100;
+        // Compare on the rounded value so the threshold and the displayed
+        // percentage cannot disagree. Pre-fix, `pct > 5` with `Math.round(pct)`
+        // could fire the warning branch while rendering "(5%)" — same number
+        // we document as the quiet/loud boundary in the comment above. See
+        // ultrareview bug_018.
+        const rounded = Math.round(pct);
+        const pctStr = pct >= 1 ? ` (${rounded}%)` : '';
+        if (rounded > 5) {
+            lines.push(`⚠ ${parseErrorCount} of ${result.filesScanned} files${pctStr} couldn't be parsed — results may be incomplete. See the "Parse errors during analysis" warning on stderr for the top failing patterns.`);
+        }
+        else {
+            lines.push(`(${parseErrorCount} file${parseErrorCount === 1 ? '' : 's'} couldn't be parsed — see the "Parse errors during analysis" warning above)`);
+        }
+    }
     if (result.totalFlags === 0) {
         lines.push('No feature flags detected.');
         lines.push('');
         lines.push('Supported providers: LaunchDarkly, Unleash, Flipt, Split.io, PostHog, and more.');
         lines.push('Run flagshark scan --help for configuration options.');
+        // Troubleshooting hint when a non-trivial repo turns up empty. Pre-fix,
+        // this was the single most common confused-user response: "I have 50
+        // feature flags, your scan found 0, what's wrong?". The hint surfaces
+        // the three real causes (SDK wrappers loaded at runtime, TS path
+        // aliases, config-struct flag systems) without falsely promising
+        // "this WILL find them"; see README#known-limitations for the design
+        // trade-offs that lead here. We only fire on repos large enough that
+        // "no flags at all" is suspicious (≥100 files); empty/tiny repos
+        // legitimately have no flags and don't deserve scolding.
+        const SUSPICIOUS_THRESHOLD = 100;
+        if (result.filesScanned >= SUSPICIOUS_THRESHOLD) {
+            lines.push('');
+            lines.push(`Expected results in this ${result.filesScanned}-file repo? Three patterns FlagShark can't see today:`);
+            lines.push('  • SDK loaded at runtime via window/globalThis (instead of static `import`)');
+            lines.push('  • TS path aliases (`@/...`, `~/...`) bridging the consumer file to the SDK');
+            lines.push('  • Typed config-struct flag systems (e.g. `Config().FeatureFlags.X`)');
+            lines.push('See https://github.com/FlagShark/flagshark#known-limitations for details + workarounds.');
+        }
         return lines.join('\n');
     }
     if (result.detectedProviders.length > 0) {
@@ -63,6 +130,24 @@ export function formatText(result, options) {
     const uniqueStaleNames = new Set(result.staleFlags.map((f) => f.name));
     const staleCount = uniqueStaleNames.size;
     lines.push(`Found ${result.totalFlags} feature flags, ${staleCount} stale`);
+    // Surface permanent-flag exclusions so users see WHY a flag they expected
+    // to appear in the stale table doesn't. Per-platform breakdown so the
+    // attribution is clear when multiple platforms are configured.
+    if (result.permanentByPlatform && Object.keys(result.permanentByPlatform).length > 0) {
+        for (const [platform, names] of Object.entries(result.permanentByPlatform)) {
+            if (names.length === 0)
+                continue;
+            const flagWord = names.length === 1 ? 'flag' : 'flags';
+            // Cap the inline list at 5 names to keep the line readable on
+            // medium-sized projects. Verbose mode could show all — but the
+            // existing verbose option drives the stale-table cap, not this.
+            // For now, a fixed cap: anyone with >5 permanent flags can see
+            // the full list in JSON output.
+            const preview = names.slice(0, 5).join(', ');
+            const overflow = names.length > 5 ? `, +${names.length - 5} more` : '';
+            lines.push(`${names.length} ${flagWord} excluded as permanent in ${platform}: ${preview}${overflow}`);
+        }
+    }
     if (staleCount > 0) {
         lines.push('');
         lines.push('Stale flags:');

package/dist/output/text.js.map

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

package/dist/providers/cross-reference.d.ts

@@ -1,13 +1,35 @@
 import type { FeatureFlag } from '../detection/feature-flag.js';
 import type { PlatformFlag, PlatformSignal } from './interface.js';
+export interface CrossReferenceOptions {
+    /**
+     * Staleness threshold in days. When set, cross-reference can emit
+     * `platform-too-old` for matched flags whose platform-side
+     * `createdAt` exceeds the threshold — a code-independent staleness
+     * signal that's stronger than either code-age or platform-age alone.
+     * When unset, the platform-too-old signal is never emitted.
+     */
+    thresholdDays?: number;
+}
 /**
  * Pure function: joins detected flag keys against a platform's flag list,
- * emits PlatformSignals for keys that are missing (error) or archived (warning).
+ * emits PlatformSignals based on the platform's view of each flag.
+ *
+ * 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)
+ *
+ * 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.
  *
  * Does NOT surface platform flags with no code reference — that's a separate
  * "orphan platform flags" feature, out of scope.
  */
-export declare function crossReference(detectedFlags: Map<string, FeatureFlag[]>, platformFlags: PlatformFlag[], platformDisplayName: string): Map<string, PlatformSignal[]>;
+export declare function crossReference(detectedFlags: Map<string, FeatureFlag[]>, platformFlags: PlatformFlag[], platformDisplayName: string, options?: CrossReferenceOptions): Map<string, PlatformSignal[]>;
 /**
  * Merge platform signals from multiple platforms into a single per-flag map.
  * If both LaunchDarkly and Unleash say a flag is missing, the flag's entry

package/dist/providers/cross-reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-reference.d.ts","sourceRoot":"","sources":["../../src/providers/cross-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAElE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EACzC,aAAa,EAAE,YAAY,EAAE,EAC7B,mBAAmB,EAAE,MAAM,GAC1B,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAsB/B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,EACnC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,GACpC,IAAI,CASN"}
+{"version":3,"file":"cross-reference.d.ts","sourceRoot":"","sources":["../../src/providers/cross-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAElE,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EACzC,aAAa,EAAE,YAAY,EAAE,EAC7B,mBAAmB,EAAE,MAAM,EAC3B,OAAO,GAAE,qBAA0B,GAClC,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAoF/B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,EACnC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,GACpC,IAAI,CASN"}

package/dist/providers/cross-reference.js

@@ -1,28 +1,95 @@
 /**
  * Pure function: joins detected flag keys against a platform's flag list,
- * emits PlatformSignals for keys that are missing (error) or archived (warning).
+ * emits PlatformSignals based on the platform's view of each flag.
+ *
+ * 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)
+ *
+ * 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.
  *
  * 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) {
+export function crossReference(detectedFlags, platformFlags, platformDisplayName, options = {}) {
     const platformByKey = new Map(platformFlags.map((f) => [f.key, f]));
     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) {
-            out.set(key, [{
+            out.set(key, [
+                {
                     type: 'missing-in-platform',
                     severity: 'error',
                     description: `referenced in code but not found in ${platformDisplayName}`,
-                }]);
+                },
+            ]);
+            continue;
         }
-        else if (platform.archived) {
-            out.set(key, [{
+        if (platform.archived) {
+            out.set(key, [
+                {
                     type: 'archived-in-platform',
                     severity: 'warning',
                     description: `archived in ${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') {
+            signals.push({
+                type: 'platform-launched',
+                severity: 'error',
+                description: `${platformDisplayName} reports this flag has served one variation for 7+ days — 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`,
+            });
+        }
+        if (platform.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
+            // flags should not be flagged as stale by code-side heuristics.
+            signals.push({
+                type: 'platform-permanent',
+                severity: 'info',
+                description: `marked permanent in ${platformDisplayName}`,
+            });
+        }
+        // platform-too-old: platform-side staleness independent of code age.
+        // Only fires when caller provided a threshold AND the platform
+        // 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 &&
+            thresholdMs != null &&
+            platform.createdAt &&
+            now - platform.createdAt.getTime() > thresholdMs) {
+            const ageDays = Math.floor((now - platform.createdAt.getTime()) / 86_400_000);
+            signals.push({
+                type: 'platform-too-old',
+                severity: 'warning',
+                description: `created in ${platformDisplayName} ${ageDays} days ago — past the ${options.thresholdDays}-day threshold`,
+            });
+        }
+        if (signals.length > 0) {
+            out.set(key, signals);
         }
     }
     return out;

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

@@ -1 +1 @@
-{"version":3,"file":"cross-reference.js","sourceRoot":"","sources":["../../src/providers/cross-reference.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,aAAyC,EACzC,aAA6B,EAC7B,mBAA2B;IAE3B,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IACnE,MAAM,GAAG,GAAG,IAAI,GAAG,EAA4B,CAAA;IAE/C,KAAK,MAAM,GAAG,IAAI,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACvC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;oBACZ,IAAI,EAAE,qBAAqB;oBAC3B,QAAQ,EAAE,OAAO;oBACjB,WAAW,EAAE,uCAAuC,mBAAmB,EAAE;iBAC1E,CAAC,CAAC,CAAA;QACL,CAAC;aAAM,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAC7B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;oBACZ,IAAI,EAAE,sBAAsB;oBAC5B,QAAQ,EAAE,SAAS;oBACnB,WAAW,EAAE,eAAe,mBAAmB,EAAE;iBAClD,CAAC,CAAC,CAAA;QACL,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAmC,EACnC,MAAqC;IAErC,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAA;QAC3B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAA;QAC7B,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"cross-reference.js","sourceRoot":"","sources":["../../src/providers/cross-reference.ts"],"names":[],"mappings":"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"}

package/dist/providers/interface.d.ts

@@ -5,6 +5,70 @@ export interface PlatformFlag {
     /** Each platform maps its concept (archived/disabled/stale) to this boolean. */
     archived: boolean;
     lastModified: Date | null;
+    /**
+     * True when the platform considers this flag permanent — i.e. NOT a
+     * temporary feature toggle that should ever be removed. Kill-switches,
+     * operational config flags, and "long-lived experiments" fall here.
+     *
+     * Maps from LaunchDarkly's `temporary` field (we invert: `permanent =
+     * !temporary`). Other platforms may not have an equivalent concept —
+     * leave undefined when unknown, which the staleness engine treats
+     * exactly as it always did (no special-case suppression).
+     *
+     * Why surface this: the staleness engine's age and low-usage signals
+     * are false positives on intentionally permanent flags. A
+     * personal-access-tokens kill switch shouldn't be flagged as "stale"
+     * just because it's three years old and only appears in one place;
+     * that's the entire point of a kill switch.
+     */
+    permanent?: boolean;
+    /**
+     * When the flag was first created in the platform. Distinct from
+     * `lastModified` (which tracks the most recent environment-level
+     * edit). The cross-reference layer compares this against the
+     * staleness threshold to emit `platform-too-old` — a code-independent
+     * staleness signal. A flag that LD created 18 months ago AND still
+     * has code references is a stronger candidate for cleanup than either
+     * data point alone.
+     */
+    createdAt?: Date | null;
+    /**
+     * Platform-side classification labels. LaunchDarkly's tag list maps
+     * directly; other platforms may map their equivalent concept (Unleash
+     * `strategies`, Split.io `traffic_types`, etc.). Surfaced in output
+     * so reviewers see the LD-side classification alongside flag names.
+     */
+    tags?: string[];
+    /**
+     * Human-readable maintainer label. Producer is responsible for
+     * resolving any opaque ID (e.g. LD `maintainerId`) into a display
+     * string ('First Last <email>') before populating this field.
+     */
+    maintainer?: string;
+    /**
+     * Platform-computed activity verdict for this flag in the configured
+     * environment. Maps directly from LD's flag-statuses endpoint:
+     *
+     *   - 'new': created in the last 7 days; not enough data yet → no
+     *     staleness verdict, suppresses code-side age signals
+     *   - 'active': serving evaluations as expected → no signal
+     *   - 'inactive': no evaluation events in 7+ days → emit
+     *     `platform-inactive` (warning) — code reference may be dead
+     *   - 'launched': single variation served consistently for 7+ days →
+     *     emit `platform-launched` (error) — flag is effectively rolled
+     *     out and the conditional code can be removed
+     *
+     * Other platforms may not have an equivalent; leave undefined when
+     * unknown.
+     */
+    status?: 'new' | 'active' | 'inactive' | 'launched';
+    /**
+     * When this flag was last evaluated, per the platform's runtime
+     * telemetry. Null when no evaluations have occurred yet (`status:
+     * 'new'`). Surface this in output so reviewers can decide whether
+     * "7 days ago" or "9 months ago" before pulling the trigger.
+     */
+    lastRequested?: Date | null;
 }
 /** Runtime client for a configured platform. Returned by PlatformDefinition.createClient. */
 export interface PlatformClient {
@@ -30,8 +94,31 @@ export interface PlatformDefinition<TConfig = unknown> {
 }
 /** Signal type emitted by crossReference(). Merged into StaleFlag.signals[] by staleness.ts. */
 export interface PlatformSignal {
-    type: 'missing-in-platform' | 'archived-in-platform';
-    severity: 'error' | 'warning';
+    /**
+     * Signal types:
+     *
+     * - `missing-in-platform` (error): code references a flag that's not
+     *   in the platform at all. Almost always a dead reference.
+     * - `archived-in-platform` (warning): user archived the flag in the
+     *   platform but code still references it — cleanup time.
+     * - `platform-permanent` (info, CONTROL signal): user marked the
+     *   flag permanent. Tells the staleness engine to suppress age + low-
+     *   usage signals; filtered out of user-facing output. See
+     *   PlatformFlag.permanent docstring for full reasoning.
+     * - `platform-too-old` (warning): the flag was created in the
+     *   platform more than `thresholdDays` ago — a code-independent
+     *   staleness signal. Survives even when code-age signal is clean
+     *   (e.g. flag was copy-pasted into a new file last week, but
+     *   originated in LD 2 years ago).
+     * - `platform-inactive` (warning): LD's own flag-status verdict —
+     *   no evaluations recorded against this flag in the last 7 days.
+     *   Sourced from the /flag-statuses endpoint.
+     * - `platform-launched` (error): LD's own verdict — flag has been
+     *   serving a single variation consistently for the past 7 days.
+     *   "Ready for removal" from LD's perspective.
+     */
+    type: 'missing-in-platform' | 'archived-in-platform' | 'platform-permanent' | 'platform-too-old' | 'platform-inactive' | 'platform-launched';
+    severity: 'error' | 'warning' | 'info';
     description: string;
 }
 //# sourceMappingURL=interface.d.ts.map

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;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,IAAI,EAAE,qBAAqB,GAAG,sBAAsB,CAAA;IACpD,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;CACpB"}
+{"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;CAC5B;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;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,EACA,qBAAqB,GACrB,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,mBAAmB,GACnB,mBAAmB,CAAA;IACvB,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IACtC,WAAW,EAAE,MAAM,CAAA;CACpB"}

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

@@ -9,5 +9,17 @@ export interface FetchAllFlagsOptions {
     fetch?: typeof globalThis.fetch;
     signal?: AbortSignal;
 }
+/**
+ * Fetches every flag in `config.project` (active + archived), then enriches
+ * the result with platform-side signals from two auxiliary LD endpoints:
+ *
+ *   /api/v2/flag-statuses/{project}/{env}     → status + lastRequested
+ *   /api/v2/members?limit=500                 → maintainer name resolution
+ *
+ * Both auxiliary calls are best-effort: if they fail (e.g. token lacks
+ * permission, network blip), we log via thrown LdApiError only for the
+ * primary /flags request. Aux failures are swallowed so the core
+ * cross-reference path still functions with partial data.
+ */
 export declare function fetchAllFlags(config: FetchAllFlagsConfig, opts?: FetchAllFlagsOptions): Promise<PlatformFlag[]>;
 //# sourceMappingURL=client.d.ts.map

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":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAKnD,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,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,YAAY,EAAE,CAAC,CA+BzB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/launchdarkly/client.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAKnD,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,CA+FzB"}