@santi020k/lumen 3.0.0 → 4.0.0

package/dist/version-migration-source.js

@@ -0,0 +1,281 @@
+import { scriptRegexRanges } from './source-script-ranges.js';
+import { findBalancedEnd, findImportStatements, findMarkupTagEnd, getMarkupStart, getTagNameEnd, parseMarkupAttributes, parseNamedImports } from './v2-migration.js';
+import { migrateLumenV4Source } from './v4-migration.js';
+const layoutGaps = { lg: 'xl', md: 'group', xl: '2xl' };
+const reviewComponents = new Map([
+    ['Card', 'Review padding, child margins, media clipping and footer wrapping in the rendered application.'],
+    ['Container', 'Review responsive gutters; use --ui-container-gutter only when a fixed gutter is intentional.'],
+    ['Prose', 'Review reading-block margins and remove verified compensating offsets.'],
+    ['Typography', 'Review first/last child margins and heading spacing.'],
+    ['Button', 'Review direct-child selectors for .ui-button__content and loading/disabled descendants.'],
+    ['DatePicker', 'Associate labels with the focusable trigger; the native input ID now ends in -native.'],
+    ['Combobox', 'Review focus assumptions; the editable input retains focus with aria-activedescendant.'],
+    ['Dialog', 'Review pending-state dismissal policy and focus restoration.'],
+    ['DataTable', 'Use controlled sort/onSortChange and sortMode="manual" for server-paginated React results.'],
+    ['BarChart', 'Review stable unique X identities, label formatting and application-owned chart patches.'],
+    ['LineChart', 'Review stable unique X identities, label formatting and application-owned chart patches.']
+]);
+const visualSizeComponents = new Set(['Select', 'PhoneInput', 'Segmented']);
+const elementNames = new Map([
+    ['lumen-select', 'Select'],
+    ['lumen-phone-input', 'PhoneInput'],
+    ['lumen-segmented', 'Segmented'],
+    ['lumen-stack', 'Stack'],
+    ['lumen-grid', 'Grid'],
+    ...[...reviewComponents.keys()].map(name => [
+        `lumen-${name.replaceAll(/[A-Z]/gu, (letter, offset) => `${offset ? '-' : ''}${letter.toLowerCase()}`)}`,
+        name
+    ])
+]);
+const lineStarts = (source) => {
+    const starts = [0];
+    for (let index = 0; index < source.length; index += 1) {
+        if (source[index] === '\n')
+            starts.push(index + 1);
+    }
+    return starts;
+};
+const location = (starts, offset) => {
+    let low = 0;
+    let high = starts.length;
+    while (low + 1 < high) {
+        const middle = Math.floor((low + high) / 2);
+        if ((starts[middle] ?? 0) <= offset)
+            low = middle;
+        else
+            high = middle;
+    }
+    return { column: offset - (starts[low] ?? 0) + 1, line: low + 1 };
+};
+const skipQuoted = (source, start) => {
+    const quote = source[start];
+    let cursor = start + 1;
+    while (cursor < source.length) {
+        if (source[cursor] === '\\')
+            cursor += 2;
+        else if (source[cursor++] === quote)
+            return cursor;
+    }
+    return source.length;
+};
+const skipNonMarkup = (source, cursor, script) => {
+    const comment = [['<!--', '-->'], ...(script ? [['/*', '*/'], ['//', '\n']] : [])]
+        .find(([opening]) => opening !== undefined && source.startsWith(opening, cursor));
+    const ending = comment?.[1];
+    if (ending) {
+        const end = source.indexOf(ending, cursor + 2);
+        return end < 0 ? source.length : end + ending.length;
+    }
+    if (script && ['"', '\'', '`'].includes(source[cursor] ?? ''))
+        return skipQuoted(source, cursor);
+    return cursor;
+};
+const realImportStarts = (source, exclusions) => {
+    const offsets = new Set();
+    let cursor = 0;
+    while (cursor < source.length) {
+        const next = exclusions.get(cursor) ?? skipNonMarkup(source, cursor, true);
+        if (next !== cursor) {
+            cursor = next;
+            continue;
+        }
+        if (source.startsWith('import', cursor))
+            offsets.add(cursor);
+        cursor += 1;
+    }
+    return offsets;
+};
+const collectComponents = (source, exclusions) => {
+    const components = new Map();
+    const offsets = realImportStarts(source, exclusions);
+    for (const module of ['@santi020k/lumen-astro', '@santi020k/lumen-react']) {
+        for (const statement of findImportStatements(source, module)) {
+            if (!offsets.has(statement.start))
+                continue;
+            const imports = parseNamedImports(statement.clause);
+            if (!imports?.complete)
+                continue;
+            for (const item of imports.imports) {
+                if (!item.typeOnly)
+                    components.set(item.local, item.imported);
+            }
+        }
+    }
+    return components;
+};
+const readTag = (source, cursor) => {
+    if (source[cursor] !== '<' || !/[A-Za-z]/u.test(source[cursor + 1] ?? ''))
+        return undefined;
+    const nameEnd = getTagNameEnd(source, cursor + 1);
+    return { start: cursor, nameEnd, name: source.slice(cursor + 1, nameEnd), end: findMarkupTagEnd(source, nameEnd) };
+};
+const literalValue = (attribute) => {
+    if (attribute.valueKind === 'literal')
+        return attribute.value;
+    const expression = attribute.value;
+    if (expression && /^(['"])[a-z0-9-]+\1$/u.test(expression))
+        return expression.slice(1, -1);
+    return undefined;
+};
+const inspectGap = (context, tag) => {
+    const attributes = parseMarkupAttributes(context.source, tag.nameEnd, tag.end);
+    const gaps = attributes.filter(attribute => attribute.name === 'gap');
+    const gap = gaps[0];
+    if (!gap)
+        return;
+    const value = literalValue(gap);
+    const ambiguous = gaps.length > 1 || context.source.slice(tag.nameEnd, tag.end).includes('...');
+    if (!value || ambiguous) {
+        context.manualReview.push(context.finding(gap.start, 'layout-gap', `${tag.name}: review dynamic, duplicated or spread gap values; v3 md/lg/xl map to group/xl/2xl.`));
+        return;
+    }
+    const replacement = Object.hasOwn(layoutGaps, value) ? layoutGaps[value] : undefined;
+    if (!replacement)
+        return;
+    const offset = context.source.slice(gap.start, gap.end).lastIndexOf(value);
+    context.edits.push({ start: gap.start + offset, end: gap.start + offset + value.length, replacement });
+    context.changes.push(context.finding(gap.start, 'layout-gap', `${tag.name}: preserve v3 gap ${value} with ${replacement}.`));
+};
+const visualSizes = new Set(['default', 'lg', 'sm']);
+const isNumericSize = (attribute) => {
+    const value = attribute.valueKind === 'expression' ? attribute.value : literalValue(attribute);
+    return /^\d+$/u.test(value ?? '');
+};
+const isKnownVisualSize = (value, component) => value !== undefined && (visualSizes.has(value) || (component === 'Select' && value === 'md'));
+const reportVisualSizeReview = (context, tag, name, offset = tag.start) => {
+    context.manualReview.push(context.finding(offset, 'control-size', `${tag.name}: review dynamic, duplicated or spread size props; visual sizing uses ${name}, and native Select size remains numeric.`));
+};
+const isAmbiguousVisualSize = (attributes, count, name, spread) => spread || count !== 1 || attributes.some(attribute => attribute.name === name);
+const isNativeSelectSize = (component, size, ambiguous) => component === 'Select' && isNumericSize(size) && !ambiguous;
+const inspectVisualSize = (context, tag, component) => {
+    const attributes = parseMarkupAttributes(context.source, tag.nameEnd, tag.end);
+    const sizes = attributes.filter(attribute => attribute.name === 'size');
+    const size = sizes[0];
+    const spread = context.source.slice(tag.nameEnd, tag.end).includes('...');
+    const visualName = tag.name.startsWith('lumen-') ? 'visual-size' : 'visualSize';
+    if (!size) {
+        if (spread)
+            reportVisualSizeReview(context, tag, visualName);
+        return;
+    }
+    const ambiguous = isAmbiguousVisualSize(attributes, sizes.length, visualName, spread);
+    const value = literalValue(size);
+    if (isNativeSelectSize(component, size, ambiguous))
+        return;
+    if (ambiguous || !isKnownVisualSize(value, component)) {
+        reportVisualSizeReview(context, tag, visualName, size.start);
+        return;
+    }
+    context.edits.push({ start: size.start, end: size.start + 'size'.length, replacement: visualName });
+    if (value === 'md') {
+        const offset = context.source.slice(size.start, size.end).lastIndexOf(value);
+        context.edits.push({ start: size.start + offset, end: size.start + offset + value.length, replacement: 'default' });
+    }
+    context.changes.push(context.finding(size.start, 'control-size', `${tag.name}: move visual size ${value} to ${visualName}.`));
+};
+const inspectTag = (context, tag) => {
+    const component = context.components.get(tag.name) ?? elementNames.get(tag.name);
+    if (!component)
+        return;
+    const message = reviewComponents.get(component);
+    if (message)
+        context.manualReview.push(context.finding(tag.start, 'component-review', `${tag.name}: ${message}`));
+    if (component === 'Stack' || component === 'Grid')
+        inspectGap(context, tag);
+    if (visualSizeComponents.has(component))
+        inspectVisualSize(context, tag, component);
+};
+const markupSkipper = (source, exclusions, script) => {
+    if (!script)
+        return cursor => skipNonMarkup(source, cursor, false);
+    return cursor => exclusions.get(cursor) ?? skipNonMarkup(source, cursor, true);
+};
+const scanMarkup = (context, file) => {
+    const script = !['.astro', '.html', '.htm'].some(extension => file.endsWith(extension));
+    const source = context.source;
+    const skip = markupSkipper(source, context.regexRanges, script);
+    let cursor = getMarkupStart(source, file);
+    while (cursor < source.length) {
+        const next = skip(cursor);
+        if (next !== cursor) {
+            cursor = next;
+            continue;
+        }
+        if (!script && source[cursor] === '{') {
+            cursor = findBalancedEnd(source, cursor, '{', '}');
+            continue;
+        }
+        const tag = readTag(source, cursor);
+        if (!tag) {
+            cursor += 1;
+            continue;
+        }
+        cursor = tag.end + 1;
+        if (!script && ['script', 'style'].includes(tag.name)) {
+            const end = source.indexOf(`</${tag.name}`, cursor);
+            cursor = end < 0 ? source.length : end;
+        }
+        else if (tag.end < source.length)
+            inspectTag(context, tag);
+    }
+};
+const generalFindings = (source, file, version) => {
+    if (['.swift', '.kt', '.kts'].some(extension => file.endsWith(extension)) && source.includes('Lumen')) {
+        return [{ file,
+                line: 1,
+                column: 1,
+                kind: 'native-review',
+                message: version === 'v3' ?
+                    'Update coordinated native package pins and rebuild. Review exhaustive Swift LumenIconName switches for added cases; no web component rewrites are required.' :
+                    'Update coordinated native package pins and rebuild. Review sheet/control initializer signatures and exhaustive Swift LumenIconName switches.' }];
+    }
+    if (version === 'v4' && file.endsWith('.css') && source.includes('.ui-')) {
+        return [{ file, line: 1, column: 1, kind: 'component-review', message: 'Review internal selectors, child margins, media clipping, fixed gutters and chart patches against the v4 migration guide; CSS is not rewritten automatically.' }];
+    }
+    return [];
+};
+const applyEdits = (source, edits) => {
+    const pieces = [];
+    let end = 0;
+    for (const edit of edits) {
+        pieces.push(source.slice(end, edit.start), edit.replacement);
+        end = edit.end;
+    }
+    pieces.push(source.slice(end));
+    return pieces.join('');
+};
+const applySdkMigration = (migration, file) => {
+    if (!['.ts', '.js', '.mjs'].some(extension => file.endsWith(extension)))
+        return migration;
+    const sdk = migrateLumenV4Source(migration.source, file);
+    return {
+        ...migration,
+        changes: [...migration.changes, ...sdk.changes.map(({ column, file: sourceFile, line, message }) => ({
+                column, file: sourceFile, kind: 'embedded-mcp-sdk', line, message
+            }))],
+        source: sdk.source
+    };
+};
+/** Assumes v3 input for v4. Filesystem apply uses a ledger to prevent repeated spacing rewrites. */
+export const migrateLumenVersionSource = (source, file, version) => {
+    const manualReview = generalFindings(source, file, version);
+    if (version === 'v3' || file.endsWith('.css'))
+        return { changes: [], manualReview, source };
+    const regexRanges = scriptRegexRanges(source, file);
+    if (!regexRanges) {
+        manualReview.push({ file, line: 1, column: 1, kind: 'component-review', message: 'The source exceeds the syntax parser nesting limit; review this file manually.' });
+        return { changes: [], manualReview, source };
+    }
+    const starts = lineStarts(source);
+    const context = {
+        source,
+        manualReview,
+        changes: [],
+        edits: [],
+        regexRanges,
+        components: collectComponents(source, regexRanges),
+        finding: (offset, kind, message) => ({ ...location(starts, offset), file, kind, message })
+    };
+    scanMarkup(context, file);
+    return applySdkMigration({ changes: context.changes, manualReview, source: applyEdits(source, context.edits) }, file);
+};

package/dist/version-migration.d.ts

@@ -0,0 +1,34 @@
+import { type LumenConsumerUpgradeAudit } from './consumer-upgrade-audit.js';
+import { applyLumenVersionMigrationDependencies, type LumenMigrationDependencyOptions } from './version-migration-dependencies.js';
+export { migrateLumenVersionSource } from './version-migration-source.js';
+export type LumenMigrationVersion = 'v3' | 'v4';
+export interface LumenVersionMigrationFinding {
+    column: number;
+    file: string;
+    kind: 'control-size' | 'layout-gap' | 'component-review' | 'native-review' | 'embedded-mcp-sdk';
+    line: number;
+    message: string;
+}
+export interface LumenVersionSourceMigration {
+    changes: LumenVersionMigrationFinding[];
+    manualReview: LumenVersionMigrationFinding[];
+    source: string;
+}
+export interface LumenVersionMigrationOptions extends LumenMigrationDependencyOptions {
+    cwd?: string;
+    version: LumenMigrationVersion;
+}
+export interface LumenVersionMigrationReport extends Omit<LumenVersionSourceMigration, 'source'> {
+    consumerAudit?: LumenConsumerUpgradeAudit;
+    applied: boolean;
+    changedFiles: string[];
+    dependencies?: Awaited<ReturnType<typeof applyLumenVersionMigrationDependencies>>;
+    dependencyVersion: string;
+    packageVersions?: Record<string, string>;
+    filesScanned: number;
+    root: string;
+    version: LumenMigrationVersion;
+}
+export declare const migrateLumenVersion: (options: LumenVersionMigrationOptions) => Promise<LumenVersionMigrationReport>;
+export declare const formatLumenVersionMigration: (report: LumenVersionMigrationReport) => string;
+//# sourceMappingURL=version-migration.d.ts.map

package/dist/version-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-migration.d.ts","sourceRoot":"","sources":["../src/version-migration.ts"],"names":[],"mappings":"AAKA,OAAO,EAAgE,KAAK,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAG1I,OAAO,EACL,sCAAsC,EACtC,KAAK,+BAA+B,EACrC,MAAM,qCAAqC,CAAA;AAG5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAA;AAEzE,MAAM,MAAM,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAAA;AAC/C,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,cAAc,GAAG,YAAY,GAAG,kBAAkB,GAAG,eAAe,GAAG,kBAAkB,CAAA;IAC/F,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AACD,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,4BAA4B,EAAE,CAAA;IACvC,YAAY,EAAE,4BAA4B,EAAE,CAAA;IAC5C,MAAM,EAAE,MAAM,CAAA;CACf;AACD,MAAM,WAAW,4BAA6B,SAAQ,+BAA+B;IACnF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,qBAAqB,CAAA;CAC/B;AACD,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAC;IAC9F,aAAa,CAAC,EAAE,yBAAyB,CAAA;IACzC,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,sCAAsC,CAAC,CAAC,CAAA;IACjF,iBAAiB,EAAE,MAAM,CAAA;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,qBAAqB,CAAA;CAC/B;AAmJD,eAAO,MAAM,mBAAmB,GAC9B,SAAS,4BAA4B,KACpC,OAAO,CAAC,2BAA2B,CA2CrC,CAAA;AAED,eAAO,MAAM,2BAA2B,GAAI,QAAQ,2BAA2B,KAAG,MAYtE,CAAA"}

package/dist/version-migration.js

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { formatConsumerRollout, inspectLumenConsumer } from './consumer-rollout.js';
+import { formatLumenConsumerUpgradeAudit, inspectLumenConsumerUpgrade } from './consumer-upgrade-audit.js';
+import { discoverSourceFiles } from './v2-migration.js';
+import { migrateLumenV4 } from './v4-migration.js';
+import { applyLumenVersionMigrationDependencies } from './version-migration-dependencies.js';
+import { migrateLumenVersionSource } from './version-migration-source.js';
+export { migrateLumenVersionSource } from './version-migration-source.js';
+const extensions = new Set(['.astro', '.htm', '.html', '.js', '.jsx', '.mjs', '.ts', '.tsx', '.swift', '.kt', '.kts', '.gradle', '.css']);
+const fingerprint = (source) => createHash('sha256').update(source).digest('hex');
+const checkLedgerLocation = async (root) => {
+    for (const path of [resolve(root, '.lumen'), resolve(root, '.lumen', 'migrations-v4.json')]) {
+        try {
+            if ((await lstat(path)).isSymbolicLink())
+                throw new Error(`Migration ledger must not follow a symbolic link: ${path}`);
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+    }
+};
+const readLedger = async (path) => {
+    let source;
+    try {
+        source = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+    const value = JSON.parse(source);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Invalid migration ledger: ${path}`);
+    const entries = Object.entries(value);
+    if (entries.some(([, hash]) => typeof hash !== 'string' || !/^[a-f0-9]{64}$/u.test(hash)))
+        throw new Error(`Invalid migration ledger: ${path}`);
+    return Object.fromEntries(entries.map(([file, hash]) => [file, String(hash)]));
+};
+const writeMigratedSource = async (absoluteFile, source, nextSource, { report, ledger, ledgerPath, file }) => {
+    if (await readFile(absoluteFile, 'utf8') !== source)
+        throw new Error(`Source changed during migration: ${file}`);
+    if (report.version === 'v4') {
+        // Write the intended fingerprint first so an interrupted apply cannot double-rewrite gaps.
+        await mkdir(resolve(report.root, '.lumen'), { recursive: true });
+        ledger[file] = fingerprint(nextSource);
+        await writeFile(ledgerPath, `${JSON.stringify(ledger, undefined, 2)}\n`, 'utf8');
+    }
+    if (await readFile(absoluteFile, 'utf8') !== source) {
+        if (report.version === 'v4') {
+            Reflect.deleteProperty(ledger, file);
+            await writeFile(ledgerPath, `${JSON.stringify(ledger, undefined, 2)}\n`, 'utf8');
+        }
+        throw new Error(`Source changed during migration: ${file}`);
+    }
+    await writeFile(absoluteFile, nextSource, 'utf8');
+};
+const migrateFile = async (absoluteFile, report, ledger, ledgerPath) => {
+    const file = relative(report.root, absoluteFile) || absoluteFile;
+    const source = await readFile(absoluteFile, 'utf8');
+    if (report.version === 'v4' && Object.hasOwn(ledger, file)) {
+        if (ledger[file] !== fingerprint(source))
+            report.manualReview.push({ file,
+                line: 1,
+                column: 1,
+                kind: 'layout-gap',
+                message: 'This file was already migrated to v4 and has since changed. Review new edits manually; repeating gap rewrites would change spacing twice.' });
+        return;
+    }
+    const migration = migrateLumenVersionSource(source, file, report.version);
+    report.changes.push(...migration.changes);
+    report.manualReview.push(...migration.manualReview);
+    if (source === migration.source)
+        return;
+    report.changedFiles.push(file);
+    if (!report.applied)
+        return;
+    await writeMigratedSource(absoluteFile, source, migration.source, { report, ledger, ledgerPath, file });
+};
+const createReport = (options, root, filesScanned) => ({
+    applied: options.apply === true,
+    changedFiles: [],
+    changes: [],
+    filesScanned,
+    manualReview: [],
+    root,
+    version: options.version,
+    dependencyVersion: options.version === 'v3' ? '3.0.1' : '4.0.0'
+});
+const refreshDependencyReport = async (report) => {
+    if (report.dependencies && report.applied) {
+        for (const repository of report.dependencies.repositories) {
+            const current = await inspectLumenConsumer(repository.repository, report.dependencyVersion);
+            current.warnings = current.warnings.filter(warning => !warning.startsWith('Repository has uncommitted changes'));
+            current.valid = current.warnings.length === 0 && current.integration.healthy;
+            Object.assign(repository, current);
+        }
+    }
+};
+const optionalConsumerAudit = async (root, version) => {
+    try {
+        await readFile(resolve(root, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    return inspectLumenConsumerUpgrade(root, version);
+};
+export const migrateLumenVersion = async (options) => {
+    const root = resolve(options.cwd ?? process.cwd());
+    if (!(await lstat(root)).isDirectory())
+        throw new Error('Migration --cwd must be a project directory.');
+    const files = await discoverSourceFiles(root, extensions);
+    const ledgerPath = resolve(root, '.lumen', 'migrations-v4.json');
+    await checkLedgerLocation(root);
+    const ledger = options.version === 'v4' ? await readLedger(ledgerPath) : {};
+    const report = createReport(options, root, files.length);
+    if (options.dependencies) {
+        report.dependencies = await applyLumenVersionMigrationDependencies(root, report.dependencyVersion, options);
+        if (report.dependencies.repositories.some(repository => repository.commands.some(command => !command.ok))) {
+            report.applied = false;
+            return report;
+        }
+    }
+    if (options.version === 'v4') {
+        const sdk = await migrateLumenV4({ cwd: root });
+        report.packageVersions = sdk.packageVersions;
+        report.manualReview.push(...sdk.manualReview.filter(finding => finding.rule === 'embedded-mcp-sdk-v2')
+            .map(({ column, file, line, message }) => ({ column, file, kind: 'embedded-mcp-sdk', line, message })));
+    }
+    for (const absoluteFile of files) {
+        await migrateFile(absoluteFile, report, ledger, ledgerPath);
+    }
+    await refreshDependencyReport(report);
+    const consumerAudit = await optionalConsumerAudit(root, report.dependencyVersion);
+    if (consumerAudit)
+        report.consumerAudit = consumerAudit;
+    return report;
+};
+export const formatLumenVersionMigration = (report) => [
+    `Lumen ${report.version} migration ${report.applied ? 'apply' : 'dry run'}: ${report.root}`,
+    `Scanned ${report.filesScanned} source files. ${report.applied ? 'Applied' : 'Would apply'} ${report.changes.length} changes in ${report.changedFiles.length} files.`,
+    ...report.changes.map(item => `${item.file}:${item.line}:${item.column} [${item.kind}] ${item.message}`),
+    ...report.manualReview.map(item => `${item.file}:${item.line}:${item.column} [manual review] ${item.message}`),
+    ...(report.dependencies ? [formatConsumerRollout(report.dependencies)] : []),
+    ...(report.consumerAudit ? [formatLumenConsumerUpgradeAudit(report.consumerAudit)] : []),
+    report.version === 'v3' ?
+        'V3 requires coordinated package versions and a native rebuild, with no web source rewrites. Review exhaustive Swift LumenIconName switches for added cases.' :
+        'Review product CSS, pending dialogs, chart identity, native initializers, exhaustive Swift icon switches and embedded MCP SDK v2 integrations. Source changes do not qualify the application for release.',
+    `Use --dependencies to inventory or upgrade the coordinated npm family to ${report.dependencyVersion} through the existing pnpm rollout. Native Swift/Maven pins remain application-owned.`,
+    ...(!report.applied && report.changes.length ? [`Run lumen migrate ${report.version} --apply to write the source changes.`] : [])
+].join('\n');