@funnelsgrove/runtime 0.1.55 → 0.1.59

package/dist/validation/funnel-manifest-input.normalization.d.ts

@@ -0,0 +1,67 @@
+import type { FunnelContractDiagnostic } from './funnel-contract-diagnostics.js';
+export declare const MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS = 4096;
+export type NormalizedStep = {
+    id: unknown;
+    name: unknown;
+    path: unknown;
+    filePath: unknown;
+    componentKey: unknown;
+    type: unknown;
+    kind: unknown;
+    choice: unknown;
+};
+type NormalizedEntryPoint = {
+    id: unknown;
+    stepId: unknown;
+    isDefault: unknown;
+};
+type NormalizedEdge = {
+    toStepId: unknown;
+    conditionId: unknown;
+};
+type NormalizedEdgeGroup = {
+    sourceStepId: string;
+    edges: readonly NormalizedEdge[];
+};
+type NormalizedBranch = {
+    id: unknown;
+    name: unknown;
+    sourceStepId: unknown;
+    stepIds: readonly unknown[];
+};
+type NormalizedVariant = {
+    variantKey: unknown;
+    routeToStepId: unknown;
+};
+type NormalizedExperiment = {
+    experimentId: unknown;
+    stepId: unknown;
+    variants: readonly NormalizedVariant[];
+};
+export type NormalizedManifest = {
+    stepContractVersion: unknown;
+    templateArchitectureVersion: unknown;
+    steps: readonly NormalizedStep[];
+    declaredStepCount: number;
+    hasValidStepRecords: boolean;
+    entryPoints: readonly NormalizedEntryPoint[];
+    edgeGroups: readonly NormalizedEdgeGroup[];
+    branches: readonly NormalizedBranch[];
+    experiments: readonly NormalizedExperiment[];
+};
+export type BoundaryDiagnosticInput = {
+    code: 'FG-STEP-002' | 'FG-FLOW-002';
+    expected: string;
+    received: unknown;
+    reason: string;
+    repair: string;
+};
+type BoundaryDiagnosticFactory = (input: BoundaryDiagnosticInput) => FunnelContractDiagnostic;
+type PlainDataRecord = Record<string, unknown>;
+export declare const isPlainDataRecord: (value: unknown) => value is PlainDataRecord;
+export type NormalizedManifestResult = {
+    manifest: NormalizedManifest | null;
+    diagnostics: FunnelContractDiagnostic[];
+};
+export declare const normalizeFunnelManifestInput: (input: unknown, createDiagnostic: BoundaryDiagnosticFactory) => NormalizedManifestResult;
+export {};

package/dist/validation/funnel-manifest-input.normalization.js

@@ -0,0 +1,386 @@
+export const MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS = 4096;
+const describeRuntimeValue = (value) => {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    return typeof value;
+};
+const sanitizeRuntimeScalar = (value) => {
+    if (value === null
+        || value === undefined
+        || typeof value === 'string'
+        || typeof value === 'number'
+        || typeof value === 'boolean') {
+        return value;
+    }
+    return Object.freeze({ runtimeType: describeRuntimeValue(value) });
+};
+export const isPlainDataRecord = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    // This boundary accepts parsed/plain data. Portable browser JavaScript cannot detect
+    // proxies without invoking reflection traps, so the public validator catches any
+    // reflection error (including revoked proxies) and returns a blocking diagnostic.
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+const readDataProperty = (record, key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (!descriptor) {
+        return { status: 'missing', value: undefined };
+    }
+    if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+        return { status: 'accessor', value: undefined };
+    }
+    return { status: 'data', value: descriptor.value };
+};
+const readDataRecord = (value, keys) => {
+    if (!isPlainDataRecord(value)) {
+        return null;
+    }
+    const fields = new Map();
+    for (const key of keys) {
+        const property = readDataProperty(value, key);
+        if (property.status === 'accessor') {
+            return null;
+        }
+        fields.set(key, property.value);
+    }
+    return fields;
+};
+const OVERSIZED_DATA_ARRAY = 'oversized';
+const isReadableDataArray = (value) => {
+    return value !== null && value !== OVERSIZED_DATA_ARRAY;
+};
+const arrayExpectation = (value, fallback) => {
+    return value === OVERSIZED_DATA_ARRAY
+        ? `array with at most ${MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS} items`
+        : fallback;
+};
+const readDataArray = (value) => {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
+    if (!lengthDescriptor
+        || !Object.prototype.hasOwnProperty.call(lengthDescriptor, 'value')
+        || typeof lengthDescriptor.value !== 'number') {
+        return null;
+    }
+    if (lengthDescriptor.value > MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS) {
+        return OVERSIZED_DATA_ARRAY;
+    }
+    const values = [];
+    for (let index = 0; index < lengthDescriptor.value; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor && !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+            return null;
+        }
+        values.push(descriptor === null || descriptor === void 0 ? void 0 : descriptor.value);
+    }
+    return { values, declaredLength: lengthDescriptor.value };
+};
+const readBoundedOwnPropertyNames = (record) => {
+    const keys = Object.getOwnPropertyNames(record);
+    return keys.length <= MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS ? keys : null;
+};
+const sanitizeChoiceValue = (value) => {
+    if (!isPlainDataRecord(value)) {
+        return sanitizeRuntimeScalar(value);
+    }
+    const entries = [];
+    const keys = readBoundedOwnPropertyNames(value);
+    if (!keys) {
+        return '[oversized choice descriptor]';
+    }
+    for (const key of keys.sort()) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+            return '[accessor choice descriptor]';
+        }
+        entries.push([key, sanitizeRuntimeScalar(descriptor.value)]);
+    }
+    return Object.fromEntries(entries);
+};
+export const normalizeFunnelManifestInput = (input, createDiagnostic) => {
+    var _a;
+    if (!isPlainDataRecord(input)) {
+        return {
+            manifest: null,
+            diagnostics: [createDiagnostic({
+                    code: 'FG-STEP-002',
+                    expected: 'plain funnel manifest object',
+                    received: describeRuntimeValue(input),
+                    reason: 'The funnel manifest must be a plain parsed-data object.',
+                    repair: 'Provide a JSON-compatible funnel manifest object.',
+                })],
+        };
+    }
+    const diagnostics = [];
+    const versionProperty = readDataProperty(input, 'stepContractVersion');
+    const architectureProperty = readDataProperty(input, 'templateArchitectureVersion');
+    const stepsProperty = readDataProperty(input, 'steps');
+    const entryPointsProperty = readDataProperty(input, 'entryPoints');
+    const edgesProperty = readDataProperty(input, 'edgesByStepId');
+    const branchesProperty = readDataProperty(input, 'branches');
+    const experimentsProperty = readDataProperty(input, 'experiments');
+    const stepContractVersion = versionProperty.status === 'accessor'
+        ? '[accessor stepContractVersion]'
+        : sanitizeRuntimeScalar(versionProperty.value);
+    const templateArchitectureVersion = architectureProperty.status === 'accessor'
+        ? '[accessor templateArchitectureVersion]'
+        : sanitizeRuntimeScalar(architectureProperty.value);
+    const steps = [];
+    const rawSteps = stepsProperty.status === 'data' ? stepsProperty.value : undefined;
+    const stepArray = readDataArray(rawSteps);
+    if (!isReadableDataArray(stepArray)) {
+        diagnostics.push(createDiagnostic({
+            code: 'FG-STEP-002',
+            expected: arrayExpectation(stepArray, 'steps array'),
+            received: describeRuntimeValue(stepsProperty.status === 'accessor' ? '[accessor]' : rawSteps),
+            reason: 'Manifest steps must be a parsed-data array.',
+            repair: 'Replace steps with an array of plain step metadata objects.',
+        }));
+    }
+    else {
+        stepArray.values.forEach((rawStep, index) => {
+            const fields = readDataRecord(rawStep, [
+                'id',
+                'name',
+                'path',
+                'filePath',
+                'componentKey',
+                'type',
+                'kind',
+                'choice',
+            ]);
+            if (!fields) {
+                diagnostics.push(createDiagnostic({
+                    code: 'FG-STEP-002',
+                    expected: 'plain step metadata object',
+                    received: describeRuntimeValue(rawStep),
+                    reason: `Manifest step at index ${index} is not a plain data record.`,
+                    repair: 'Replace the step with plain JSON-compatible metadata.',
+                }));
+                return;
+            }
+            steps.push({
+                id: sanitizeRuntimeScalar(fields.get('id')),
+                name: sanitizeRuntimeScalar(fields.get('name')),
+                path: sanitizeRuntimeScalar(fields.get('path')),
+                filePath: sanitizeRuntimeScalar(fields.get('filePath')),
+                componentKey: sanitizeRuntimeScalar(fields.get('componentKey')),
+                type: sanitizeRuntimeScalar(fields.get('type')),
+                kind: sanitizeRuntimeScalar(fields.get('kind')),
+                choice: sanitizeChoiceValue(fields.get('choice')),
+            });
+        });
+    }
+    const entryPoints = [];
+    const rawEntryPoints = entryPointsProperty.status === 'missing'
+        ? []
+        : entryPointsProperty.status === 'data'
+            ? entryPointsProperty.value
+            : undefined;
+    const entryPointArray = readDataArray(rawEntryPoints);
+    if (!isReadableDataArray(entryPointArray)) {
+        diagnostics.push(createDiagnostic({
+            code: 'FG-FLOW-002',
+            expected: arrayExpectation(entryPointArray, 'entryPoints array'),
+            received: describeRuntimeValue(entryPointsProperty.status === 'accessor' ? '[accessor]' : rawEntryPoints),
+            reason: 'Manifest entry points must be a parsed-data array when present.',
+            repair: 'Replace entryPoints with an array of plain entry point objects.',
+        }));
+    }
+    else {
+        entryPointArray.values.forEach((rawEntryPoint, index) => {
+            const fields = readDataRecord(rawEntryPoint, ['id', 'stepId', 'isDefault']);
+            if (!fields) {
+                diagnostics.push(createDiagnostic({
+                    code: 'FG-FLOW-002',
+                    expected: 'plain entry point object',
+                    received: describeRuntimeValue(rawEntryPoint),
+                    reason: `Entry point at index ${index} is not a plain data record.`,
+                    repair: 'Replace the entry point with plain JSON-compatible routing metadata.',
+                }));
+                return;
+            }
+            entryPoints.push({
+                id: sanitizeRuntimeScalar(fields.get('id')),
+                stepId: sanitizeRuntimeScalar(fields.get('stepId')),
+                isDefault: sanitizeRuntimeScalar(fields.get('isDefault')),
+            });
+        });
+    }
+    const edgeGroups = [];
+    const rawEdges = edgesProperty.status === 'data' ? edgesProperty.value : undefined;
+    if (!isPlainDataRecord(rawEdges)) {
+        diagnostics.push(createDiagnostic({
+            code: 'FG-FLOW-002',
+            expected: 'edgesByStepId plain object',
+            received: describeRuntimeValue(edgesProperty.status === 'accessor' ? '[accessor]' : rawEdges),
+            reason: 'Manifest edgesByStepId must be a plain parsed-data object.',
+            repair: 'Replace edgesByStepId with an object of source-step edge arrays.',
+        }));
+    }
+    else {
+        const sourceStepIds = readBoundedOwnPropertyNames(rawEdges);
+        if (!sourceStepIds) {
+            diagnostics.push(createDiagnostic({
+                code: 'FG-FLOW-002',
+                expected: `object with at most ${MAX_FUNNEL_MANIFEST_COLLECTION_ITEMS} keys`,
+                received: 'oversized object',
+                reason: 'Manifest edgesByStepId declares too many source keys.',
+                repair: 'Reduce the manifest edge source count before validation.',
+            }));
+        }
+        for (const sourceStepId of (_a = sourceStepIds === null || sourceStepIds === void 0 ? void 0 : sourceStepIds.sort()) !== null && _a !== void 0 ? _a : []) {
+            const descriptor = Object.getOwnPropertyDescriptor(rawEdges, sourceStepId);
+            const rawEdgeList = descriptor && Object.prototype.hasOwnProperty.call(descriptor, 'value')
+                ? descriptor.value
+                : undefined;
+            const edgeArray = readDataArray(rawEdgeList);
+            if (!isReadableDataArray(edgeArray)) {
+                diagnostics.push(createDiagnostic({
+                    code: 'FG-FLOW-002',
+                    expected: arrayExpectation(edgeArray, 'edge array'),
+                    received: describeRuntimeValue(rawEdgeList),
+                    reason: `Edges for source ${sourceStepId} must be a parsed-data array.`,
+                    repair: 'Replace the edge value with an array of plain edge objects.',
+                }));
+                continue;
+            }
+            const edges = [];
+            edgeArray.values.forEach((rawEdge, index) => {
+                const fields = readDataRecord(rawEdge, ['toStepId', 'conditionId']);
+                if (!fields) {
+                    diagnostics.push(createDiagnostic({
+                        code: 'FG-FLOW-002',
+                        expected: 'plain edge object',
+                        received: describeRuntimeValue(rawEdge),
+                        reason: `Edge ${sourceStepId}[${index}] is not a plain data record.`,
+                        repair: 'Replace the edge with plain JSON-compatible routing metadata.',
+                    }));
+                    return;
+                }
+                edges.push({
+                    toStepId: sanitizeRuntimeScalar(fields.get('toStepId')),
+                    conditionId: sanitizeRuntimeScalar(fields.get('conditionId')),
+                });
+            });
+            edgeGroups.push({ sourceStepId, edges });
+        }
+    }
+    const branches = [];
+    const rawBranches = branchesProperty.status === 'missing'
+        ? []
+        : branchesProperty.status === 'data'
+            ? branchesProperty.value
+            : undefined;
+    const branchArray = readDataArray(rawBranches);
+    if (!isReadableDataArray(branchArray)) {
+        diagnostics.push(createDiagnostic({
+            code: 'FG-FLOW-002',
+            expected: arrayExpectation(branchArray, 'branches array'),
+            received: describeRuntimeValue(branchesProperty.status === 'accessor' ? '[accessor]' : rawBranches),
+            reason: 'Manifest branches must be a parsed-data array when present.',
+            repair: 'Replace branches with an array of plain branch objects.',
+        }));
+    }
+    else {
+        branchArray.values.forEach((rawBranch, index) => {
+            const fields = readDataRecord(rawBranch, ['id', 'name', 'sourceStepId', 'stepIds']);
+            const rawStepIds = fields === null || fields === void 0 ? void 0 : fields.get('stepIds');
+            const stepIdArray = readDataArray(rawStepIds);
+            if (!fields || !isReadableDataArray(stepIdArray)) {
+                diagnostics.push(createDiagnostic({
+                    code: 'FG-FLOW-002',
+                    expected: arrayExpectation(stepIdArray, 'plain branch object with a stepIds array'),
+                    received: describeRuntimeValue(rawBranch),
+                    reason: `Branch at index ${index} has malformed routing metadata.`,
+                    repair: 'Replace the branch with plain metadata and an array of owned step ids.',
+                }));
+                return;
+            }
+            branches.push({
+                id: sanitizeRuntimeScalar(fields.get('id')),
+                name: sanitizeRuntimeScalar(fields.get('name')),
+                sourceStepId: sanitizeRuntimeScalar(fields.get('sourceStepId')),
+                stepIds: stepIdArray.values.map(sanitizeRuntimeScalar),
+            });
+        });
+    }
+    const experiments = [];
+    const rawExperiments = experimentsProperty.status === 'data'
+        ? experimentsProperty.value
+        : undefined;
+    const experimentArray = readDataArray(rawExperiments);
+    if (!isReadableDataArray(experimentArray)) {
+        diagnostics.push(createDiagnostic({
+            code: 'FG-FLOW-002',
+            expected: arrayExpectation(experimentArray, 'experiments array'),
+            received: describeRuntimeValue(experimentsProperty.status === 'accessor' ? '[accessor]' : rawExperiments),
+            reason: 'Manifest experiments must be a parsed-data array.',
+            repair: 'Replace experiments with an array of plain experiment objects.',
+        }));
+    }
+    else {
+        experimentArray.values.forEach((rawExperiment, index) => {
+            const fields = readDataRecord(rawExperiment, ['experimentId', 'stepId', 'variants']);
+            const rawVariants = fields === null || fields === void 0 ? void 0 : fields.get('variants');
+            const variantArray = readDataArray(rawVariants);
+            if (!fields || !isReadableDataArray(variantArray)) {
+                diagnostics.push(createDiagnostic({
+                    code: 'FG-FLOW-002',
+                    expected: arrayExpectation(variantArray, 'plain experiment object with a variants array'),
+                    received: describeRuntimeValue(rawExperiment),
+                    reason: `Experiment at index ${index} has malformed routing metadata.`,
+                    repair: 'Replace the experiment with plain metadata and an array of variants.',
+                }));
+                return;
+            }
+            const variants = [];
+            variantArray.values.forEach((rawVariant, variantIndex) => {
+                const variantFields = readDataRecord(rawVariant, ['variantKey', 'routeToStepId']);
+                if (!variantFields) {
+                    diagnostics.push(createDiagnostic({
+                        code: 'FG-FLOW-002',
+                        expected: 'plain experiment variant object',
+                        received: describeRuntimeValue(rawVariant),
+                        reason: `Variant ${index}[${variantIndex}] is not a plain data record.`,
+                        repair: 'Replace the variant with plain JSON-compatible routing metadata.',
+                    }));
+                    return;
+                }
+                variants.push({
+                    variantKey: sanitizeRuntimeScalar(variantFields.get('variantKey')),
+                    routeToStepId: sanitizeRuntimeScalar(variantFields.get('routeToStepId')),
+                });
+            });
+            experiments.push({
+                experimentId: sanitizeRuntimeScalar(fields.get('experimentId')),
+                stepId: sanitizeRuntimeScalar(fields.get('stepId')),
+                variants,
+            });
+        });
+    }
+    return {
+        manifest: {
+            stepContractVersion,
+            templateArchitectureVersion,
+            steps,
+            declaredStepCount: isReadableDataArray(stepArray) ? stepArray.declaredLength : 1,
+            hasValidStepRecords: isReadableDataArray(stepArray)
+                && steps.length === stepArray.declaredLength,
+            entryPoints,
+            edgeGroups,
+            branches,
+            experiments,
+        },
+        diagnostics,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/runtime",
-  "version": "0.1.55",
+  "version": "0.1.59",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",
@@ -26,6 +26,11 @@
       "types": "./dist/services/public-env.d.ts",
       "import": "./dist/services/public-env.js",
       "default": "./dist/services/public-env.js"
+    },
+    "./testing/funnel-contract-journey": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     }
   },
   "files": [
@@ -46,9 +51,12 @@
     "react-dom": "19.2.3"
   },
   "devDependencies": {
+    "@testing-library/react": "16.3.1",
     "@types/node": "^20",
+    "@types/jsdom": "^21.1.7",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "jsdom": "^20.0.3",
     "typescript": "^5",
     "vitest": "^3.2.4"
   }