@contrail/cli 3.4.5 → 3.4.6-alpha.cffb28e

package/node_modules/@contrail/loader/lib/pipeline/item-execute-helpers.js

@@ -0,0 +1,517 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeItemEntities = exports.previewItemEntities = exports.splitIntoFamiliesAndOptions = exports.buildDiffUpdatePayload = exports.extractFailureId = exports.extractApiErrorMessage = void 0;
+const types_1 = require("./types");
+const util_1 = require("@contrail/util");
+const lodash_1 = require("lodash");
+const entities_helper_1 = require("../entities-v2/entities-helper");
+const type_helper_1 = require("../common/type-helper");
+const pLimit = require('p-limit');
+const DEFAULT_BATCH_SIZE = 50;
+const DEFAULT_CONCURRENCY = 20;
+const DEFAULT_MAX_RETRIES = 3;
+function extractApiErrorMessage(err) {
+    const validationErrors = err?.error?.response?.validationSummary?.validationErrors;
+    if (validationErrors && typeof validationErrors === 'object') {
+        const messages = [];
+        for (const [field, errors] of Object.entries(validationErrors)) {
+            if (Array.isArray(errors)) {
+                for (const e of errors) {
+                    messages.push(`${field}: ${e.message || JSON.stringify(e)}`);
+                }
+            }
+        }
+        if (messages.length > 0)
+            return messages.join('; ');
+    }
+    return err?.error?.message ?? err?.error?.response?.message ?? String(err?.error);
+}
+exports.extractApiErrorMessage = extractApiErrorMessage;
+function extractFailureId(err) {
+    return (err?.data?.federatedId ??
+        err?.entity?.federatedId ??
+        err?.error?.response?.obj?.federatedId ??
+        err?.entity?.id ??
+        'unknown');
+}
+exports.extractFailureId = extractFailureId;
+function buildDiffUpdatePayload(incoming, existing) {
+    const diffs = (0, entities_helper_1.compareIncomingAndExisting)(incoming, existing);
+    const changes = {};
+    for (const diff of diffs) {
+        const topKey = diff.propertyName.split('.')[0];
+        if (topKey && incoming[topKey] !== undefined) {
+            changes[topKey] = incoming[topKey];
+        }
+    }
+    return {
+        id: existing.id,
+        changes,
+    };
+}
+exports.buildDiffUpdatePayload = buildDiffUpdatePayload;
+function splitIntoFamiliesAndOptions(incomingEntities, typesByPath) {
+    const byFamilyId = {};
+    for (const entity of incomingEntities) {
+        const famFedId = entity.itemFamilyFederatedId;
+        if (!famFedId)
+            continue;
+        if (!byFamilyId[famFedId])
+            byFamilyId[famFedId] = [];
+        byFamilyId[famFedId].push(entity);
+    }
+    const families = [];
+    const options = [];
+    const optionToFamilyMap = new Map();
+    for (const [famFedId, rows] of Object.entries(byFamilyId)) {
+        const familyRow = rows.find((r) => !r.itemOptionFederatedId) || rows[0];
+        const typePath = familyRow.typePath || types_1.EntityType.ITEM;
+        const typeInfo = typesByPath[typePath];
+        const type = typeInfo?.type;
+        const typePropSlugs = new Set((type?.typeProperties ?? []).map((tp) => tp.slug));
+        const familyClone = util_1.ObjectUtil.cloneDeep(familyRow);
+        const familyEntity = type ? (0, type_helper_1.reduceToFamilyProperties)(familyClone, type) : { ...familyClone };
+        promoteFamilySuffixes(familyEntity, typePropSlugs);
+        familyEntity.federatedId = famFedId;
+        delete familyEntity.optionGroup;
+        delete familyEntity.optionName;
+        delete familyEntity.itemFamilyFederatedId;
+        delete familyEntity.itemOptionFederatedId;
+        families.push(familyEntity);
+        for (const row of rows) {
+            if (!row.itemOptionFederatedId)
+                continue;
+            const optionFedId = row.itemOptionFederatedId;
+            const optClone = util_1.ObjectUtil.cloneDeep(row);
+            optClone.federatedId = optionFedId;
+            optionToFamilyMap.set(optionFedId, optClone.itemFamilyFederatedId);
+            delete optClone.itemFamilyFederatedId;
+            delete optClone.itemOptionFederatedId;
+            if (type) {
+                (0, type_helper_1.setOptionOverrides)(optClone, { typeProperties: type.typeProperties });
+                (0, type_helper_1.removeFamilyLevelPropsFromOption)(optClone, type);
+            }
+            promoteOptionSuffixes(optClone, typePropSlugs);
+            options.push(optClone);
+        }
+    }
+    return { families, options, optionToFamilyMap };
+}
+exports.splitIntoFamiliesAndOptions = splitIntoFamiliesAndOptions;
+const SUFFIX_SKIP_BASES = new Set(['itemFamily', 'itemOption']);
+function isPromotableSuffix(key, base, typePropSlugs) {
+    if (typePropSlugs.has(key))
+        return false;
+    if (SUFFIX_SKIP_BASES.has(base))
+        return false;
+    return typePropSlugs.has(base) || SYSTEM_OVERRIDABLE_BASES.has(base);
+}
+const SYSTEM_OVERRIDABLE_BASES = new Set(['lifecycleStage']);
+function promoteFamilySuffixes(entity, typePropSlugs) {
+    for (const key of Object.keys(entity)) {
+        const family = 'Family';
+        if (!key.endsWith(family))
+            continue;
+        const base = key.slice(0, -family.length);
+        if (!isPromotableSuffix(key, base, typePropSlugs))
+            continue;
+        entity[base] = entity[key];
+        delete entity[key];
+    }
+    for (const key of Object.keys(entity)) {
+        const familyId = 'FamilyId';
+        if (!key.endsWith(familyId))
+            continue;
+        const baseId = key.slice(0, -familyId.length) + 'Id';
+        if (typePropSlugs.has(key))
+            continue;
+        if (!typePropSlugs.has(baseId) && !SYSTEM_OVERRIDABLE_BASES.has(key.slice(0, -familyId.length)))
+            continue;
+        entity[baseId] = entity[key];
+        delete entity[key];
+    }
+    for (const key of Object.keys(entity)) {
+        const option = 'Option';
+        const optionId = 'OptionId';
+        if (!key.endsWith(option) && !key.endsWith(optionId))
+            continue;
+        const base = key.endsWith(optionId) ? key.slice(0, -optionId.length) : key.slice(0, -option.length);
+        if (!isPromotableSuffix(key, base, typePropSlugs))
+            continue;
+        delete entity[key];
+    }
+}
+function promoteOptionSuffixes(entity, typePropSlugs) {
+    for (const key of Object.keys(entity)) {
+        const searchString = 'Option';
+        if (!key.endsWith(searchString))
+            continue;
+        const base = key.slice(0, -searchString.length);
+        if (!isPromotableSuffix(key, base, typePropSlugs))
+            continue;
+        entity[base] = entity[key];
+        delete entity[key];
+    }
+    for (const key of Object.keys(entity)) {
+        const searchString = 'OptionId';
+        if (!key.endsWith('OptionId'))
+            continue;
+        const baseId = key.slice(0, -searchString.length) + 'Id';
+        if (typePropSlugs.has(key))
+            continue;
+        if (!typePropSlugs.has(baseId) && !SYSTEM_OVERRIDABLE_BASES.has(key.slice(0, -searchString.length)))
+            continue;
+        entity[baseId] = entity[key];
+        delete entity[key];
+    }
+    for (const key of Object.keys(entity)) {
+        const familyId = 'FamilyId';
+        const family = 'Family';
+        if (!key.endsWith(family) && !key.endsWith(familyId))
+            continue;
+        const base = key.endsWith(familyId) ? key.slice(0, -familyId.length) : key.slice(0, -family.length);
+        if (!isPromotableSuffix(key, base, typePropSlugs))
+            continue;
+        delete entity[key];
+    }
+}
+function previewItemEntities(incomingEntities, currentByFedId, typesByPath, config) {
+    const { families, options, optionToFamilyMap } = splitIntoFamiliesAndOptions(incomingEntities, typesByPath);
+    const warnings = [];
+    const badRows = [];
+    const staleRows = [];
+    const familyClassification = classifyEntities(families, currentByFedId, config.skipStaleUpdatesUsing);
+    const skippedUpstream = [];
+    const viableOptions = [];
+    const familyFedIds = new Set();
+    for (const fam of families) {
+        familyFedIds.add(fam.federatedId);
+    }
+    for (const opt of options) {
+        const famFedId = optionToFamilyMap.get(opt.federatedId);
+        const familyExists = currentByFedId[famFedId] || familyFedIds.has(famFedId);
+        if (!familyExists) {
+            skippedUpstream.push({
+                rowNumber: -1,
+                federatedId: opt.federatedId,
+                reason: `Family (${famFedId}) not found for option (${opt.federatedId})`,
+            });
+            continue;
+        }
+        viableOptions.push(opt);
+    }
+    const optionClassification = classifyEntities(viableOptions, currentByFedId, config.skipStaleUpdatesUsing);
+    for (const s of [...familyClassification.stale, ...optionClassification.stale]) {
+        staleRows.push({
+            rowNumber: -1,
+            federatedId: s.entity?.federatedId,
+            reason: 'Skipped: incoming timestamp is older than existing',
+        });
+    }
+    const summaries = [
+        {
+            entityType: 'item (families)',
+            total: families.length,
+            creates: familyClassification.toCreate.length,
+            updates: familyClassification.toUpdate.length,
+            drops: 0,
+            unchanged: familyClassification.unchanged.length,
+            skippedStale: familyClassification.stale.length,
+        },
+        {
+            entityType: 'item (options)',
+            total: viableOptions.length,
+            creates: optionClassification.toCreate.length,
+            updates: optionClassification.toUpdate.length,
+            drops: 0,
+            unchanged: optionClassification.unchanged.length,
+            skippedStale: optionClassification.stale.length,
+        },
+    ];
+    return {
+        summaries,
+        badRows,
+        staleRows,
+        warnings,
+        constructedFamilies: {
+            toCreate: familyClassification.toCreate,
+            toUpdate: familyClassification.toUpdate,
+            unchanged: familyClassification.unchanged,
+            currentByFedId,
+        },
+        constructedOptions: {
+            toCreate: optionClassification.toCreate,
+            toUpdate: optionClassification.toUpdate,
+            unchanged: optionClassification.unchanged,
+            skippedUpstream,
+        },
+    };
+}
+exports.previewItemEntities = previewItemEntities;
+async function executeItemEntities(client, entitySet, config, options) {
+    const batchSize = options?.batchSize ?? config.options?.batchSize ?? DEFAULT_BATCH_SIZE;
+    const concurrency = options?.concurrency ?? config.options?.concurrency ?? DEFAULT_CONCURRENCY;
+    const maxRetries = options?.maxRetries ?? config.options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const limit = pLimit(concurrency);
+    const { families, options: itemOptions, optionToFamilyMap, } = splitIntoFamiliesAndOptions(entitySet.incomingEntities, entitySet.typesByPath);
+    const currentByFedId = { ...entitySet.allCurrentEntitiesByFederatedId };
+    const allSkippedRows = [];
+    const allWarnings = [];
+    let hasFailures = false;
+    const familyClass = classifyEntities(families, currentByFedId, config.skipStaleUpdatesUsing);
+    if (config.options?.ignoreFamilyNameOnUpdate) {
+        for (const entity of familyClass.toUpdate) {
+            delete entity.name;
+        }
+    }
+    for (const s of familyClass.stale) {
+        allSkippedRows.push({
+            rowNumber: -1,
+            federatedId: s.entity?.federatedId,
+            reason: 'Stale update skipped (family)',
+        });
+    }
+    const familyFailures = [];
+    let familyCreatedCount = 0;
+    let familyUpdatedCount = 0;
+    const failedFamilyFedIds = new Set();
+    const totalOps = familyClass.toCreate.length + familyClass.toUpdate.length;
+    let completedOps = 0;
+    const reportProgress = (count, stage) => {
+        completedOps += count;
+        options?.onProgress?.({ stage, current: completedOps, total: totalOps });
+    };
+    const { created, failures: createFails } = await batchCreateEntities(client, familyClass.toCreate, 'item', batchSize, limit, maxRetries, (n) => reportProgress(n, 'execute:item-families'));
+    familyCreatedCount = created;
+    familyFailures.push(...createFails);
+    for (const f of createFails) {
+        failedFamilyFedIds.add(f.federatedId);
+    }
+    const updateEntities = familyClass.toUpdate.map((incoming) => {
+        const existing = currentByFedId[incoming.federatedId];
+        return buildDiffUpdatePayload(incoming, existing);
+    });
+    const { updated, failures: updateFails } = await batchUpdateEntities(client, updateEntities, 'item', batchSize, limit, maxRetries, (n) => reportProgress(n, 'execute:item-families'));
+    familyUpdatedCount = updated;
+    familyFailures.push(...updateFails);
+    for (const f of updateFails) {
+        failedFamilyFedIds.add(f.federatedId);
+    }
+    if (familyFailures.length > 0)
+        hasFailures = true;
+    const allFamilyFedIds = families.map((f) => f.federatedId).filter((id) => !failedFamilyFedIds.has(id));
+    if (allFamilyFedIds.length > 0) {
+        await refreshEntityCache(client, allFamilyFedIds, currentByFedId);
+    }
+    const viableOptions = [];
+    for (const opt of itemOptions) {
+        const famFedId = optionToFamilyMap.get(opt.federatedId);
+        if (failedFamilyFedIds.has(famFedId)) {
+            allSkippedRows.push({
+                rowNumber: -1,
+                federatedId: opt.federatedId,
+                reason: `Skipped: family (${famFedId}) failed to load`,
+            });
+            continue;
+        }
+        const family = currentByFedId[famFedId];
+        if (!family) {
+            allSkippedRows.push({
+                rowNumber: -1,
+                federatedId: opt.federatedId,
+                reason: `Family (${famFedId}) not found after family load phase`,
+            });
+            continue;
+        }
+        opt.itemFamilyId = family.id;
+        viableOptions.push(opt);
+    }
+    const optionClass = classifyEntities(viableOptions, currentByFedId, config.skipStaleUpdatesUsing);
+    if (config.options?.ignoreOptionNameOnUpdate) {
+        for (const entity of optionClass.toUpdate) {
+            delete entity.name;
+        }
+    }
+    for (const entity of optionClass.toCreate) {
+        entity.optionGroup = 'color';
+    }
+    for (const s of optionClass.stale) {
+        allSkippedRows.push({
+            rowNumber: -1,
+            federatedId: s.entity?.federatedId,
+            reason: 'Stale update skipped (option)',
+        });
+    }
+    const optionFailures = [];
+    let optionCreatedCount = 0;
+    let optionUpdatedCount = 0;
+    const optTotalOps = optionClass.toCreate.length + optionClass.toUpdate.length;
+    let optCompletedOps = 0;
+    const reportOptProgress = (count) => {
+        optCompletedOps += count;
+        options?.onProgress?.({ stage: 'execute:item-options', current: optCompletedOps, total: optTotalOps });
+    };
+    const { created: optCreated, failures: optCreateFails } = await batchCreateEntities(client, optionClass.toCreate, 'item', batchSize, limit, maxRetries, reportOptProgress);
+    optionCreatedCount = optCreated;
+    optionFailures.push(...optCreateFails);
+    const optUpdateEntities = optionClass.toUpdate.map((incoming) => {
+        const existing = currentByFedId[incoming.federatedId];
+        return buildDiffUpdatePayload(incoming, existing);
+    });
+    const { updated: optUpdated, failures: optUpdateFails } = await batchUpdateEntities(client, optUpdateEntities, 'item', batchSize, limit, maxRetries, reportOptProgress);
+    optionUpdatedCount = optUpdated;
+    optionFailures.push(...optUpdateFails);
+    if (optionFailures.length > 0)
+        hasFailures = true;
+    const summaries = [
+        {
+            entityType: 'item (families)',
+            created: familyCreatedCount,
+            updated: familyUpdatedCount,
+            dropped: 0,
+            skippedStale: familyClass.stale.length,
+            failed: familyFailures.length,
+            failures: familyFailures,
+        },
+        {
+            entityType: 'item (options)',
+            created: optionCreatedCount,
+            updated: optionUpdatedCount,
+            dropped: 0,
+            skippedStale: optionClass.stale.length,
+            failed: optionFailures.length,
+            failures: optionFailures,
+        },
+    ];
+    return { summaries, skippedRows: allSkippedRows, warnings: allWarnings, hasFailures };
+}
+exports.executeItemEntities = executeItemEntities;
+async function batchCreateEntities(client, entities, entityName, batchSize, limit, maxRetries, onBatchComplete) {
+    let created = 0;
+    const failures = [];
+    const chunks = (0, lodash_1.chunk)(entities, batchSize);
+    const promises = chunks.map((batch) => limit(async () => {
+        try {
+            console.debug(`Batch CREATE ${entityName} (${batch.length} entities):`, JSON.stringify(batch, null, 2));
+            const result = await (0, entities_helper_1.retryOnTimeout)(client, entities_helper_1.EntitiesLambdaCallType.BATCHCREATE, { entityName, objects: batch, apiVersion: '2' }, maxRetries);
+            if (result?.errors?.length) {
+                for (const err of result.errors) {
+                    failures.push({
+                        federatedId: extractFailureId(err),
+                        operation: 'create',
+                        error: extractApiErrorMessage(err),
+                    });
+                }
+            }
+            const errorCount = result?.errors?.length ?? 0;
+            const hasData = Array.isArray(result?.data) && result.data.length > 0;
+            const successCount = hasData ? result.data.length : batch.length - errorCount;
+            created += Math.max(0, successCount);
+            onBatchComplete(batch.length);
+        }
+        catch (e) {
+            console.error(`Batch CREATE ${entityName} failed. Payload:`, JSON.stringify(batch, null, 2));
+            for (const entity of batch) {
+                failures.push({
+                    federatedId: entity.federatedId ?? 'unknown',
+                    operation: 'create',
+                    error: e.message,
+                });
+            }
+        }
+    }));
+    await Promise.all(promises);
+    return { created, failures };
+}
+async function batchUpdateEntities(client, entities, entityName, batchSize, limit, maxRetries, onBatchComplete) {
+    let updated = 0;
+    const failures = [];
+    const chunks = (0, lodash_1.chunk)(entities, batchSize);
+    const promises = chunks.map((batch) => limit(async () => {
+        try {
+            console.debug(`Batch UPDATE ${entityName} (${batch.length} entities):`, JSON.stringify(batch, null, 2));
+            const result = await (0, entities_helper_1.retryOnTimeout)(client, entities_helper_1.EntitiesLambdaCallType.BATCHUPDATE, { entityName, objects: batch, apiVersion: '2' }, maxRetries);
+            if (result?.errors?.length) {
+                for (const err of result.errors) {
+                    failures.push({
+                        federatedId: extractFailureId(err),
+                        operation: 'update',
+                        error: extractApiErrorMessage(err),
+                    });
+                }
+            }
+            const errorCount = result?.errors?.length ?? 0;
+            const hasData = Array.isArray(result?.data) && result.data.length > 0;
+            const successCount = hasData ? result.data.length : batch.length - errorCount;
+            updated += Math.max(0, successCount);
+            onBatchComplete(batch.length);
+        }
+        catch (e) {
+            console.error(`Batch UPDATE ${entityName} failed. Payload:`, JSON.stringify(batch, null, 2));
+            for (const entity of batch) {
+                failures.push({
+                    federatedId: entity.federatedId ?? 'unknown',
+                    operation: 'update',
+                    error: e.message,
+                });
+            }
+        }
+    }));
+    await Promise.all(promises);
+    return { updated, failures };
+}
+async function refreshEntityCache(client, federatedIds, cache) {
+    const chunks = (0, lodash_1.chunk)(federatedIds, 200);
+    const pLimitFetch = pLimit(5);
+    const promises = chunks.map((batch) => pLimitFetch(async () => {
+        try {
+            const items = await (0, entities_helper_1.retryOnTimeout)(client, entities_helper_1.EntitiesLambdaCallType.GET, {
+                entityName: 'item',
+                federatedIds: batch,
+                skipHydrateRelationships: true,
+            });
+            if (items?.length) {
+                for (const item of items) {
+                    cache[item.federatedId] = item;
+                }
+            }
+        }
+        catch (e) {
+            console.warn('Failed to refresh entity cache:', e.message);
+        }
+    }));
+    await Promise.all(promises);
+}
+function classifyEntities(incomingEntities, currentByFedId, skipStaleUpdatesUsing) {
+    const toCreate = [];
+    const toUpdate = [];
+    const unchanged = [];
+    const stale = [];
+    for (const incoming of incomingEntities) {
+        const fedId = incoming.federatedId;
+        const existing = fedId ? currentByFedId[fedId] : undefined;
+        if (!existing) {
+            toCreate.push(incoming);
+            continue;
+        }
+        if (skipStaleUpdatesUsing) {
+            const incomingTs = incoming[skipStaleUpdatesUsing];
+            const existingTs = existing[skipStaleUpdatesUsing];
+            if (incomingTs && existingTs && new Date(incomingTs) < new Date(existingTs)) {
+                stale.push({
+                    entity: incoming,
+                    incomingTimestamp: String(incomingTs),
+                    existingTimestamp: String(existingTs),
+                });
+                continue;
+            }
+        }
+        if ((0, entities_helper_1.UpdateNeeded)(incoming, existing)) {
+            toUpdate.push(incoming);
+        }
+        else {
+            unchanged.push(incoming);
+        }
+    }
+    return { toCreate, toUpdate, unchanged, stale };
+}

package/node_modules/@contrail/loader/lib/pipeline/item-execute-helpers.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@contrail/loader/lib/pipeline/item-execute-helpers.spec.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("@contrail/types");
+const item_execute_helpers_1 = require("./item-execute-helpers");
+describe('splitIntoFamiliesAndOptions', () => {
+    const makeTypesByPath = (typeProperties) => ({
+        item: {
+            type: { typeProperties },
+            allPropertiesSlugs: typeProperties.map((tp) => tp.slug),
+            typePropertyToValueType: {},
+            objectReferenceProperties: [],
+            userListProperties: [],
+        },
+    });
+    describe('ObjectReference overridable properties with Id suffix', () => {
+        const typesByPath = makeTypesByPath([
+            {
+                slug: 'topMaterial',
+                propertyType: types_1.PropertyType.ObjectReference,
+                propertyLevel: types_1.PropertyLevel.OVERRIDABLE,
+            },
+        ]);
+        it('should promote topMaterialFamilyId to topMaterialId on family entity', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    topMaterialFamilyId: 'family-entity-id',
+                    topMaterialOptionId: 'option-entity-id',
+                },
+            ];
+            const { families } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(families[0].topMaterialId).toBe('family-entity-id');
+            expect(families[0].topMaterialFamilyId).toBeUndefined();
+            expect(families[0].topMaterialOptionId).toBeUndefined();
+        });
+        it('should promote topMaterialOptionId to topMaterialId on option entity', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    topMaterialFamilyId: 'family-entity-id',
+                    topMaterialOptionId: 'option-entity-id',
+                },
+            ];
+            const { options } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(options[0].topMaterialId).toBe('option-entity-id');
+            expect(options[0].topMaterialOptionId).toBeUndefined();
+            expect(options[0].topMaterialFamilyId).toBeUndefined();
+        });
+    });
+    describe('system property overridable suffixes (not in typeProperties)', () => {
+        const typesByPath = makeTypesByPath([
+            { slug: 'color', propertyType: types_1.PropertyType.String, propertyLevel: types_1.PropertyLevel.OPTION },
+        ]);
+        it('should promote lifecycleStageFamily to lifecycleStage on family entity', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    lifecycleStageFamily: 'concept',
+                    lifecycleStageOption: 'released',
+                },
+            ];
+            const { families } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(families[0].lifecycleStage).toBe('concept');
+            expect(families[0].lifecycleStageFamily).toBeUndefined();
+            expect(families[0].lifecycleStageOption).toBeUndefined();
+        });
+        it('should promote lifecycleStageOption to lifecycleStage on option entity', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    lifecycleStageFamily: 'concept',
+                    lifecycleStageOption: 'released',
+                },
+            ];
+            const { options } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(options[0].lifecycleStage).toBe('released');
+            expect(options[0].lifecycleStageOption).toBeUndefined();
+            expect(options[0].lifecycleStageFamily).toBeUndefined();
+        });
+    });
+    describe('standard overridable properties', () => {
+        const typesByPath = makeTypesByPath([
+            {
+                slug: 'property_with_level_overridable',
+                propertyType: types_1.PropertyType.String,
+                propertyLevel: types_1.PropertyLevel.OVERRIDABLE,
+            },
+        ]);
+        it('should promote Family suffix to base on family entity', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    property_with_level_overridableFamily: 'family_value',
+                    property_with_level_overridableOption: 'option_value',
+                },
+            ];
+            const { families } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(families[0].property_with_level_overridable).toBe('family_value');
+            expect(families[0].property_with_level_overridableFamily).toBeUndefined();
+            expect(families[0].property_with_level_overridableOption).toBeUndefined();
+        });
+        it('should promote Option suffix to base on option entity', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    property_with_level_overridableFamily: 'family_value',
+                    property_with_level_overridableOption: 'option_value',
+                },
+            ];
+            const { options } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(options[0].property_with_level_overridable).toBe('option_value');
+            expect(options[0].property_with_level_overridableOption).toBeUndefined();
+            expect(options[0].property_with_level_overridableFamily).toBeUndefined();
+        });
+    });
+    describe('property slugs ending in Family/Option should not be treated as suffixes', () => {
+        const typesByPath = makeTypesByPath([
+            {
+                slug: 'propertyFamily',
+                propertyType: types_1.PropertyType.String,
+                propertyLevel: types_1.PropertyLevel.OPTION,
+            },
+            {
+                slug: 'propertyOption',
+                propertyType: types_1.PropertyType.String,
+                propertyLevel: types_1.PropertyLevel.FAMILY,
+            },
+        ]);
+        it('should preserve propertyOption on family entity (FAMILY-level prop whose slug ends in Option)', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    propertyFamily: 'family_val',
+                    propertyOption: 'option_val',
+                },
+            ];
+            const { families } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(families[0].propertyOption).toBe('option_val');
+            expect(families[0].propertyFamily).toBeUndefined();
+        });
+        it('should preserve propertyFamily on option entity (OPTION-level prop whose slug ends in Family)', () => {
+            const entities = [
+                {
+                    itemFamilyFederatedId: 'fam-1',
+                    itemOptionFederatedId: 'opt-1',
+                    typePath: 'item',
+                    propertyFamily: 'family_val',
+                    propertyOption: 'option_val',
+                },
+            ];
+            const { options } = (0, item_execute_helpers_1.splitIntoFamiliesAndOptions)(entities, typesByPath);
+            expect(options[0].propertyFamily).toBe('family_val');
+            expect(options[0].propertyOption).toBeUndefined();
+        });
+    });
+});