@quonfig/cli 0.0.48 → 0.0.50

package/dist/migrate/migration-report.js

@@ -43,14 +43,34 @@ const renderEnvironmentMap = (entries) => {
     const rows = sorted.map((e) => `| ${e.sourceName} | ${e.quonfigName} |`);
     return [header, '', '| Source | Quonfig |', '| --- | --- |', ...rows].join('\n');
 };
-const renderIdentifierMap = (map) => {
+const renderIdentifierMap = (map, maintainerMap) => {
     const header = '## Identifier map';
+    const sections = [];
     const keys = Object.keys(map);
-    if (keys.length === 0)
+    if (keys.length > 0) {
+        const sorted = [...keys].sort();
+        const rows = sorted.map((k) => `| \`${k}\` | \`${map[k]}\` |`);
+        sections.push(['### Legacy keys', '', '| Legacy key | Quonfig key |', '| --- | --- |', ...rows].join('\n'));
+    }
+    const maintainerIds = maintainerMap ? Object.keys(maintainerMap) : [];
+    if (maintainerIds.length > 0) {
+        const sorted = [...maintainerIds].sort();
+        const rows = sorted.map((id) => `| \`${id}\` | ${maintainerMap[id]} |`);
+        sections.push([
+            '### Maintainer IDs',
+            '',
+            `Resolved **${sorted.length}** maintainer ID${sorted.length === 1 ? '' : 's'} via the LaunchDarkly /members ` +
+                `endpoint. Use this table to read 'Dropped maintainer metadata' below — each \`maintainerId\` there maps to the ` +
+                `email here.`,
+            '',
+            '| maintainerId | email |',
+            '| --- | --- |',
+            ...rows,
+        ].join('\n'));
+    }
+    if (sections.length === 0)
         return `${header}\n\n${NONE}`;
-    const sorted = [...keys].sort();
-    const rows = sorted.map((k) => `| \`${k}\` | \`${map[k]}\` |`);
-    return [header, '', '| Legacy key | Quonfig key |', '| --- | --- |', ...rows].join('\n');
+    return [header, '', ...sections].join('\n\n');
 };
 const renderDroppedOverrides = (dropped) => {
     if (!dropped || dropped.total === 0)
@@ -138,13 +158,96 @@ const CONVERSION_NOTE_HEADINGS = {
     'dropped-custom-properties': 'Dropped custom properties',
     'dropped-experiment-metadata': 'Dropped experiment metadata',
     'dropped-maintainer': 'Dropped maintainer metadata',
-    'dropped-mobile-key-availability': 'Dropped mobile-key availability',
+    'dropped-mobile-key-now-server-only': 'Dropped mobile-key availability (now server-only)',
+    'dropped-mobile-key-still-visible': 'Dropped mobile-key availability (still client-visible)',
     'dropped-prerequisite': 'Dropped prerequisites',
     'dropped-private-attribute': 'Dropped private attributes',
     'individual-target-as-rule': 'Individual targets converted to rules',
     'skipped-rule': 'Skipped rules (unsupported operators)',
     'unexportable-segment-membership': 'Unexportable segment membership',
 };
+const SIGNAL_SPECS = {
+    'dropped-mobile-key-now-server-only': {
+        render: (count, keys) => `**${count} flag${count === 1 ? '' : 's'} ${count === 1 ? 'will' : 'will'} stop reaching mobile clients** ` +
+            `(${keys.map((k) => `\`${k}\``).join(', ')}). LaunchDarkly had \`usingMobileKey:true\` with ` +
+            `\`usingEnvironmentId:false\` — these were mobile-only and won't be visible to mobile SDKs post-migration. ` +
+            `Rebuild client-side access by hand before cutover.`,
+    },
+    'dropped-prerequisite': {
+        render: (count, keys) => `**${count} flag${count === 1 ? '' : 's'} lost cross-flag dependencies** (${keys.map((k) => `\`${k}\``).join(', ')}). ` +
+            `The Quonfig copy now serves its variations independently of its parent flag. ` +
+            `Review §'Dropped prerequisites' below.`,
+    },
+    'rebucketed-rollout': {
+        render: (count) => `**${count} flag${count === 1 ? '' : 's'} will re-bucket users.** Coordinate comms or drain affected ` +
+            `rollouts — see 'Users will be re-bucketed' below.`,
+    },
+    'skipped-rule': {
+        render: (count, keys) => `**${count} flag${count === 1 ? '' : 's'} had rules skipped** (${keys.map((k) => `\`${k}\``).join(', ')}) — ` +
+            `a clause used an unsupported operator. Rebuild the rule by hand before cutover.`,
+    },
+    'unexportable-segment-membership': {
+        render: (count, keys) => `**${count} segment${count === 1 ? '' : 's'} ${count === 1 ? 'has' : 'have'} missing membership** (${keys
+            .map((k) => `\`${k}\``)
+            .join(', ')}). Re-author or sync from your IdP before cutover.`,
+    },
+};
+const SIGNAL_ORDER = [
+    'dropped-mobile-key-now-server-only',
+    'dropped-prerequisite',
+    'rebucketed-rollout',
+    'unexportable-segment-membership',
+    'skipped-rule',
+];
+const MAX_EXAMPLE_KEYS = 3;
+const groupKeysByCategory = (notes) => {
+    const map = new Map();
+    for (const note of notes) {
+        const list = map.get(note.category) ?? [];
+        list.push(note.key);
+        map.set(note.category, list);
+    }
+    return map;
+};
+const renderBeforeYouCutOver = (notes) => {
+    if (!notes || notes.length === 0)
+        return null;
+    const byCategory = groupKeysByCategory(notes);
+    const items = [];
+    for (const category of SIGNAL_ORDER) {
+        const keys = byCategory.get(category);
+        if (!keys || keys.length === 0)
+            continue;
+        const sortedKeys = [...keys].sort((a, b) => a.localeCompare(b));
+        const example = sortedKeys.slice(0, MAX_EXAMPLE_KEYS);
+        const truncated = sortedKeys.length > MAX_EXAMPLE_KEYS ? [...example, '…'] : example;
+        items.push(SIGNAL_SPECS[category].render(sortedKeys.length, truncated));
+    }
+    if (items.length === 0)
+        return null;
+    const lines = [
+        '## Before you cut over',
+        '',
+        `${items.length} thing${items.length === 1 ? ' needs' : 's need'} a human decision before flipping the SDK:`,
+        '',
+    ];
+    items.forEach((item, idx) => {
+        lines.push(`${idx + 1}. ${item}`);
+    });
+    const ignoreParts = [];
+    const maintainerCount = byCategory.get('dropped-maintainer')?.length ?? 0;
+    if (maintainerCount > 0) {
+        ignoreParts.push(`dropped maintainer metadata (${maintainerCount} entries — git authorship replaces it)`);
+    }
+    const mobileKeyCount = byCategory.get('dropped-mobile-key-still-visible')?.length ?? 0;
+    if (mobileKeyCount > 0) {
+        ignoreParts.push(`dropped mobile-key availability (${mobileKeyCount} entries — all still client-visible via usingEnvironmentId)`);
+    }
+    if (ignoreParts.length > 0) {
+        lines.push('', `You can ignore: ${ignoreParts.join(', ')}.`);
+    }
+    return lines.join('\n');
+};
 const renderRebucketedRollouts = (notes) => {
     const rollouts = (notes ?? []).filter((n) => n.category === 'rebucketed-rollout');
     if (rollouts.length === 0)
@@ -163,7 +266,77 @@ const renderRebucketedRollouts = (notes) => {
     }
     return lines.join('\n');
 };
-const renderConversionNotes = (notes) => {
+/**
+ * Categories that are pure informational noise (drowned out the signal in the
+ * 172-note LD migration report — see qfg-ve5w). Render as a 1-line rollup +
+ * collapsible `<details>` block instead of N top-level bullets.
+ */
+const COLLAPSED_CATEGORIES = {
+    'dropped-maintainer': (count) => `${count} flag${count === 1 ? '' : 's'} had a maintainer ID dropped. Intentional — Quonfig authorship lives in ` +
+        `git history. No action required.`,
+    'dropped-mobile-key-still-visible': (count) => `${count} flag${count === 1 ? '' : 's'} had \`usingMobileKey:true\` collapsed into the single \`sendToClientSdk\` ` +
+        `boolean. Each flag is still client-visible via \`usingEnvironmentId\`. No action required.`,
+};
+/**
+ * Render the `dropped-prerequisite` subsection (qfg-nb4n): one multi-line entry
+ * per child flag with nested parent bullets naming each variation index, plus
+ * a trailing inverted view that lists each orphaned parent and its downstream
+ * consumers. Returns the rendered lines (without the `### …` header — that is
+ * pushed by the caller so the section grouping stays consistent).
+ */
+const renderDroppedPrerequisiteBody = (notes) => {
+    const sorted = [...notes].sort((a, b) => a.key.localeCompare(b.key));
+    const lines = [];
+    // Forward view: child flag → parents.
+    for (const note of sorted) {
+        const edges = note.prerequisites;
+        if (!edges || edges.length === 0) {
+            // Backward-compat fallback when a future caller forgets the structured payload.
+            lines.push(`- \`${note.key}\` — ${note.detail}`);
+            continue;
+        }
+        lines.push(`- \`${note.key}\` evaluated independently of its ${edges.length} parent${edges.length === 1 ? '' : 's'}:`);
+        for (const edge of edges) {
+            lines.push(`  - was gated on \`${edge.parentKey}\` = variation ${edge.variation}`);
+        }
+        lines.push('  To preserve the gate, add a leading rule matching the same parent state, or wrap reads in app code.');
+    }
+    // Inverted view: parent → children that depended on it.
+    const parentToChildren = new Map();
+    for (const note of sorted) {
+        for (const edge of note.prerequisites ?? []) {
+            const set = parentToChildren.get(edge.parentKey) ?? new Set();
+            set.add(note.key);
+            parentToChildren.set(edge.parentKey, set);
+        }
+    }
+    if (parentToChildren.size > 0) {
+        lines.push('', '#### Orphaned parent flags (inverted view)', '');
+        const parents = [...parentToChildren.keys()].sort((a, b) => a.localeCompare(b));
+        for (const parent of parents) {
+            const children = [...(parentToChildren.get(parent) ?? [])].sort((a, b) => a.localeCompare(b));
+            const childList = children.map((c) => `\`${c}\``).join(', ');
+            lines.push(`- **\`${parent}\`** is now an orphaned dependency. Downstream flags that depended on it: ${childList}.`);
+        }
+    }
+    return lines;
+};
+/**
+ * qfg-l8uz: substitute every `<hex maintainerId>` in a dropped-maintainer
+ * detail with `<id> (<email>)` so the per-flag rollup reads as a human label
+ * instead of an opaque hex string. No-op when the map is empty/missing or the
+ * ID isn't in it (team-key drops, partial member visibility) — the unsubstituted
+ * line is still informative.
+ */
+const decorateMaintainerDetail = (detail, maintainerMap) => {
+    if (!maintainerMap)
+        return detail;
+    return detail.replaceAll(/[\da-f]{24}/g, (match) => {
+        const email = maintainerMap[match];
+        return email ? `${match} (${email})` : match;
+    });
+};
+const renderConversionNotes = (notes, maintainerMap) => {
     // `skipped-config` (own section) and `rebucketed-rollout` (own section) are
     // rendered elsewhere — everything else is grouped by category here.
     const grouped = (notes ?? []).filter((n) => n.category !== 'rebucketed-rollout' && n.category !== 'skipped-config');
@@ -182,12 +355,102 @@ const renderConversionNotes = (notes) => {
             continue;
         lines.push('', `### ${CONVERSION_NOTE_HEADINGS[category]}`, '');
         const sorted = [...forCategory].sort((a, b) => a.key.localeCompare(b.key));
+        const rollup = COLLAPSED_CATEGORIES[category];
+        if (rollup) {
+            lines.push(rollup(sorted.length), '', '<details><summary>Per-flag list</summary>', '');
+            for (const note of sorted) {
+                const detail = category === 'dropped-maintainer' ? decorateMaintainerDetail(note.detail, maintainerMap) : note.detail;
+                lines.push(`- \`${note.key}\` — ${detail}`);
+            }
+            lines.push('', '</details>');
+            continue;
+        }
+        if (category === 'dropped-prerequisite') {
+            lines.push(...renderDroppedPrerequisiteBody(sorted));
+            continue;
+        }
         for (const note of sorted) {
             lines.push(`- \`${note.key}\` — ${note.detail}`);
         }
     }
     return lines.join('\n');
 };
+/**
+ * Maps each lossy conversion-note category to a Follow-up checklist bucket plus
+ * a 1-line remediation hint. Categories not listed here (or `skipped-config` /
+ * housekeeping categories like `dropped-maintainer`) are intentionally not
+ * surfaced as checklist items — they get their own dedicated report sections
+ * or are pure-metadata losses that don't require human follow-up.
+ */
+const FOLLOW_UP_BUCKETS = {
+    'dropped-mobile-key-now-server-only': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — flag was mobile-only in LaunchDarkly (usingMobileKey:true, usingEnvironmentId:false) and will not reach mobile SDKs after migration; restore client-side access by hand.`,
+    },
+    'dropped-prerequisite': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — restore the dropped prerequisite gate manually; Quonfig v1 has no cross-flag dependency operator.`,
+    },
+    'individual-target-as-rule': {
+        bucket: 'reviewPostCutover',
+        hint: (key) => `\`${key}\` — individual user targets are now a leading rule; the LaunchDarkly targets pane affordance is gone.`,
+    },
+    'rebucketed-rollout': {
+        bucket: 'reviewPostCutover',
+        hint: (key) => `\`${key}\` — percentage rollout will re-bucket users post-migration; communicate before cutover.`,
+    },
+    'skipped-rule': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — a rule clause used an unsupported operator and was skipped; rebuild the rule by hand.`,
+    },
+    'unexportable-segment-membership': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — segment shell migrated but membership is empty (LD big/synced segment); repopulate members before cutover.`,
+    },
+};
+/**
+ * Folds conversion notes into a followUp checklist. De-duplicates by hint
+ * string so a flag with two dropped prerequisites doesn't produce two
+ * identical checkbox lines.
+ */
+export const deriveFollowUpFromConversionNotes = (base, notes) => {
+    const mustFix = new Set(base.mustFixBeforeCutover);
+    const review = new Set(base.reviewPostCutover);
+    for (const note of notes ?? []) {
+        const mapping = FOLLOW_UP_BUCKETS[note.category];
+        if (!mapping)
+            continue;
+        const line = mapping.hint(note.key);
+        if (mapping.bucket === 'mustFixBeforeCutover')
+            mustFix.add(line);
+        else
+            review.add(line);
+    }
+    return { mustFixBeforeCutover: [...mustFix], reviewPostCutover: [...review] };
+};
+/**
+ * Static, content-stable appendix describing v1 behavioral gaps between
+ * LaunchDarkly and Quonfig (plan §5.4 / qfg-ox7m). Documentation, not data —
+ * does not vary across runs. Rendered only when source === 'launchdarkly'.
+ */
+const LAUNCHDARKLY_BEHAVIORAL_DIFFERENCES_APPENDIX = [
+    '## Behavioral differences post-cutover (independent of this import)',
+    '',
+    '- LaunchDarkly evaluates targets/contextTargets *before* rules. Quonfig has no',
+    '  individual-target primitive; user/context targets are now a leading PROP_IS_ONE_OF',
+    '  rule. Adding/removing individuals is now a config edit (qfg set / web UI), not a',
+    '  separate targeting UI pane.',
+    "- LaunchDarkly's 'off' toggle disappears. A flag is on iff at least one rule",
+    '  matches; there is no global kill-switch unless you author one as a top rule.',
+    '- offVariation does not exist in Quonfig. The off-state behavior of any flag',
+    '  that was on=false in LD has been baked into a single ALWAYS_TRUE rule serving',
+    '  that variation.',
+    '- Mobile SDK keys: LaunchDarkly distinguished mobile-key vs environment-id',
+    '  availability. Quonfig has one sendToClientSdk bool — your iOS/Android and',
+    '  browser-JS SDKs now share the same client-visibility setting.',
+    '- Maintainer is no longer a field on flags. `git log path/to/flag.json` is the',
+    '  new source of truth.',
+].join('\n');
 const renderFollowUp = (followUp) => {
     const must = followUp.mustFixBeforeCutover.length === 0
         ? NONE
@@ -212,7 +475,11 @@ export const buildMigrationReport = (data) => {
     if (data.dryRun) {
         sections.push('> **DRY RUN** — no files were written to the workspace during this run.');
     }
-    sections.push(`# Migration Report (from ${data.source})`, `_Reflects only the changes produced by this run. Re-running overwrites this file._`, renderCounts(data.counts), renderCleanMappings(data.cleanMappings), renderLossyMappings(data.lossyMappings), renderUnsupported(data.unsupportedFeatures), renderEnvironmentMap(data.environmentMap), renderIdentifierMap(data.identifierMap));
+    sections.push(`# Migration Report (from ${data.source})`, `_Reflects only the changes produced by this run. Re-running overwrites this file._`);
+    const beforeYouCutOver = renderBeforeYouCutOver(data.conversionNotes);
+    if (beforeYouCutOver !== null)
+        sections.push(beforeYouCutOver);
+    sections.push(renderCounts(data.counts), renderCleanMappings(data.cleanMappings), renderLossyMappings(data.lossyMappings), renderUnsupported(data.unsupportedFeatures), renderEnvironmentMap(data.environmentMap), renderIdentifierMap(data.identifierMap, data.maintainerMap));
     const dropped = renderDroppedOverrides(data.droppedOverrides);
     if (dropped !== null)
         sections.push(dropped);
@@ -228,10 +495,13 @@ export const buildMigrationReport = (data) => {
     const rebucketed = renderRebucketedRollouts(data.conversionNotes);
     if (rebucketed !== null)
         sections.push(rebucketed);
-    const conversionNotes = renderConversionNotes(data.conversionNotes);
+    const conversionNotes = renderConversionNotes(data.conversionNotes, data.maintainerMap);
     if (conversionNotes !== null)
         sections.push(conversionNotes);
     sections.push(renderFollowUp(data.followUp));
+    if (data.source === 'launchdarkly') {
+        sections.push(LAUNCHDARKLY_BEHAVIORAL_DIFFERENCES_APPENDIX);
+    }
     return sections.join('\n\n') + '\n';
 };
 export const migrationReportPath = (outputDir) => path.join(outputDir, 'MIGRATION_REPORT.md');

package/dist/migrate/push-to-cloud.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { buildAuditFinalCommit, buildAuditPerChangeCommits, buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles, } from './local-write.js';
-import { writeMigrationReport } from './migration-report.js';
+import { deriveFollowUpFromConversionNotes, writeMigrationReport } from './migration-report.js';
 import { cloneAndStackPush, } from '../util/clone-and-stack-push.js';
 import { formatResult, validateWorkspace } from '../verify/validate.js';
 /**
@@ -95,6 +95,8 @@ export const pushMigrationToCloud = async (opts) => {
                     acc.duplicateResolutions =
                         resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
                     const conversionNotes = opts.source.getConversionNotes?.() ?? null;
+                    const environmentMap = opts.source.getEnvironmentMap?.() ?? null;
+                    const maintainerMap = opts.source.getMaintainerMap?.() ?? null;
                     const skippedTotal = (acc.skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
                     const environmentsCount = opts.environments?.length ?? 0;
                     const counts = buildMigrationCounts(livePaths, environmentsCount, skippedTotal);
@@ -102,10 +104,13 @@ export const pushMigrationToCloud = async (opts) => {
                     const reportData = {
                         ...opts.reportData,
                         counts,
+                        ...(environmentMap && environmentMap.length > 0 ? { environmentMap } : {}),
+                        followUp: deriveFollowUpFromConversionNotes(opts.reportData.followUp, conversionNotes ?? undefined),
                         ...(acc.coercedSentinels ? { coercedSentinels: acc.coercedSentinels } : {}),
                         ...(conversionNotes && conversionNotes.length > 0 ? { conversionNotes } : {}),
                         ...(acc.droppedOverrides ? { droppedOverrides: acc.droppedOverrides } : {}),
                         ...(acc.duplicateResolutions ? { duplicateResolutions: acc.duplicateResolutions } : {}),
+                        ...(maintainerMap && Object.keys(maintainerMap).length > 0 ? { maintainerMap } : {}),
                         ...(acc.skippedConfigs ? { skippedConfigs: acc.skippedConfigs } : {}),
                     };
                     writeMigrationReport(dir, reportData);

package/dist/migrate/quonfig-target/report.d.ts

@@ -26,8 +26,18 @@ export type ConversionNoteCategory =
  | 'dropped-maintainer'
 /** `customProperties` dropped — report-only in v1 (D6). */
  | 'dropped-custom-properties'
-/** clientSideAvailability mobile-key dimension dropped. */
- | 'dropped-mobile-key-availability'
+/**
+ * `usingMobileKey:true` collapsed into Quonfig's single client-visibility bool,
+ * but the flag is still client-visible because `usingEnvironmentId` is also true.
+ * No action required — pure rollup noise.
+ */
+ | 'dropped-mobile-key-still-visible'
+/**
+ * `usingMobileKey:true` but `usingEnvironmentId:false` — the flag was
+ * mobile-only in LD and will no longer reach mobile clients after migration.
+ * Must-fix before cutover.
+ */
+ | 'dropped-mobile-key-now-server-only'
 /** A percentage rollout that will re-bucket users post-migration (plan §5.4). */
  | 'rebucketed-rollout'
 /** A big/synced segment whose membership is not exportable via REST. */
@@ -40,6 +50,15 @@ export interface ConversionNote {
     detail: string;
     /** Source key the note is about (flag or segment key). */
     key: string;
+    /**
+     * Structured prereq edges on `dropped-prerequisite` notes — the renderer uses
+     * this to produce the inverted "orphaned parent → downstream consumers" view
+     * (qfg-nb4n). Absent on every other category.
+     */
+    prerequisites?: Array<{
+        parentKey: string;
+        variation: number;
+    }>;
 }
 /**
  * Collects conversion notes during a migration run. A provider source holds
@@ -49,7 +68,12 @@ export interface ConversionNote {
 export declare class ConversionReport {
     private readonly notes;
     get size(): number;
-    add(category: ConversionNoteCategory, key: string, detail: string): void;
+    add(category: ConversionNoteCategory, key: string, detail: string, extras?: {
+        prerequisites?: Array<{
+            parentKey: string;
+            variation: number;
+        }>;
+    }): void;
     /** All notes, in insertion order. */
     all(): ConversionNote[];
     /** Notes of one category, in insertion order. */

package/dist/migrate/quonfig-target/report.js

@@ -19,8 +19,11 @@ export class ConversionReport {
     get size() {
         return this.notes.length;
     }
-    add(category, key, detail) {
-        this.notes.push({ category, detail, key });
+    add(category, key, detail, extras) {
+        const note = { category, detail, key };
+        if (extras?.prerequisites)
+            note.prerequisites = extras.prerequisites;
+        this.notes.push(note);
     }
     /** All notes, in insertion order. */
     all() {

package/dist/migrate/quonfig-target/ruleset.js

@@ -155,11 +155,10 @@ export function collapseEnvironment(env, ctx) {
         return [{ criteria: [ALWAYS_TRUE], value: variationValue(env.offVariation ?? 0, ctx) }];
     }
     const rules = [];
-    if (env.prerequisites && env.prerequisites.length > 0) {
-        ctx.report.add('dropped-prerequisite', ctx.sourceKey, `${env.prerequisites.length} prerequisite(s) dropped (${env.prerequisites
-            .map((p) => p.key)
-            .join(', ')}) — Quonfig has no cross-flag dependency operator`);
-    }
+    // Prerequisites are dropped (no cross-flag dependency operator in Quonfig v1)
+    // but their reporting is owned by the caller (translateFlag), which dedupes
+    // across environments and emits one enriched note per child flag (qfg-nb4n).
+    // collapseEnvironment intentionally stays silent here.
     // Individual + context targets evaluate before rules in LaunchDarkly, so
     // they become leading rules. Lossy: the LD UI affordance is gone (plan §5.4).
     const allTargets = [...(env.targets ?? []), ...(env.contextTargets ?? [])];
@@ -177,7 +176,10 @@ export function collapseEnvironment(env, ctx) {
             ],
             value: variationValue(target.variation, ctx),
         });
-        ctx.report.add('individual-target-as-rule', ctx.sourceKey, `${target.values.length} ${kind} target(s) converted to a leading PROP_IS_ONE_OF rule on ${kind}.key`);
+        ctx.report.add('individual-target-as-rule', ctx.sourceKey, `${target.values.length} ${kind} key(s) inlined into a leading PROP_IS_ONE_OF rule on ${kind}.key. ` +
+            `**Trade-off:** you lost the LD 'targets' UI pane — adding/removing an individual now requires a ` +
+            `config edit (qfg set / web UI), not a separate UI. If this was used for beta-list-style toggling, ` +
+            `consider authoring a \`beta_user\` context attribute instead.`);
     }
     for (const rule of env.rules ?? []) {
         const value = rule.rollout === undefined ? variationValue(rule.variation ?? 0, ctx) : rolloutToWeightedValues(rule.rollout, ctx);

package/dist/migrate/source.d.ts

@@ -12,6 +12,17 @@ export interface QuonfigFile {
     deleted?: boolean;
     path: string;
 }
+/**
+ * One row of the "Environment mapping table" in MIGRATION_REPORT.md. Sources
+ * implement `getEnvironmentMap()` to expose the source-name → Quonfig-name
+ * pairs they translated; the report renderer just formats the rows.
+ */
+export interface EnvironmentMapEntry {
+    /** The Quonfig-side environment name (slugified key). */
+    quonfigName: string;
+    /** The user-facing source-system name (e.g. LD env display name). */
+    sourceName: string;
+}
 export interface DroppedOverrideSummary {
     /** Per-envId → per-output-path count of dropped override sections. */
     byEnv: Record<string, Record<string, number>>;
@@ -106,6 +117,22 @@ export interface MigrationSource {
      * report so customers can review the loss.
      */
     getDroppedOverrides?(): DroppedOverrideSummary | null;
+    /**
+     * qfg-1t7m: source-name → Quonfig-name pairs for the "Environment mapping table"
+     * section of MIGRATION_REPORT.md. Returns the rows the source actually
+     * translated this run; callers thread these into report data. Sources that
+     * don't expose user-facing env names omit this and the table renders `_(none)_`.
+     */
+    getEnvironmentMap?(): EnvironmentMapEntry[] | null;
+    /**
+     * qfg-l8uz: maintainerId → email pairs for the report's "Identifier map"
+     * section. Sources that fetch a member directory (e.g. LD's /members) expose
+     * the lookup here so the report renderer can swap opaque IDs for readable
+     * emails and decorate the `dropped-maintainer` rollup. Null when the source
+     * couldn't fetch members (auth scope, hidden member data) or has none to
+     * surface — the rest of the report still renders.
+     */
+    getMaintainerMap?(): null | Record<string, string>;
     /**
      * Optional post-translate accumulator. Returns any configs that translate() soft-
      * skipped due to invalid source data (e.g. variant/valueType mismatch). Null when

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);