@quonfig/cli 0.0.50 → 0.0.51

package/dist/migrate/sources/flagsmith/api.js

@@ -0,0 +1,402 @@
+/**
+ * Flagsmith REST API client — Phase-1 config snapshot.
+ *
+ * Flagsmith has no bulk-export endpoint, so the fetcher stitches per-resource
+ * calls: project → environments → features → per-env featurestates → segments
+ * → feature-segments (priority) → edge identities → edge identity overrides
+ * → tags.
+ *
+ * Auth is `Authorization: Api-Key <token>` — note the `Api-Key` prefix (not
+ * `Bearer`, and not bare-token like LaunchDarkly). Rate-limiting headers are
+ * unpublished; we program against the response: back off on 429 using
+ * `Retry-After` (standard) or `X-RateLimit-Reset` (Flagsmith's variant), and
+ * step the inter-request throttle up briefly when we hit one (mirrors the
+ * Phase-2 generator's empirical backoff loop). On any non-429 error we throw
+ * immediately — only rate limiting is retried.
+ *
+ * Pagination is standard Django REST `{count, next, previous, results}` with
+ * absolute `next` URLs. Edge-identities listing is the one exception: it uses
+ * `{results, last_evaluated_key}` cursor pagination via a query-string param.
+ */
+const PROD_BASE_URL = 'https://api.flagsmith.com/api/v1';
+/** Page size for Django REST endpoints that accept `page_size`. Conservative for memory + 429 risk. */
+const PAGE_LIMIT = 100;
+/** Fallback wait when a 429 carries no usable headers. Mirrors the Phase-2 generator's base. */
+const DEFAULT_BACKOFF_MS = 2000;
+/** Hard cap on retries per request before we give up. */
+const MAX_RETRIES = 6;
+let baseUrl = PROD_BASE_URL;
+export function setFlagsmithBaseUrl(url) {
+    baseUrl = url;
+}
+export function selectFlagsmithBaseUrl() {
+    return process.env.FLAGSMITH_API_URL ?? PROD_BASE_URL;
+}
+export function applyFlagsmithBaseUrl() {
+    baseUrl = selectFlagsmithBaseUrl();
+}
+/** Real timer-backed sleep — swapped out in tests so MSW runs don't actually wait. */
+function timerSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Test seam: a no-op sleep is swapped in so MSW tests don't actually wait. */
+let sleepImpl = timerSleep;
+export function __setSleepForTests(fn) {
+    sleepImpl = fn;
+}
+export function __resetSleepForTests() {
+    sleepImpl = timerSleep;
+}
+export class FlagsmithApiError extends Error {
+    status;
+    constructor(status, statusText, url, body) {
+        super(`Flagsmith API request failed: ${status} ${statusText} — ${url}\n${body}`);
+        this.name = 'FlagsmithApiError';
+        this.status = status;
+    }
+}
+/**
+ * Compute the wait derived from a 429 response's headers.
+ *
+ * Flagsmith honours the standard `Retry-After` (seconds) and also sometimes
+ * sends `X-RateLimit-Reset` — which the Phase-2 generator observed as either
+ * seconds-from-now OR an epoch-ms timestamp. Heuristic: > 10^10 means
+ * epoch-ms. We bump the wait UP for either signal (never down) so a tight
+ * 429 storm doesn't burn through the retry budget faster than the API wants.
+ */
+function backoffMsFromHeaders(headers, attempt) {
+    // Exponential base: 2s, 4s, 8s, 16s, 32s, 60s (clamped).
+    let wait = Math.min(60_000, 2000 * 2 ** attempt);
+    const retryAfter = headers.get('Retry-After');
+    if (retryAfter !== null) {
+        const sec = Number(retryAfter);
+        if (Number.isFinite(sec))
+            wait = Math.max(wait, sec * 1000);
+    }
+    const reset = headers.get('X-RateLimit-Reset') ?? headers.get('X-Ratelimit-Reset');
+    if (reset !== null) {
+        const n = Number(reset);
+        if (Number.isFinite(n)) {
+            // > 10^10 ⇒ epoch ms; ≤ 10^10 ⇒ seconds-from-now.
+            const ms = n > 1e10 ? Math.max(0, n - Date.now()) : n * 1000;
+            wait = Math.max(wait, ms + 500);
+        }
+    }
+    return Math.min(60_000, wait);
+}
+/**
+ * Single GET with `Api-Key` auth, 429 backoff against `Retry-After` /
+ * `X-RateLimit-Reset`, and an exponential fallback. Non-429 errors throw
+ * immediately — only rate limiting is retried.
+ */
+export async function apiFetch(path, apiKey) {
+    const url = path.startsWith('http') ? path : `${baseUrl}${path}`;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await fetch(url, {
+            headers: {
+                Accept: 'application/json',
+                Authorization: `Api-Key ${apiKey}`,
+            },
+        });
+        if (res.status === 429) {
+            if (attempt === MAX_RETRIES) {
+                // eslint-disable-next-line no-await-in-loop
+                const body = await res.text().catch(() => '(no body)');
+                throw new FlagsmithApiError(429, res.statusText, url, body);
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await sleepImpl(backoffMsFromHeaders(res.headers, attempt) || DEFAULT_BACKOFF_MS);
+            continue;
+        }
+        if (!res.ok) {
+            // eslint-disable-next-line no-await-in-loop
+            const body = await res.text().catch(() => '(no body)');
+            throw new FlagsmithApiError(res.status, res.statusText, url, body);
+        }
+        return res.json();
+    }
+    // Unreachable — the loop either returns or throws.
+    throw new FlagsmithApiError(429, 'Too Many Requests', url, 'retries exhausted');
+}
+/**
+ * Walks a Django-REST paginated collection. The first page is fetched at
+ * `firstPath`; subsequent pages follow the absolute `next` URL until null.
+ * Flagsmith's `next` is a full `https://api.flagsmith.com/...` URL; `apiFetch`
+ * treats absolute URLs as-is, so this works under the configurable base URL
+ * for tests (we strip the production host off so the test base URL applies).
+ */
+async function paginate(firstPath, apiKey) {
+    const collected = [];
+    let nextPath = firstPath;
+    const seen = new Set();
+    while (nextPath && !seen.has(nextPath)) {
+        seen.add(nextPath);
+        // eslint-disable-next-line no-await-in-loop
+        const page = (await apiFetch(nextPath, apiKey));
+        if (Array.isArray(page.results))
+            collected.push(...page.results);
+        nextPath = page.next ? rewriteNextUrl(page.next) : undefined;
+    }
+    return collected;
+}
+/**
+ * Flagsmith's `next` field is the full production URL. For tests we point at
+ * `https://flagsmith.test/api/v1` via setFlagsmithBaseUrl; strip the prod
+ * host so the next-page fetch goes through the test server too.
+ */
+function rewriteNextUrl(next) {
+    if (baseUrl === PROD_BASE_URL)
+        return next;
+    if (next.startsWith(PROD_BASE_URL))
+        return baseUrl + next.slice(PROD_BASE_URL.length);
+    return next;
+}
+/** `GET /projects/{id}/` — used as the cheap auth probe AND as a source of `use_edge_identities`. */
+export async function fetchProject(apiKey, projectId) {
+    return apiFetch(`/projects/${encodeURIComponent(String(projectId))}/`, apiKey);
+}
+/** `GET /environments/?project={id}` — paginated env list. */
+export async function fetchEnvironments(apiKey, projectId) {
+    const qs = new URLSearchParams({ page_size: String(PAGE_LIMIT), project: String(projectId) });
+    return paginate(`/environments/?${qs}`, apiKey);
+}
+/**
+ * `GET /projects/{pk}/features/` — paginated feature list. Each result
+ * includes inline `multivariate_options[]` which we sort ASC by id (API6) so
+ * downstream code sees variations in definition order, not the reverse order
+ * the API returns.
+ */
+export async function fetchFeatures(apiKey, projectId) {
+    const qs = new URLSearchParams({ page_size: String(PAGE_LIMIT) });
+    const features = await paginate(`/projects/${encodeURIComponent(String(projectId))}/features/?${qs}`, apiKey);
+    for (const feature of features) {
+        if (Array.isArray(feature.multivariate_options) && feature.multivariate_options.length > 1) {
+            feature.multivariate_options = [...feature.multivariate_options].sort((a, b) => a.id - b.id);
+        }
+    }
+    return features;
+}
+/**
+ * `GET /features/featurestates/?environment={env_id}` — per-env featurestates.
+ *
+ * This is the unified listing that returns BOTH env-default rows
+ * (`feature_segment == null && identity == null`) AND segment-override rows
+ * (`feature_segment != null`). The plan §4.1 suggests
+ * `/environments/{api_key}/featurestates/`, but empirically on v2-versioned
+ * envs that endpoint silently omits segment-override rows. The
+ * `/features/featurestates/?environment=` path is the only read endpoint that
+ * returns both on a v2 env, so we use it uniformly across v1 and v2 envs.
+ *
+ * Identity overrides are NOT in this listing on edge-enabled projects — see
+ * `fetchEdgeIdentityOverrides`.
+ */
+export async function fetchEnvFeatureStates(apiKey, envId) {
+    const qs = new URLSearchParams({ environment: String(envId), page_size: String(PAGE_LIMIT) });
+    return paginate(`/features/featurestates/?${qs}`, apiKey);
+}
+/** `GET /projects/{pk}/segments/` — project-scoped segment pool. */
+export async function fetchSegments(apiKey, projectId) {
+    const qs = new URLSearchParams({ page_size: String(PAGE_LIMIT) });
+    return paginate(`/projects/${encodeURIComponent(String(projectId))}/segments/?${qs}`, apiKey);
+}
+/**
+ * `GET /features/feature-segments/?environment={env_id}&feature={feature_id}` —
+ * the per-env, per-feature segment priority list. Required by the converter
+ * to order the segment-override rules (Quonfig is a strict first-match list).
+ *
+ * The endpoint REJECTS calls without `feature` (`{feature: ["This field is
+ * required."]}`), so we have to walk every feature × env combo. This is N×E
+ * calls in the worst case — acceptable for the corpus (~110 features × 2 envs
+ * = ~220 calls) and roughly the same order as fetchEnvFeatureStates.
+ */
+export async function fetchFeatureSegments(apiKey, envId, featureId) {
+    const qs = new URLSearchParams({
+        environment: String(envId),
+        feature: String(featureId),
+        page_size: String(PAGE_LIMIT),
+    });
+    return paginate(`/features/feature-segments/?${qs}`, apiKey);
+}
+/**
+ * `GET /environments/{api_key}/edge-identities/` — paginated edge-identity
+ * listing. Pagination here is CURSOR-based (`last_evaluated_key`) not page
+ * numbers — the Flagsmith dynamo-backed edge store can't offset-paginate.
+ *
+ * The fetcher uses this only to surface identifiers for the report; the
+ * actual identity-override featurestates come from
+ * `fetchEdgeIdentityOverrides`, which is a one-call-per-env shortcut.
+ */
+export async function fetchEdgeIdentities(apiKey, envApiKey) {
+    const collected = [];
+    let cursor = null;
+    const seen = new Set();
+    for (;;) {
+        const qs = new URLSearchParams({ page_size: String(PAGE_LIMIT) });
+        if (cursor !== null)
+            qs.set('last_evaluated_key', cursor);
+        // eslint-disable-next-line no-await-in-loop
+        const page = (await apiFetch(`/environments/${encodeURIComponent(envApiKey)}/edge-identities/?${qs}`, apiKey));
+        if (Array.isArray(page.results))
+            collected.push(...page.results);
+        if (!page.last_evaluated_key || seen.has(page.last_evaluated_key))
+            break;
+        seen.add(page.last_evaluated_key);
+        cursor = page.last_evaluated_key;
+    }
+    return collected;
+}
+/**
+ * `GET /environments/{api_key}/edge-identity-overrides` — every identity
+ * override in the env, flat. Each row is `{identifier, identity_uuid,
+ * feature_state}` so we can index by feature without walking N identities.
+ *
+ * Note: the path has NO trailing slash (unlike most Flagsmith paths). This
+ * endpoint does not paginate in the verified shape — it returns
+ * `{results: [...]}` directly.
+ */
+export async function fetchEdgeIdentityOverrides(apiKey, envApiKey) {
+    const data = (await apiFetch(`/environments/${encodeURIComponent(envApiKey)}/edge-identity-overrides`, apiKey));
+    return Array.isArray(data.results) ? data.results : [];
+}
+/** `GET /projects/{pk}/tags/` — project-scoped tag pool. */
+export async function fetchTags(apiKey, projectId) {
+    const qs = new URLSearchParams({ page_size: String(PAGE_LIMIT) });
+    return paginate(`/projects/${encodeURIComponent(String(projectId))}/tags/?${qs}`, apiKey);
+}
+/**
+ * Stitch the whole Phase-1 snapshot: project → environments → features →
+ * per-env featurestates (split into env-default + segment-overrides) → segments
+ * → feature-segments (per env, per feature with segment overrides) → edge
+ * identity overrides → tags.
+ *
+ * Walk count grows as 1 (project) + 1 (envs) + 1 (segments) + 1 (tags) + E ×
+ * (1 featurestates + 1 edge-id-overrides + S features-with-segov ×
+ * feature-segments). For the 110-feature, 2-env, 5 features-with-segov live
+ * corpus: ~1 + 1 + 1 + 1 + 2 × (1 + 1 + 5) = ~17 calls. The featurestates
+ * endpoint is paginated under 100/page so larger projects multiply that
+ * featurestates leg.
+ *
+ * `sinceEpochMs` is currently unused — decision D2 says Phase 1 is always a
+ * full re-snapshot. It survives in the signature so reporting (Epic 5) can
+ * compute "what's new since last run" against the same snapshot.
+ */
+export async function fetchSnapshot(apiKey, projectId) {
+    const project = await fetchProject(apiKey, projectId);
+    const environments = await fetchEnvironments(apiKey, projectId);
+    const features = await fetchFeatures(apiKey, projectId);
+    const segments = await fetchSegments(apiKey, projectId);
+    const tags = await fetchTags(apiKey, projectId);
+    // Index featurestates by env_api_key, then by feature_id. We split each env's
+    // featurestate listing into env-default rows (feature_segment == null) and
+    // segment-override rows (feature_segment != null) up-front so the per-feature
+    // bundle assembly below is a lookup, not a scan.
+    const fsByEnvByFeature = new Map();
+    for (const env of environments) {
+        // eslint-disable-next-line no-await-in-loop
+        const featureStates = await fetchEnvFeatureStates(apiKey, env.id);
+        const perFeature = new Map();
+        for (const fs of featureStates) {
+            const bucket = perFeature.get(fs.feature) ?? { default: null, segment_overrides: [] };
+            if (fs.feature_segment === null) {
+                bucket.default = fs;
+            }
+            else {
+                bucket.segment_overrides.push(fs);
+            }
+            perFeature.set(fs.feature, bucket);
+        }
+        fsByEnvByFeature.set(env.api_key, perFeature);
+    }
+    // Edge-identity overrides indexed by env_api_key → feature_id.
+    const idovByEnvByFeature = new Map();
+    if (project.use_edge_identities) {
+        for (const env of environments) {
+            // eslint-disable-next-line no-await-in-loop
+            const overrides = await fetchEdgeIdentityOverrides(apiKey, env.api_key);
+            const byFeature = new Map();
+            for (const ov of overrides) {
+                const list = byFeature.get(ov.feature_state.feature) ?? [];
+                list.push(ov);
+                byFeature.set(ov.feature_state.feature, list);
+            }
+            idovByEnvByFeature.set(env.api_key, byFeature);
+        }
+    }
+    // feature-segments listing (per env, per feature) for priority. Only fetched
+    // for features that actually have segment-override featurestates in this env
+    // — saves N×E calls on the common case where most features have no segovs.
+    const fsegByEnvByFeature = new Map();
+    for (const env of environments) {
+        const perFeature = fsByEnvByFeature.get(env.api_key) ?? new Map();
+        const featuresWithSegov = [];
+        for (const [featureId, bucket] of perFeature) {
+            if (bucket.segment_overrides.length > 0)
+                featuresWithSegov.push(featureId);
+        }
+        const byFeature = new Map();
+        for (const featureId of featuresWithSegov) {
+            // eslint-disable-next-line no-await-in-loop
+            const rows = await fetchFeatureSegments(apiKey, env.id, featureId);
+            byFeature.set(featureId, rows);
+        }
+        fsegByEnvByFeature.set(env.api_key, byFeature);
+    }
+    // Stitch the per-feature bundles together.
+    const stitched = features.map((feature) => stitchFeatureBundle(feature, environments, fsByEnvByFeature, idovByEnvByFeature, fsegByEnvByFeature));
+    return { environments, features: stitched, project, segments, tags };
+}
+/**
+ * For one feature, assemble its per-env bundle. Sorts segment-override
+ * featurestates by their `feature_segment` priority (ASC) using the
+ * feature-segments lookup, so the converter sees them in evaluation order.
+ */
+function stitchFeatureBundle(feature, environments, fsByEnvByFeature, idovByEnvByFeature, fsegByEnvByFeature) {
+    const featurestates_by_env = {};
+    const feature_segments_by_env = {};
+    for (const env of environments) {
+        const perFeature = fsByEnvByFeature.get(env.api_key) ?? new Map();
+        const bucket = perFeature.get(feature.id) ?? { default: null, segment_overrides: [] };
+        const idov = idovByEnvByFeature.get(env.api_key)?.get(feature.id) ?? [];
+        const fseg = fsegByEnvByFeature.get(env.api_key)?.get(feature.id) ?? [];
+        // Sort segment-override featurestates by priority ASC, using the
+        // feature_segments table. Each fs.feature_segment is either a number ID or
+        // an inline {id, priority, ...} object — handle both.
+        const priorityById = new Map();
+        for (const fs of fseg)
+            priorityById.set(fs.id, fs.priority);
+        const sortedSegov = [...bucket.segment_overrides].sort((a, b) => {
+            const pa = priorityFor(a, priorityById);
+            const pb = priorityFor(b, priorityById);
+            return pa - pb;
+        });
+        featurestates_by_env[env.api_key] = {
+            default: bucket.default,
+            identity_overrides: idov,
+            segment_overrides: sortedSegov,
+        };
+        feature_segments_by_env[env.api_key] = fseg;
+    }
+    return { feature, feature_segments_by_env, featurestates_by_env };
+}
+/**
+ * Resolve a segment-override featurestate's priority. `feature_segment` on the
+ * row comes as either a numeric ID (legacy endpoint) or an inline `{id,
+ * priority, ...}` object (the `/features/featurestates/` endpoint we use).
+ * Fall back to a huge number so an unresolved row sorts last instead of NaN.
+ */
+function priorityFor(fs, priorityById) {
+    const fsRef = fs.feature_segment;
+    if (fsRef === null || fsRef === undefined)
+        return Number.MAX_SAFE_INTEGER;
+    if (typeof fsRef === 'object' && typeof fsRef.priority === 'number')
+        return fsRef.priority;
+    if (typeof fsRef === 'number') {
+        const p = priorityById.get(fsRef);
+        if (typeof p === 'number')
+            return p;
+    }
+    return Number.MAX_SAFE_INTEGER;
+}

package/dist/migrate/sources/flagsmith/translate.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Flagsmith converter — Flagsmith feature/segment JSON → `QuonfigFile`-ready
+ * objects (plain JS objects ready for `JSON.stringify`).
+ *
+ * Provider-specific topology collapse (plan §5, Epic 3). Calls the shared
+ * `quonfig-target/` verb library where the structure is identical to LD
+ * (value coercion, criterion + rule shape, report wiring) and handles the
+ * Flagsmith-shaped bits here: synthesizing the ordered rule list from
+ * `feature_state` + `segment_overrides` + `identity_overrides` (§5.1),
+ * `enabled=false` disposition per D-F1, operator mapping with `:semver`
+ * suffix detection (§5.3), multivariate weighted-values shape (§5.4),
+ * cross-env value-type coercion per D-F5.
+ *
+ * This module is a pure function — no I/O, no env reads, no module-level
+ * mutable state. Report accumulation flows through the `ConversionReport`
+ * argument supplied by the caller (the `flagsmith.ts` source).
+ */
+import type { ConversionReport } from '../../quonfig-target/report.js';
+import type { QuonfigCriterion } from '../../quonfig-target/ruleset.js';
+import type { FlagsmithFeatureStateValueEnvelope, FlagsmithFeatureWithStates, FlagsmithSegment, FlagsmithSegmentCondition, FlagsmithTag } from './types.js';
+/**
+ * Operator-mapping result. A clean criterion translation OR a whole-rule drop
+ * with a precise reason. Returned per condition; the rule is dropped if any
+ * condition drops.
+ */
+type ConditionMapping = {
+    criterion: QuonfigCriterion;
+} | {
+    drop: true;
+    reason: string;
+};
+/**
+ * Flagsmith feature names land directly under `feature-flags/` — Flagsmith
+ * enforces a lower-case-hyphenated naming policy on most projects, so the
+ * key is already filesystem-safe. We still defensively replace any `/` so
+ * a name can never spawn a nested directory.
+ */
+export declare function flagOutputPath(name: string): string;
+export declare function segmentOutputPath(name: string): string;
+/**
+ * Unwrap the `feature_state_value` field as it appears on the
+ * `/features/featurestates/` endpoint (envelope shape on env-default and
+ * segment-override rows; scalar on `/edge-identity-overrides` per API5).
+ * Returns the raw JS value Flagsmith would have served before any Quonfig
+ * type coercion.
+ */
+export declare function coerceEnvelopeOrScalar(v: FlagsmithFeatureStateValueEnvelope | boolean | null | number | string | undefined): boolean | null | number | string;
+/**
+ * Map one Flagsmith condition to a Quonfig criterion, or signal a whole-rule
+ * drop with a reason. Implements plan §5.3 verbatim.
+ */
+export declare function mapCondition(condition: FlagsmithSegmentCondition): ConditionMapping;
+/**
+ * Translate one Flagsmith feature (with all its per-env state) into a Quonfig
+ * feature-flag config object.
+ */
+export declare function translateFeature(bundle: FlagsmithFeatureWithStates, report: ConversionReport, options?: {
+    /** Map from env api_key → user-facing env name. The converter slugifies the name for the Quonfig env id. */
+    envNameByApiKey?: Map<string, string>;
+    segmentNameById?: Map<number, string>;
+    tags?: FlagsmithTag[];
+}): Record<string, unknown>;
+/**
+ * Translate one Flagsmith segment into a Quonfig segment config object.
+ *
+ * Quonfig segments are boolean ("is the context in the segment?") and have no
+ * per-environment state, so all rules collapse into `default.rules`,
+ * first-match-wins. A rule whose conditions all map yields a true-valued rule;
+ * a trailing ALWAYS_TRUE serves false (not in segment).
+ */
+export declare function translateSegment(segment: FlagsmithSegment, report: ConversionReport): Record<string, unknown>;
+export {};