@funnelsgrove/runtime 0.1.56 → 0.1.59

package/dist/steps/choice-contract.js

@@ -0,0 +1,302 @@
+import { createFunnelContractDiagnostic, } from '../validation/funnel-contract-diagnostics.js';
+import { FUNNEL_STEP_CONTRACTS, } from './step-contract.js';
+export const FUNNEL_CHOICE_STEP_TYPES = Object.freeze(Object.keys(FUNNEL_STEP_CONTRACTS).filter((type) => 'choice' in FUNNEL_STEP_CONTRACTS[type]));
+const GUIDE = 'docs/product-specs/funnel-template-step-authoring.md';
+const SAFE_ANSWER_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PROTOTYPE_DANGEROUS_ANSWER_KEYS = new Set([
+    ...Object.getOwnPropertyNames(Object.prototype),
+    'prototype',
+]);
+export const MAX_FUNNEL_CHOICE_ITEMS = 4096;
+export const MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH = 256;
+export const MAX_FUNNEL_CHOICE_CONTENT_STRING_LENGTH = 4096;
+const diagnostic = (code, stepId, expected, received, reason, repair) => createFunnelContractDiagnostic({
+    code,
+    file: null,
+    stepId,
+    expected,
+    received,
+    reason,
+    guide: GUIDE,
+    repair,
+});
+const isChoiceStepType = (value) => {
+    return typeof value === 'string'
+        && FUNNEL_CHOICE_STEP_TYPES.some((type) => type === value);
+};
+const readPlainDataRecord = (value) => {
+    try {
+        const prototype = typeof value === 'object' && value !== null
+            ? Object.getPrototypeOf(value)
+            : undefined;
+        if (typeof value !== 'object'
+            || value === null
+            || Array.isArray(value)
+            || (prototype !== Object.prototype && prototype !== null)
+            || Object.getOwnPropertySymbols(value).length > 0) {
+            return null;
+        }
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const fields = Object.keys(descriptors).sort();
+        if (fields.some((field) => !('value' in descriptors[field]))) {
+            return null;
+        }
+        return { descriptors, fields };
+    }
+    catch (_a) {
+        return null;
+    }
+};
+const readOwnDataProperty = (value, key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor) {
+        return { status: 'missing', value: undefined };
+    }
+    if (!('value' in descriptor)) {
+        return { status: 'accessor', value: undefined };
+    }
+    return { status: 'data', value: descriptor.value };
+};
+const isBoundedNonblankString = (value, maximumLength) => {
+    return typeof value === 'string'
+        && value.length <= maximumLength
+        && value.trim().length > 0;
+};
+const captureChoiceStepMeta = (value) => {
+    let stepId = null;
+    try {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return { ok: false, stepId, issue: 'step metadata must be a plain data record' };
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return { ok: false, stepId, issue: 'step metadata must be a plain data record' };
+        }
+        const idProperty = readOwnDataProperty(value, 'id');
+        if (idProperty.status !== 'data'
+            || !isBoundedNonblankString(idProperty.value, MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH)) {
+            return { ok: false, stepId, issue: 'step ID must be a bounded nonblank data string' };
+        }
+        stepId = idProperty.value;
+        const typeProperty = readOwnDataProperty(value, 'type');
+        const choiceProperty = readOwnDataProperty(value, 'choice');
+        if (typeProperty.status !== 'data' || choiceProperty.status === 'accessor') {
+            return {
+                ok: false,
+                stepId,
+                issue: 'step type and choice must be own data properties',
+            };
+        }
+        if (typeof typeProperty.value === 'string'
+            && typeProperty.value.length > MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH) {
+            return { ok: false, stepId, issue: 'step type exceeds the maximum identifier length' };
+        }
+        return {
+            ok: true,
+            id: stepId,
+            type: typeProperty.value,
+            choice: choiceProperty.value,
+        };
+    }
+    catch (_a) {
+        return { ok: false, stepId, issue: 'step metadata could not be inspected safely' };
+    }
+};
+const readBoundedDenseArray = (value, label) => {
+    try {
+        if (!Array.isArray(value)) {
+            return { ok: false, issue: `${label} must be an array` };
+        }
+        const lengthProperty = readOwnDataProperty(value, 'length');
+        if (lengthProperty.status !== 'data'
+            || typeof lengthProperty.value !== 'number'
+            || !Number.isSafeInteger(lengthProperty.value)
+            || lengthProperty.value < 0) {
+            return { ok: false, issue: `${label} has an invalid length` };
+        }
+        if (lengthProperty.value > MAX_FUNNEL_CHOICE_ITEMS) {
+            const verb = label === 'options' ? 'exceed' : 'exceeds';
+            return { ok: false, issue: `${label} ${verb} the maximum item count` };
+        }
+        const values = [];
+        for (let index = 0; index < lengthProperty.value; index += 1) {
+            const item = readOwnDataProperty(value, String(index));
+            if (item.status !== 'data') {
+                return { ok: false, issue: `${label} must be a dense data array`, index };
+            }
+            values.push(item.value);
+        }
+        return { ok: true, values };
+    }
+    catch (_a) {
+        return { ok: false, issue: `${label} could not be inspected safely` };
+    }
+};
+const readDescriptorValue = (record, field) => { var _a; return (_a = record.descriptors[field]) === null || _a === void 0 ? void 0 : _a.value; };
+const hasExactFields = (fields, required, allowed) => {
+    return required.every((field) => fields.includes(field))
+        && fields.every((field) => allowed.includes(field));
+};
+export const parseFunnelChoiceDescriptor = (stepType, choice) => {
+    if (!isChoiceStepType(stepType)) {
+        return { ok: false, issue: 'not-choice-step-type' };
+    }
+    const contract = FUNNEL_STEP_CONTRACTS[stepType].choice;
+    const record = readPlainDataRecord(choice);
+    if (record === null
+        || !hasExactFields(record.fields, ['answerKey'], ['answerKey', 'allowEmpty'])) {
+        return { ok: false, issue: 'invalid-descriptor-shape' };
+    }
+    const answerKey = readDescriptorValue(record, 'answerKey');
+    const allowEmpty = readDescriptorValue(record, 'allowEmpty');
+    const definesAllowEmpty = record.fields.includes('allowEmpty');
+    if (!isBoundedNonblankString(answerKey, MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH)
+        || !SAFE_ANSWER_KEY_PATTERN.test(answerKey)
+        || PROTOTYPE_DANGEROUS_ANSWER_KEYS.has(answerKey)) {
+        return { ok: false, issue: 'invalid-answer-key' };
+    }
+    if ((allowEmpty !== undefined && typeof allowEmpty !== 'boolean')
+        || (definesAllowEmpty && !contract.allowEmptyConfig)
+        || (allowEmpty === true && contract.cardinality === 'one')) {
+        return { ok: false, issue: 'invalid-allow-empty' };
+    }
+    return {
+        ok: true,
+        descriptor: allowEmpty === undefined ? { answerKey } : { answerKey, allowEmpty },
+        contract,
+        stepType,
+    };
+};
+const validateChoiceOptions = (options, presentation) => {
+    var _a;
+    const optionsRead = readBoundedDenseArray(options, 'options');
+    if (!optionsRead.ok) {
+        return {
+            valid: false,
+            optionIndex: (_a = optionsRead.index) !== null && _a !== void 0 ? _a : null,
+            issue: optionsRead.issue,
+        };
+    }
+    if (optionsRead.values.length === 0) {
+        return { valid: false, optionIndex: null, issue: 'options must be a non-empty array' };
+    }
+    const seenIds = new Set();
+    for (let optionIndex = 0; optionIndex < optionsRead.values.length; optionIndex += 1) {
+        const option = readPlainDataRecord(optionsRead.values[optionIndex]);
+        const required = presentation === 'emoji'
+            ? ['id', 'label', 'emoji']
+            : ['id', 'label'];
+        const allowed = presentation === 'emoji'
+            ? ['id', 'label', 'emoji']
+            : ['id', 'label', 'imageSrc', 'iconKey'];
+        if (option === null || !hasExactFields(option.fields, required, allowed)) {
+            return { valid: false, optionIndex, issue: 'option has invalid fields' };
+        }
+        const id = readDescriptorValue(option, 'id');
+        const label = readDescriptorValue(option, 'label');
+        const emoji = readDescriptorValue(option, 'emoji');
+        const imageSrc = readDescriptorValue(option, 'imageSrc');
+        const iconKey = readDescriptorValue(option, 'iconKey');
+        const hasValidCommonFields = isBoundedNonblankString(id, MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH) && isBoundedNonblankString(label, MAX_FUNNEL_CHOICE_CONTENT_STRING_LENGTH);
+        const hasValidPresentation = presentation === 'emoji'
+            ? isBoundedNonblankString(emoji, MAX_FUNNEL_CHOICE_CONTENT_STRING_LENGTH)
+            : (imageSrc === undefined || typeof imageSrc === 'string')
+                && (imageSrc === undefined || imageSrc.length <= MAX_FUNNEL_CHOICE_CONTENT_STRING_LENGTH)
+                && (iconKey === undefined || typeof iconKey === 'string')
+                && (iconKey === undefined || iconKey.length <= MAX_FUNNEL_CHOICE_CONTENT_STRING_LENGTH);
+        if (!hasValidCommonFields || !hasValidPresentation) {
+            return { valid: false, optionIndex, issue: 'option has invalid field values' };
+        }
+        if (seenIds.has(id)) {
+            return { valid: false, optionIndex, issue: 'option ID is duplicated' };
+        }
+        seenIds.add(id);
+    }
+    return { valid: true, ids: seenIds };
+};
+const selectionSummary = (ids) => {
+    try {
+        if (typeof ids === 'string') {
+            return { shape: 'string', length: ids.length };
+        }
+        if (Array.isArray(ids)) {
+            const lengthProperty = readOwnDataProperty(ids, 'length');
+            return lengthProperty.status === 'data' && typeof lengthProperty.value === 'number'
+                ? { shape: 'array', count: Math.min(lengthProperty.value, MAX_FUNNEL_CHOICE_ITEMS + 1) }
+                : { shape: 'array', count: 'invalid' };
+        }
+        return { shape: ids === null ? 'null' : typeof ids };
+    }
+    catch (_a) {
+        return { shape: 'uninspectable' };
+    }
+};
+export const buildChoiceCompletion = (stepMeta, options, ids) => {
+    const capturedMeta = captureChoiceStepMeta(stepMeta);
+    if (!capturedMeta.ok) {
+        return diagnostic('FG-CHOICE-001', capturedMeta.stepId, 'plain step metadata with bounded own id, type, and choice data properties', { issue: capturedMeta.issue }, 'Choice completion requires safely inspectable step metadata.', 'Provide plain step metadata with own data properties and bounded strings.');
+    }
+    const { id: stepId, type: stepType, choice } = capturedMeta;
+    const descriptorResult = parseFunnelChoiceDescriptor(stepType, choice);
+    if (!descriptorResult.ok) {
+        return diagnostic('FG-CHOICE-001', stepId, {
+            answerKey: 'bounded safe extensible identifier',
+            allowEmpty: 'omitted for single choice; optional boolean for multi-select',
+        }, {
+            descriptor: choice === undefined ? 'missing' : 'invalid',
+            issue: descriptorResult.issue,
+        }, 'Choice completion requires an exact valid choice descriptor.', 'Declare a safe answerKey and include allowEmpty only for multi-select choice steps.');
+    }
+    const { contract, descriptor } = descriptorResult;
+    const optionValidation = validateChoiceOptions(options, contract.presentation);
+    if (!optionValidation.valid) {
+        return diagnostic('FG-CHOICE-002', stepId, contract.presentation === 'emoji'
+            ? { fields: ['id', 'label', 'emoji'], values: 'nonblank strings', ids: 'unique' }
+            : {
+                requiredFields: ['id', 'label'],
+                optionalFields: ['imageSrc', 'iconKey'],
+                values: 'valid strings',
+                ids: 'unique',
+            }, { optionIndex: optionValidation.optionIndex, issue: optionValidation.issue }, 'The choice option content is invalid.', 'Provide a non-empty list of exact-schema options with stable unique IDs.');
+    }
+    if (contract.cardinality === 'one') {
+        if (typeof ids !== 'string'
+            || ids.length === 0
+            || ids.length > MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH
+            || !optionValidation.ids.has(ids)) {
+            return diagnostic('FG-CHOICE-002', stepId, 'one non-empty stable option ID', selectionSummary(ids), 'The single-choice selection is invalid.', 'Pass exactly one stable option ID from this step\'s option list.');
+        }
+        return {
+            answerKey: descriptor.answerKey,
+            value: ids,
+            selected: { [descriptor.answerKey]: ids },
+        };
+    }
+    const selectedRead = readBoundedDenseArray(ids, 'selection');
+    if (!selectedRead.ok) {
+        return diagnostic('FG-CHOICE-002', stepId, 'an array of unique stable option IDs', Object.assign(Object.assign({}, selectionSummary(ids)), { issue: selectedRead.issue }), 'The multi-choice selection has the wrong shape.', 'Pass an array containing only stable option IDs from this step\'s option list.');
+    }
+    const selectedIds = [];
+    const selectedIdSet = new Set();
+    let selectionIsValid = true;
+    for (const selectedId of selectedRead.values) {
+        if (!isBoundedNonblankString(selectedId, MAX_FUNNEL_CHOICE_IDENTIFIER_LENGTH)
+            || !optionValidation.ids.has(selectedId)
+            || selectedIdSet.has(selectedId)) {
+            selectionIsValid = false;
+            break;
+        }
+        selectedIdSet.add(selectedId);
+        selectedIds.push(selectedId);
+    }
+    if (!selectionIsValid || (selectedIds.length === 0 && descriptor.allowEmpty !== true)) {
+        return diagnostic('FG-CHOICE-002', stepId, descriptor.allowEmpty === true
+            ? 'an array of unique stable option IDs, including an explicit empty array'
+            : 'a non-empty array of unique stable option IDs', selectionSummary(ids), 'The multi-choice selection is invalid.', 'Pass unique stable option IDs and use an empty array only when allowEmpty is true.');
+    }
+    return {
+        answerKey: descriptor.answerKey,
+        value: selectedIds,
+        selected: { [descriptor.answerKey]: selectedIds },
+    };
+};