@quonfig/cli 0.0.49 → 0.0.51

package/dist/migrate/sources/flagsmith.js

@@ -1,28 +1,385 @@
-// Stub — `qfg migrate --from flagsmith` is not yet wired up. Before replacing this with a real
-// implementation, investigate:
-//   - Flagsmith API shape: what the admin/REST API returns for features, segments, identities,
-//     environments, and multivariate variations, and how that maps onto Quonfig's JSON schema.
-//   - Delta/cursor support: whether Flagsmith exposes an audit-log or change-feed endpoint with a
-//     stable cursor we can persist in `.qf/import-state.json` for re-runnable incremental
-//     imports, or whether we have to full-reimport + diff on every run (as is likely for LD).
-//   - Auth model: API key scopes (server-side vs. admin), org/project/environment hierarchy.
-//   - Schema gaps: Flagsmith's identity overrides and segment rules vs. Quonfig's rule operators
-//     — document any unsupported primitives the way `launchdarkly.README.md` does for LD.
-import { NotYetImplementedError } from '../source.js';
+/**
+ * `qfg migrate --from flagsmith` — the MigrationSource implementation.
+ *
+ * Wires the Flagsmith fetcher (`flagsmith/api.ts` + `flagsmith/types.ts`) and
+ * converter (`flagsmith/translate.ts`) into the source-agnostic migration
+ * framework. Epic 1 implemented the read side (validateAuth, listEnvironments,
+ * fetchChanges yielding LegacyChange[] carrying raw Flagsmith JSON); Epic 3
+ * adds the translate() side — `translateFeature` and `translateSegment`
+ * dispatched by `raw.kind` (see `FlagsmithRaw` below). Report accumulators
+ * (`getSkippedConfigs`, `getCoercedSentinels`, `getConversionNotes`) thread
+ * the per-source notes into MIGRATION_REPORT.md.
+ *
+ * Design is frozen in `project/plans/migrator-flagsmith.md`. Notable choices
+ * for this epic — the contract Epic 3 will consume:
+ *
+ * - `LegacyChange.raw` is a discriminated union over `{kind: 'feature' | 'segment'}`.
+ *   Features carry the full per-feature stitched bundle (env-default +
+ *   segment-overrides + identity-overrides + feature-segment priority +
+ *   inline MV options sorted by id asc). Segments are emitted separately
+ *   (project-scoped, referenced from multiple features).
+ *
+ * - Tags are NOT separate LegacyChanges — they're inline `feature.tags[]` as
+ *   integer IDs, plus a project-wide tag pool stashed in the source state for
+ *   the converter to resolve id → label.
+ *
+ * - Edge identities are NOT separate LegacyChanges. Identity overrides are
+ *   bundled inside the feature payload (`identity_overrides`); the identity
+ *   `identifier` is already on each override row. Traits are runtime context
+ *   the SDK sends — no server-side artifact to migrate (plan §5.5, D-F6).
+ *
+ * - Project metadata (`use_edge_identities`, `only_allow_lower_case_feature_names`,
+ *   …) is captured during `validateAuth` and stashed in source state. The
+ *   converter can read it via `getProjectMetadata()` (a Flagsmith-specific
+ *   getter, not part of the MigrationSource interface).
+ */
+import { ConversionReport } from '../quonfig-target/report.js';
+import { fetchProject, fetchSnapshot } from './flagsmith/api.js';
+import { flagOutputPath, segmentOutputPath, translateFeature, translateSegment } from './flagsmith/translate.js';
 const SOURCE_NAME = 'flagsmith';
+const DEFAULT_PROJECT_ID = '1';
+function resolveProjectId() {
+    return process.env.FLAGSMITH_PROJECT_ID ?? DEFAULT_PROJECT_ID;
+}
+const state = {
+    apiKey: null,
+    environments: [],
+    multivariateFeatures: [],
+    project: null,
+    projectId: resolveProjectId(),
+    report: new ConversionReport(),
+    segments: [],
+    tags: [],
+};
+/**
+ * Override the Flagsmith project ID for this run. Called by `qfg migrate` from
+ * its `--project` flag (or the `FLAGSMITH_PROJECT_ID` env var) — mirrors
+ * `setLaunchDarklyProjectKey`. Flagsmith projects are numeric, but we accept
+ * either a number or a numeric-string and convert at the API boundary.
+ */
+export function setFlagsmithProjectId(projectId) {
+    state.projectId = String(projectId);
+}
+/** The project metadata captured by validateAuth, or null if we haven't authed yet. */
+export function getFlagsmithProject() {
+    return state.project;
+}
+/** The tag pool from the last snapshot — Epic 3's converter resolves `feature.tags[]` IDs to labels via this. */
+export function getFlagsmithTagPool() {
+    return [...state.tags];
+}
+class MissingAuthError extends Error {
+    constructor(operation) {
+        super(`flagsmith source ${operation} requires validateAuth(apiKey) to be called first (no API key configured).`);
+        this.name = 'MissingAuthError';
+    }
+}
+function requireApiKey(operation) {
+    if (!state.apiKey)
+        throw new MissingAuthError(operation);
+    return state.apiKey;
+}
+/** Flagsmith env api_keys are random strings; we surface env `name` slugified. */
+function slugifyEnvName(name) {
+    return name
+        .toLowerCase()
+        .replaceAll(/[^\da-z]+/g, '-')
+        .replaceAll(/^-+|-+$/g, '');
+}
+async function validateAuthImpl(apiKey) {
+    // The cheapest authenticated probe is the project endpoint — 401s on a bad
+    // token, 404s on a bad project, and we need `use_edge_identities` for the
+    // snapshot walk anyway, so capture it here.
+    const project = await fetchProject(apiKey, state.projectId);
+    state.apiKey = apiKey;
+    state.project = project;
+    state.report = new ConversionReport();
+    state.environments = [];
+    state.multivariateFeatures = [];
+    state.segments = [];
+    state.tags = [];
+}
+async function listEnvironmentsImpl() {
+    const apiKey = requireApiKey('listEnvironments');
+    // We could do a dedicated fetchEnvironments call here, but fetchSnapshot
+    // will do that as part of fetchChanges anyway. To keep listEnvironments
+    // cheap (called by the migrate command before fetchChanges), we do a
+    // standalone env fetch and stash the results — fetchSnapshot will refresh
+    // them when it runs.
+    const { fetchEnvironments } = await import('./flagsmith/api.js');
+    const envs = await fetchEnvironments(apiKey, state.projectId);
+    state.environments = envs;
+    return [...new Set(envs.map((e) => slugifyEnvName(e.name)))];
+}
+/**
+ * Phase-1 config snapshot. Decision D2: always a full re-snapshot — we do not
+ * try to use Flagsmith's audit log for deltas (cursor stability across v2
+ * versioning rewrites is unverified). `sinceEpochMs` is currently unused;
+ * Epic 5 will use it for reporting "what changed since last run" without
+ * affecting the fetch itself.
+ *
+ * Yields one LegacyChange per feature (with the full per-env state bundle)
+ * followed by one LegacyChange per segment. Identity overrides are bundled
+ * inside the feature payload.
+ */
+async function* fetchChangesImpl() {
+    const apiKey = requireApiKey('fetchChanges');
+    const snapshot = await fetchSnapshot(apiKey, state.projectId);
+    state.project = snapshot.project;
+    state.environments = snapshot.environments;
+    state.segments = snapshot.segments;
+    state.tags = snapshot.tags;
+    state.multivariateFeatures = snapshot.features
+        .filter((bundle) => bundle.feature.type === 'MULTIVARIATE' && (bundle.feature.multivariate_options?.length ?? 0) > 0)
+        .map((bundle) => bundle.feature.name);
+    for (const featureBundle of snapshot.features) {
+        yield {
+            key: featureBundle.feature.name,
+            raw: { data: featureBundle, kind: 'feature' },
+            source: SOURCE_NAME,
+        };
+    }
+    for (const segment of snapshot.segments) {
+        yield {
+            key: segment.name,
+            raw: { data: segment, kind: 'segment' },
+            source: SOURCE_NAME,
+        };
+    }
+}
+/**
+ * Dispatch by raw.kind to the right translator (plan §5.1). Last-resort
+ * safety net mirrors the LD source — one structurally broken feature must
+ * not abort the whole run, so conversion errors land as `skipped-config`
+ * report entries and translate returns `[]`.
+ */
+function translateImpl(change) {
+    const raw = change.raw;
+    if (!raw || typeof raw !== 'object' || !('kind' in raw))
+        return [];
+    try {
+        if (raw.kind === 'feature') {
+            const segmentNameById = new Map();
+            for (const seg of state.segments)
+                segmentNameById.set(seg.id, seg.name);
+            const envNameByApiKey = new Map();
+            for (const env of state.environments)
+                envNameByApiKey.set(env.api_key, env.name);
+            const out = translateFeature(raw.data, state.report, {
+                envNameByApiKey,
+                segmentNameById,
+                tags: state.tags,
+            });
+            return [{ contents: JSON.stringify(out, null, 2), path: flagOutputPath(raw.data.feature.name) }];
+        }
+        const out = translateSegment(raw.data, state.report);
+        return [{ contents: JSON.stringify(out, null, 2), path: segmentOutputPath(raw.data.name) }];
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        state.report.add('skipped-config', change.key ?? 'unknown', `conversion failed: ${message}`);
+        return [];
+    }
+}
+/** Configs that could not be converted at all (matches LD `getSkippedConfigs`). */
+function getSkippedConfigsImpl() {
+    const skipped = state.report.byCategory('skipped-config');
+    if (skipped.length === 0)
+        return null;
+    return {
+        entries: skipped.map((n) => ({ key: n.key, reason: n.detail })),
+        total: skipped.length,
+    };
+}
+/**
+ * Per-flag rule-value coercions Flagsmith forced — every `enabled-false-non-boolean`
+ * + `cross-env-value-type-coerced` note is counted here so the existing
+ * "rule values were coerced" rollup in MIGRATION_REPORT.md surfaces them.
+ *
+ * The bookkeeping is per-Quonfig-env (the env-name the customer sees in the
+ * report and in the file tree). D-F1 notes carry `env "<api_key>"` in their
+ * detail string from `translate.ts`; we regex it out and map api_key →
+ * slugified env name via the captured environments. Notes that don't carry an
+ * env reference (cross-env D-F5; rare malformed details) bucket under a
+ * synthetic `_cross-env` key so they still surface but are visually distinct.
+ */
+function getCoercedSentinelsImpl() {
+    const enabledFalse = state.report.byCategory('enabled-false-non-boolean');
+    const crossEnv = state.report.byCategory('cross-env-value-type-coerced');
+    if (enabledFalse.length === 0 && crossEnv.length === 0)
+        return null;
+    const envSlugByApiKey = new Map();
+    for (const env of state.environments)
+        envSlugByApiKey.set(env.api_key, slugifyEnvName(env.name));
+    const byEnv = {};
+    let total = 0;
+    const addToEnv = (envKey, outputPath) => {
+        const env = byEnv[envKey] ?? {};
+        env[outputPath] = (env[outputPath] ?? 0) + 1;
+        byEnv[envKey] = env;
+        total += 1;
+    };
+    // D-F1: detail strings look like `... in env "<api_key>" ...` (env-default
+    // path), `... identity override "<id>" ...`, or `... segment override "<name>" ...`.
+    // Only the env-default flavor includes an api_key; the override flavors are
+    // implicitly all-envs (they fire once per override row, which is always tied
+    // to an env, but the detail doesn't surface it). For override rows the
+    // bucketing reflects what we can know: "all envs" (`_all-envs`).
+    for (const note of enabledFalse) {
+        const path = flagOutputPath(note.key);
+        const match = /env "([^"]+)"/.exec(note.detail);
+        if (match) {
+            const apiKey = match[1];
+            const slug = envSlugByApiKey.get(apiKey) ?? apiKey;
+            addToEnv(slug, path);
+        }
+        else {
+            // identity/segment override rows: surface under a synthetic bucket so
+            // the section still names the flag even when env attribution is lossy.
+            addToEnv('_all-envs', path);
+        }
+    }
+    // D-F5: cross-env divergence is a feature-wide finding — coerce target is
+    // string regardless of which env disagreed. Surface under a distinct bucket
+    // so the renderer doesn't show "0 from N envs" double-counting.
+    for (const note of crossEnv) {
+        addToEnv('_cross-env', flagOutputPath(note.key));
+    }
+    return { byEnv, total };
+}
+/**
+ * Currently no override sections are dropped due to env-id mismatch — Flagsmith
+ * has no equivalent of the Launch-source's archived/missing env case. Kept
+ * present so the report machinery's null-check still wires through.
+ */
+function getDroppedOverridesImpl() {
+    return null;
+}
+/** The full conversion report — every skip/drop/coerce note from this run. */
+export function getConversionReport() {
+    return state.report;
+}
+/**
+ * Walk every segment rule (recursively across nested `rules[]`) and collect
+ * every `condition.property` reference. These are the trait/context attribute
+ * names that downstream Quonfig callers will need to send at eval time
+ * (plan §5.5 / D-F6). The `'user.key'` Quonfig built-in is excluded — it's the
+ * caller-identity slot that's already required for any flag eval.
+ */
+function collectIdentityTraits() {
+    const traitToSegments = new Map();
+    const visitRule = (rule, segmentName) => {
+        for (const cond of rule.conditions ?? []) {
+            const prop = cond.property;
+            if (!prop || prop.length === 0)
+                continue;
+            if (prop === 'user.key')
+                continue;
+            const set = traitToSegments.get(prop) ?? new Set();
+            set.add(segmentName);
+            traitToSegments.set(prop, set);
+        }
+        for (const child of rule.rules ?? [])
+            visitRule(child, segmentName);
+    };
+    for (const segment of state.segments) {
+        for (const rule of segment.rules ?? [])
+            visitRule(rule, segment.name);
+    }
+    const sorted = new Map();
+    for (const [trait, segs] of [...traitToSegments.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        sorted.set(trait, [...segs].sort((a, b) => a.localeCompare(b)));
+    }
+    return sorted;
+}
+function getConversionNotesImpl() {
+    // Convert raw report notes — translate.ts embeds env api_keys in its
+    // detail strings; substitute them with the slugified user-facing env name
+    // so the report is readable to anyone who hasn't memorized Flagsmith's
+    // 22-character env api_keys. No-op when the api_key isn't in the env map.
+    const envSlugByApiKey = new Map();
+    for (const env of state.environments)
+        envSlugByApiKey.set(env.api_key, slugifyEnvName(env.name));
+    const decorate = (detail) => {
+        let out = detail.replaceAll(/env "([^"]+)"/g, (full, apiKey) => {
+            const slug = envSlugByApiKey.get(apiKey);
+            return slug ? `env "${slug}"` : full;
+        });
+        // Cross-env divergence details list api_keys directly as `apk=type` pairs
+        // (e.g. `Qr6Q...=int, iwz7...=string`) without surrounding quotes. Decode
+        // every known api_key in the detail to its slugified name.
+        for (const [apiKey, slug] of envSlugByApiKey) {
+            if (apiKey === slug)
+                continue;
+            out = out.replaceAll(apiKey, slug);
+        }
+        return out;
+    };
+    const notes = state.report.all().map((n) => ({ ...n, detail: decorate(n.detail) }));
+    // Synthesize rebucketed-rollout notes for every MULTIVARIATE feature so the
+    // dedicated "Users will be re-bucketed" section in MIGRATION_REPORT.md
+    // names each one (plan §5.4). Flagsmith and Quonfig hash buckets with
+    // different salts; identity-level assignments WILL change post-migration
+    // for every MV flag, regardless of whether the allocation has any per-env
+    // overrides.
+    for (const featureName of state.multivariateFeatures) {
+        notes.push({
+            category: 'rebucketed-rollout',
+            detail: 'multivariate feature; Flagsmith and Quonfig hash identities into buckets with different salts, so ' +
+                'individual identity → variation assignments will change after migration (the overall percentage allocation is preserved)',
+            key: featureName,
+        });
+    }
+    // Identity-trait references — pure FYI, no action required server-side, but
+    // every trait must be sent by the SDK caller at eval time or matching rules
+    // will silently miss. Plan §5.5 / D-F6.
+    const traitMap = collectIdentityTraits();
+    for (const [trait, segments] of traitMap) {
+        notes.push({
+            category: 'identity-traits-referenced',
+            detail: segments.length === 1
+                ? `referenced by segment "${segments[0]}" — your SDK callers must send this attribute on the evaluation context`
+                : `referenced by ${segments.length} segments (${segments.slice(0, 3).join(', ')}${segments.length > 3 ? ', …' : ''}) — your SDK callers must send this attribute on the evaluation context`,
+            key: trait,
+        });
+    }
+    return notes.length === 0 ? null : notes;
+}
+function getEnvironmentMapImpl() {
+    if (state.environments.length === 0)
+        return null;
+    const seen = new Set();
+    const entries = [];
+    for (const env of state.environments) {
+        const quonfigName = slugifyEnvName(env.name);
+        if (seen.has(quonfigName))
+            continue;
+        seen.add(quonfigName);
+        entries.push({ quonfigName, sourceName: env.name });
+    }
+    return entries.length === 0 ? null : entries;
+}
 export const flagsmithSource = {
-    // eslint-disable-next-line require-yield
-    async *fetchChanges() {
-        throw new NotYetImplementedError(SOURCE_NAME, 'fetchChanges');
-    },
-    listEnvironments() {
-        throw new NotYetImplementedError(SOURCE_NAME, 'listEnvironments');
+    fetchChanges() {
+        return fetchChangesImpl();
     },
+    getCoercedSentinels: getCoercedSentinelsImpl,
+    getConversionNotes: getConversionNotesImpl,
+    getDroppedOverrides: getDroppedOverridesImpl,
+    getEnvironmentMap: getEnvironmentMapImpl,
+    getSkippedConfigs: getSkippedConfigsImpl,
+    listEnvironments: listEnvironmentsImpl,
     name: SOURCE_NAME,
-    translate() {
-        throw new NotYetImplementedError(SOURCE_NAME, 'translate');
-    },
-    validateAuth() {
-        throw new NotYetImplementedError(SOURCE_NAME, 'validateAuth');
-    },
+    translate: translateImpl,
+    validateAuth: validateAuthImpl,
 };
+export function __resetFlagsmithSourceForTests() {
+    state.apiKey = null;
+    state.environments = [];
+    state.multivariateFeatures = [];
+    state.project = null;
+    state.projectId = resolveProjectId();
+    state.report = new ConversionReport();
+    state.segments = [];
+    state.tags = [];
+}

package/dist/migrate/sources/launchdarkly/api.d.ts

@@ -10,7 +10,7 @@
  * limit, so we program against the headers: back off on 429 using
  * `X-Ratelimit-Reset` (epoch-ms), pre-throttle on `X-Ratelimit-Global-Remaining`.
  */
-import type { LDFlag, LDSegment, LDSnapshot } from './types.js';
+import type { LDFlag, LDMember, LDSegment, LDSnapshot } from './types.js';
 export declare function setLaunchDarklyBaseUrl(url: string): void;
 export declare function selectLaunchDarklyBaseUrl(): string;
 export declare function applyLaunchDarklyBaseUrl(): void;
@@ -32,6 +32,16 @@ export declare class LaunchDarklyApiError extends Error {
 export declare function apiFetch(path: string, apiKey: string): Promise<unknown>;
 /** Probe used by `validateAuth` — a cheap authenticated call that 401s on a bad token. */
 export declare function fetchProjectEnvironments(apiKey: string, projectKey: string): Promise<string[]>;
+/**
+ * Same call as `fetchProjectEnvironments` but returns the full `{key, name}`
+ * pairs. The display `name` is needed for the MIGRATION_REPORT.md "Environment
+ * mapping table" — the bare key alone hides the customer-facing env label
+ * (qfg-1t7m).
+ */
+export declare function fetchProjectEnvironmentsDetailed(apiKey: string, projectKey: string): Promise<Array<{
+    key: string;
+    name: string;
+}>>;
 export declare function fetchContextKinds(apiKey: string, projectKey: string): Promise<string[]>;
 /**
  * Full per-environment flag targeting. `?summary=0` plus repeated `?env=`
@@ -48,6 +58,17 @@ export declare function fetchContextKinds(apiKey: string, projectKey: string): P
 export declare function fetchFlags(apiKey: string, projectKey: string, envKeys: string[], opts?: {
     archived?: boolean;
 }): Promise<LDFlag[]>;
+/**
+ * Account-wide member list — used to resolve flag `maintainerId` hex strings
+ * to readable emails for MIGRATION_REPORT.md (qfg-l8uz). Members live above
+ * projects in LD's hierarchy, so this call is project-independent.
+ *
+ * Some API tokens (project-scoped, or accounts with member visibility
+ * restrictions) can't read members and get a 403. Callers should treat the
+ * member map as best-effort and downgrade gracefully — the migration must not
+ * fail because we couldn't enrich the maintainer rollup.
+ */
+export declare function fetchMembers(apiKey: string): Promise<LDMember[]>;
 /** Segments are a per-environment resource — caller loops env keys and de-dupes. */
 export declare function fetchSegmentsForEnv(apiKey: string, projectKey: string, envKey: string): Promise<LDSegment[]>;
 /**

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

@@ -134,9 +134,18 @@ async function paginate(firstPath, apiKey) {
 }
 /** Probe used by `validateAuth` — a cheap authenticated call that 401s on a bad token. */
 export async function fetchProjectEnvironments(apiKey, projectKey) {
-    const items = await paginate(`/projects/${encodeURIComponent(projectKey)}/environments?limit=${PAGE_LIMIT}`, apiKey);
+    const items = await fetchProjectEnvironmentsDetailed(apiKey, projectKey);
     return items.map((e) => e.key);
 }
+/**
+ * Same call as `fetchProjectEnvironments` but returns the full `{key, name}`
+ * pairs. The display `name` is needed for the MIGRATION_REPORT.md "Environment
+ * mapping table" — the bare key alone hides the customer-facing env label
+ * (qfg-1t7m).
+ */
+export async function fetchProjectEnvironmentsDetailed(apiKey, projectKey) {
+    return paginate(`/projects/${encodeURIComponent(projectKey)}/environments?limit=${PAGE_LIMIT}`, apiKey);
+}
 export async function fetchContextKinds(apiKey, projectKey) {
     const data = (await apiFetch(`/projects/${encodeURIComponent(projectKey)}/context-kinds`, apiKey));
     return Array.isArray(data.items) ? data.items.map((k) => k.key) : [];
@@ -161,6 +170,19 @@ export async function fetchFlags(apiKey, projectKey, envKeys, opts = {}) {
         params.set('archived', 'true');
     return paginate(`/flags/${encodeURIComponent(projectKey)}?${params}`, apiKey);
 }
+/**
+ * Account-wide member list — used to resolve flag `maintainerId` hex strings
+ * to readable emails for MIGRATION_REPORT.md (qfg-l8uz). Members live above
+ * projects in LD's hierarchy, so this call is project-independent.
+ *
+ * Some API tokens (project-scoped, or accounts with member visibility
+ * restrictions) can't read members and get a 403. Callers should treat the
+ * member map as best-effort and downgrade gracefully — the migration must not
+ * fail because we couldn't enrich the maintainer rollup.
+ */
+export async function fetchMembers(apiKey) {
+    return paginate(`/members?limit=${PAGE_LIMIT}`, apiKey);
+}
 /** Segments are a per-environment resource — caller loops env keys and de-dupes. */
 export async function fetchSegmentsForEnv(apiKey, projectKey, envKey) {
     return paginate(`/segments/${encodeURIComponent(projectKey)}/${encodeURIComponent(envKey)}?limit=${PAGE_LIMIT}`, apiKey);

package/dist/migrate/sources/launchdarkly/translate.js

@@ -26,6 +26,26 @@ function slugifyEnvKey(key) {
         .replaceAll(/[^\da-z]+/g, '-')
         .replaceAll(/^-+|-+$/g, '');
 }
+/**
+ * Gather every prerequisite edge declared across all of a flag's environments
+ * and dedupe by parent key — the orphan-parent view is per-flag, not
+ * per-environment. First occurrence wins for the variation index when an
+ * unusual config gates on the same parent at different variations in different
+ * envs (rare; the typical case is identical edges in every env).
+ */
+function collectPrerequisiteEdges(flag) {
+    const seen = new Set();
+    const edges = [];
+    for (const envState of Object.values(flag.environments)) {
+        for (const prereq of envState.prerequisites ?? []) {
+            if (seen.has(prereq.key))
+                continue;
+            seen.add(prereq.key);
+            edges.push({ parentKey: prereq.key, variation: prereq.variation });
+        }
+    }
+    return edges;
+}
 export function flagOutputPath(key) {
     return `feature-flags/${normalizeKey(key)}.json`;
 }
@@ -54,9 +74,16 @@ export function translateFlag(flag, report) {
     };
     // clientSideAvailability: feature flags are always client-visible in Quonfig,
     // so `sendToClientSdk` is invalid on them — we cannot carry the dimension.
-    // Report the mobile-key drop rather than silently losing it.
+    // Split the drop by usingEnvironmentId co-state (qfg-iv69):
+    //  - usingEnvironmentId:true  → flag is still client-visible, pure rollup noise.
+    //  - usingEnvironmentId:false → flag was mobile-only, now server-only post-migration (must-fix).
     if (flag.clientSideAvailability?.usingMobileKey) {
-        report.add('dropped-mobile-key-availability', flag.key, `clientSideAvailability.usingMobileKey was true — Quonfig has one client-visibility bool, the mobile-key dimension is dropped`);
+        if (flag.clientSideAvailability.usingEnvironmentId) {
+            report.add('dropped-mobile-key-still-visible', flag.key, `clientSideAvailability.usingMobileKey was true; usingEnvironmentId was also true — flag remains client-visible via Quonfig's sendToClientSdk, the mobile-key dimension itself is dropped`);
+        }
+        else {
+            report.add('dropped-mobile-key-now-server-only', flag.key, `clientSideAvailability.usingMobileKey was true but usingEnvironmentId was false — flag was mobile-only in LaunchDarkly and will not reach mobile clients post-migration; rebuild client-side access by hand before cutover`);
+        }
     }
     if (flag.maintainerId || flag.maintainerTeamKey) {
         report.add('dropped-maintainer', flag.key, `maintainer ${flag.maintainerId ?? flag.maintainerTeamKey} dropped — Quonfig authorship lives in git history`);
@@ -64,6 +91,19 @@ export function translateFlag(flag, report) {
     if (flag.customProperties && Object.keys(flag.customProperties).length > 0) {
         report.add('dropped-custom-properties', flag.key, `customProperties (${Object.keys(flag.customProperties).join(', ')}) dropped — report-only in v1 (D6)`);
     }
+    // Prerequisites — dedupe across environments by parent key so a flag gated on
+    // the same parent in N environments emits one note, not N (qfg-nb4n). The
+    // detail spells out every parent's variation index plus a one-line remediation
+    // so a human knows exactly how to restore the gate; the structured
+    // `prerequisites` payload feeds the inverted orphan-parent view in the report.
+    const prereqEdges = collectPrerequisiteEdges(flag);
+    if (prereqEdges.length > 0) {
+        const parentList = prereqEdges.map((e) => `\`${e.parentKey}\` = variation ${e.variation}`).join(', ');
+        const detail = `evaluated independently of ${prereqEdges.length} parent${prereqEdges.length === 1 ? '' : 's'} ` +
+            `(${parentList}). To preserve the gate, add a leading rule matching the same parent state, ` +
+            `or wrap reads in app code — Quonfig v1 has no cross-flag dependency operator.`;
+        report.add('dropped-prerequisite', flag.key, detail, { prerequisites: prereqEdges });
+    }
     const variants = flag.variations.map((v) => {
         const variant = {
             value: toQuonfigValue(v.value, valueType),

package/dist/migrate/sources/launchdarkly/types.d.ts

@@ -173,6 +173,25 @@ export interface LDContextKindsResponse {
         name?: string;
     }>;
 }
+/**
+ * One row from `GET /members` — only the fields the migrator surfaces are
+ * typed. `_id` is what flag JSON references as `maintainerId`; `email` is the
+ * human-readable label we resolve into MIGRATION_REPORT.md.
+ */
+export interface LDMember {
+    _id: string;
+    email?: string;
+}
+/** `GET /members` — offset-paginated. */
+export interface LDMembersResponse {
+    _links?: {
+        next?: {
+            href: string;
+        };
+    };
+    items: LDMember[];
+    totalCount?: number;
+}
 /**
  * The full Phase-1 config snapshot — what the fetcher stitches together and
  * what `translate()` consumes. One of these is produced per migration run.