@featurevisor/core 2.18.0 → 2.19.0

package/src/linter/featureSchema.spec.ts

@@ -610,6 +610,34 @@ describe("featureSchema.ts :: getFeatureZodSchema (variablesSchema and variable
         "maxLength",
       );
     });
+
+    it("accepts plain-key partial object overrides for structured object schemas", () => {
+      expectParseSuccess(
+        baseFeature({
+          variablesSchema: {
+            config: {
+              type: "object",
+              properties: {
+                theme: { type: "string" },
+                compact: { type: "boolean" },
+              },
+              required: ["theme", "compact"],
+              defaultValue: { theme: "light", compact: true },
+            },
+          },
+          variations: [
+            { value: "control", weight: 50 },
+            {
+              value: "treatment",
+              weight: 50,
+              variableOverrides: {
+                config: [{ segments: "*", value: { theme: "dark" } }],
+              },
+            },
+          ],
+        }),
+      );
+    });
   });
 
   describe("rules: variables", () => {
@@ -701,6 +729,175 @@ describe("featureSchema.ts :: getFeatureZodSchema (variablesSchema and variable
     });
   });
 
+  describe("rules: variableOverrides", () => {
+    it("accepts rule variableOverrides with values matching variablesSchema", () => {
+      expectParseSuccess(
+        baseFeature({
+          variablesSchema: {
+            config: {
+              type: "object",
+              properties: {
+                title: { type: "string" },
+                nested: {
+                  type: "object",
+                  properties: {
+                    count: { type: "integer" },
+                  },
+                },
+              },
+              defaultValue: {
+                title: "default",
+                nested: { count: 0 },
+              },
+            },
+          },
+          rules: {
+            staging: [
+              {
+                key: "r1",
+                segments: "*",
+                percentage: 100,
+                variableOverrides: {
+                  config: [
+                    {
+                      segments: "countries/germany",
+                      value: {
+                        "nested.count": 5,
+                      },
+                    },
+                  ],
+                },
+              },
+            ],
+            production: [{ key: "r1", segments: "*", percentage: 100 }],
+          },
+        }),
+      );
+    });
+
+    it("rejects rule variableOverrides for unknown variable key", () => {
+      expectParseFailure(
+        baseFeature({
+          variablesSchema: {
+            config: { type: "string", defaultValue: "x" },
+          },
+          rules: {
+            staging: [
+              {
+                key: "r1",
+                segments: "*",
+                percentage: 100,
+                variableOverrides: {
+                  unknown: [{ segments: "*", value: "x" }],
+                },
+              },
+            ],
+            production: [{ key: "r1", segments: "*", percentage: 100 }],
+          },
+        }),
+        "not defined in",
+      );
+    });
+
+    it("rejects mutation notation in rule variableOverrides key", () => {
+      expectParseFailure(
+        baseFeature({
+          variablesSchema: {
+            config: {
+              type: "object",
+              properties: { title: { type: "string" } },
+              defaultValue: { title: "x" },
+            },
+          },
+          rules: {
+            staging: [
+              {
+                key: "r1",
+                segments: "*",
+                percentage: 100,
+                variableOverrides: {
+                  "config.title": [{ segments: "*", value: "y" }],
+                },
+              },
+            ],
+            production: [{ key: "r1", segments: "*", percentage: 100 }],
+          },
+        }),
+        "must be a declared variable key",
+      );
+    });
+
+    it("rejects rule variableOverride path not present in schema", () => {
+      expectParseFailure(
+        baseFeature({
+          variablesSchema: {
+            config: {
+              type: "object",
+              properties: { title: { type: "string" } },
+              defaultValue: { title: "x" },
+            },
+          },
+          rules: {
+            staging: [
+              {
+                key: "r1",
+                segments: "*",
+                percentage: 100,
+                variableOverrides: {
+                  config: [
+                    {
+                      segments: "*",
+                      value: {
+                        "nested.missing": "x",
+                      },
+                    },
+                  ],
+                },
+              },
+            ],
+            production: [{ key: "r1", segments: "*", percentage: 100 }],
+          },
+        }),
+        "invalid for variable",
+      );
+    });
+
+    it("rejects non-null payload for :remove in rule variableOverrides", () => {
+      expectParseFailure(
+        baseFeature({
+          variablesSchema: {
+            config: {
+              type: "object",
+              properties: { title: { type: "string" }, optional: { type: "string" } },
+              defaultValue: { title: "x", optional: "y" },
+            },
+          },
+          rules: {
+            staging: [
+              {
+                key: "r1",
+                segments: "*",
+                percentage: 100,
+                variableOverrides: {
+                  config: [
+                    {
+                      conditions: [{ attribute: "country", operator: "equals", value: "de" }],
+                      value: {
+                        "optional:remove": "not-null",
+                      },
+                    },
+                  ],
+                },
+              },
+            ],
+            production: [{ key: "r1", segments: "*", percentage: 100 }],
+          },
+        }),
+        "must use `null` as value",
+      );
+    });
+  });
+
   describe("force: variables", () => {
     it("accepts force variables that match variablesSchema", () => {
       expectParseSuccess(

package/src/linter/featureSchema.ts

@@ -2,12 +2,7 @@ import type { Schema, SchemaType } from "@featurevisor/types";
 import { z } from "zod";
 
 import { ProjectConfig } from "../config";
-import {
-  isMutationKey,
-  validateMutationKey,
-  parsePathMapKey,
-  resolveSchemaAtPath,
-} from "./mutationNotation";
+import { isMutationKey, validateMutationKey } from "./mutationNotation";
 import {
   valueZodSchema,
   propertyTypeEnum,
@@ -1000,6 +995,162 @@ function refineVariableEntry(
   );
 }
 
+function refineVariableOverrides({
+  ctx,
+  variableSchemaByKey,
+  variableOverrides,
+  pathPrefix,
+  projectConfig,
+  schemasByKey,
+}: {
+  ctx: z.RefinementCtx;
+  variableSchemaByKey: Record<string, unknown>;
+  variableOverrides: Record<string, Array<{ value?: unknown }>>;
+  pathPrefix: (string | number)[];
+  projectConfig: ProjectConfig;
+  schemasByKey?: Record<string, Schema>;
+}) {
+  for (const variableKey of Object.keys(variableOverrides)) {
+    if (isMutationKey(variableKey)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          `Variable override key "${variableKey}" must be a declared variable key, not mutation notation. ` +
+          "Use mutation notation inside each override's `value` object.",
+        path: [...pathPrefix, variableKey],
+      });
+      continue;
+    }
+
+    const variableSchema = variableSchemaByKey[variableKey];
+    if (!variableSchema) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${variableKey}" is not defined in \`variablesSchema\`.`,
+        path: [...pathPrefix, variableKey],
+      });
+      continue;
+    }
+
+    const variableSchemaWithRef = variableSchema as { schema?: string };
+    const resolvedVariableSchema = resolveVariableSchema(
+      variableSchema as Parameters<typeof resolveVariableSchema>[0],
+      schemasByKey,
+    );
+    if (variableSchemaWithRef.schema) {
+      if (!resolvedVariableSchema) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Schema "${variableSchemaWithRef.schema}" could not be loaded for variable "${variableKey}".`,
+          path: [...pathPrefix, variableKey],
+        });
+        continue;
+      }
+    }
+
+    const overrides = variableOverrides[variableKey];
+    if (!Array.isArray(overrides)) {
+      continue;
+    }
+
+    overrides.forEach((override, overrideN) => {
+      const overrideValue = override.value;
+      const valuePath = [...pathPrefix, variableKey, overrideN, "value"];
+
+      if (
+        typeof overrideValue === "object" &&
+        overrideValue !== null &&
+        !Array.isArray(overrideValue)
+      ) {
+        const pathMap = overrideValue as Record<string, unknown>;
+        const pathKeys = Object.keys(pathMap);
+        const hasStructuredObjectSchema =
+          resolvedVariableSchema?.type === "object" &&
+          (Boolean(resolvedVariableSchema.properties) ||
+            Boolean(resolvedVariableSchema.additionalProperties));
+        const treatAsPathMap =
+          pathKeys.some((pathKey) => isMutationKey(pathKey)) ||
+          (hasStructuredObjectSchema && pathKeys.length > 0);
+
+        if (treatAsPathMap) {
+          for (const pathKey of pathKeys) {
+            const composedMutationKey = `${variableKey}.${pathKey}`;
+            const validation = validateMutationKey(
+              composedMutationKey,
+              variableSchemaByKey as Record<string, Schema>,
+              schemasByKey,
+            );
+
+            if (!validation.valid) {
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message:
+                  validation.error ??
+                  `Invalid mutation path "${pathKey}" in variableOverride for "${variableKey}".`,
+                path: [...valuePath, pathKey],
+              });
+              continue;
+            }
+
+            if (validation.operation === "remove") {
+              if (pathMap[pathKey] !== null) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  message: `Mutation "${pathKey}:remove" must use \`null\` as value.`,
+                  path: [...valuePath, pathKey],
+                });
+              }
+              continue;
+            }
+
+            const fallbackValueSchema =
+              validation.operation === "append" ||
+              validation.operation === "prepend" ||
+              validation.operation === "before" ||
+              validation.operation === "after"
+                ? ({ type: "string" } as Schema)
+                : null;
+            const valueSchema = validation.valueSchema ?? fallbackValueSchema;
+            if (!valueSchema) {
+              continue;
+            }
+
+            superRefineVariableValue(
+              projectConfig,
+              valueSchema,
+              pathMap[pathKey],
+              [...valuePath, pathKey],
+              ctx,
+              pathKey,
+              schemasByKey,
+            );
+          }
+        } else {
+          superRefineVariableValue(
+            projectConfig,
+            variableSchema as Parameters<typeof superRefineVariableValue>[1],
+            overrideValue,
+            valuePath,
+            ctx,
+            variableKey,
+            schemasByKey,
+          );
+        }
+      } else {
+        superRefineVariableValue(
+          projectConfig,
+          variableSchema as Parameters<typeof superRefineVariableValue>[1],
+          overrideValue,
+          valuePath,
+          ctx,
+          variableKey,
+          schemasByKey,
+        );
+      }
+    });
+  }
+}
+
 function refineForce({
   ctx,
   parsedFeature, // eslint-disable-line
@@ -1065,6 +1216,18 @@ function refineRules({
       });
     }
 
+    // rules[n].variableOverrides[key][].value (path-map or full value)
+    if (rule.variableOverrides) {
+      refineVariableOverrides({
+        ctx,
+        variableSchemaByKey,
+        variableOverrides: rule.variableOverrides,
+        pathPrefix: [...pathPrefix, ruleN, "variableOverrides"],
+        projectConfig,
+        schemasByKey,
+      });
+    }
+
     // rules[n].variationWeights
     if (rule.variationWeights) {
       if (!parsedFeature.variations) {
@@ -1143,6 +1306,11 @@ export function getFeatureZodSchema(
   const schemaZodSchema = getSchemaZodSchema(availableSchemaKeys);
   const variableValueZodSchema = valueZodSchema;
   const variableValueOrNullZodSchema = z.union([valueZodSchema, z.null()]);
+  const overridePathMapValueZodSchema = z.record(variableValueOrNullZodSchema);
+  const overrideValueZodSchema = z.union([
+    variableValueOrNullZodSchema,
+    overridePathMapValueZodSchema,
+  ]);
 
   const variationValueZodSchema = z.string().min(1);
 
@@ -1191,6 +1359,26 @@ export function getFeatureZodSchema(
           enabled: z.boolean().optional(),
           variation: variationValueZodSchema.optional(),
           variables: z.record(variableValueOrNullZodSchema).optional(),
+          variableOverrides: z
+            .record(
+              z.array(
+                z.union([
+                  z
+                    .object({
+                      conditions: conditionsZodSchema,
+                      value: overrideValueZodSchema,
+                    })
+                    .strict(),
+                  z
+                    .object({
+                      segments: groupSegmentsZodSchema,
+                      value: overrideValueZodSchema,
+                    })
+                    .strict(),
+                ]),
+              ),
+            )
+            .optional(),
           variationWeights: z.record(z.number().min(0).max(100)).optional(),
         })
         .strict(),
@@ -1459,13 +1647,13 @@ export function getFeatureZodSchema(
                       z
                         .object({
                           conditions: conditionsZodSchema,
-                          value: variableValueZodSchema,
+                          value: overrideValueZodSchema,
                         })
                         .strict(),
                       z
                         .object({
                           segments: groupSegmentsZodSchema,
-                          value: variableValueZodSchema,
+                          value: overrideValueZodSchema,
                         })
                         .strict(),
                     ]),
@@ -1652,107 +1840,14 @@ export function getFeatureZodSchema(
 
           // variations[n].variableOverrides[key][].value (path-map or full value)
           if (variation.variableOverrides) {
-            for (const variableKey of Object.keys(variation.variableOverrides)) {
-              const variableSchema = variableSchemaByKey[variableKey];
-              if (!variableSchema) {
-                ctx.addIssue({
-                  code: z.ZodIssueCode.custom,
-                  message: `Variable "${variableKey}" is not defined in \`variablesSchema\`.`,
-                  path: ["variations", variationN, "variableOverrides", variableKey],
-                });
-                continue;
-              }
-              // When variable references a schema by name, ensure it can be resolved
-              const variableSchemaWithRef = variableSchema as { schema?: string };
-              if (variableSchemaWithRef.schema) {
-                const resolvedVarSchema = resolveVariableSchema(
-                  variableSchema as Parameters<typeof resolveVariableSchema>[0],
-                  schemasByKey,
-                );
-                if (!resolvedVarSchema) {
-                  ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: `Schema "${variableSchemaWithRef.schema}" could not be loaded for variable "${variableKey}".`,
-                    path: ["variations", variationN, "variableOverrides", variableKey],
-                  });
-                  continue;
-                }
-              }
-              const overrides = variation.variableOverrides[variableKey];
-              if (!Array.isArray(overrides)) continue;
-              overrides.forEach((override, overrideN) => {
-                const overrideValue = override.value;
-                const valuePath = [
-                  "variations",
-                  variationN,
-                  "variableOverrides",
-                  variableKey,
-                  overrideN,
-                  "value",
-                ];
-                if (
-                  typeof overrideValue === "object" &&
-                  overrideValue !== null &&
-                  !Array.isArray(overrideValue)
-                ) {
-                  const pathMap = overrideValue as Record<string, unknown>;
-                  for (const pathKey of Object.keys(pathMap)) {
-                    const pathSegments = parsePathMapKey(pathKey);
-                    if (!pathSegments || pathSegments.length === 0) {
-                      ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
-                        message: `Invalid mutation path "${pathKey}" in variableOverride for "${variableKey}".`,
-                        path: [...valuePath, pathKey],
-                      });
-                      continue;
-                    }
-                    const atPathSchema = resolveSchemaAtPath(
-                      variableSchema as Schema,
-                      pathSegments,
-                      schemasByKey,
-                    );
-                    if (!atPathSchema) {
-                      const effectiveSchema = resolveVariableSchema(
-                        variableSchema as Parameters<typeof resolveVariableSchema>[0],
-                        schemasByKey,
-                      );
-                      const isFlatObject =
-                        effectiveSchema?.type === "object" &&
-                        (!effectiveSchema.properties ||
-                          Object.keys(effectiveSchema.properties).length === 0);
-                      if (isFlatObject) {
-                        continue;
-                      }
-                      ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
-                        message: `Path "${pathKey}" is invalid for variable "${variableKey}" (not in schema).`,
-                        path: [...valuePath, pathKey],
-                      });
-                      continue;
-                    }
-                    superRefineVariableValue(
-                      projectConfig,
-                      atPathSchema,
-                      pathMap[pathKey],
-                      [...valuePath, pathKey],
-                      ctx,
-                      pathKey,
-                      schemasByKey,
-                    );
-                  }
-                } else {
-                  superRefineVariableValue(
-                    projectConfig,
-                    variableSchema as Parameters<typeof superRefineVariableValue>[1],
-                    overrideValue,
-                    valuePath,
-                    ctx,
-                    variableKey,
-                    schemasByKey,
-                  );
-                }
-              });
-            }
+            refineVariableOverrides({
+              ctx,
+              variableSchemaByKey,
+              variableOverrides: variation.variableOverrides,
+              pathPrefix: ["variations", variationN, "variableOverrides"],
+              projectConfig,
+              schemasByKey,
+            });
           }
         });
       }

package/src/linter/mutationNotation.spec.ts

@@ -395,6 +395,21 @@ describe("mutationNotation.ts", () => {
       tags: arraySchema,
       items: arrayOfObjectsSchema,
       settings: nestedObjectSchema,
+      partialMutationShowcase: {
+        type: "object",
+        properties: {
+          rows: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                id: { type: "integer" },
+                label: { type: "string" },
+              },
+            },
+          },
+        },
+      },
     };
 
     it("returns invalid when key is empty (parseMutationKey null)", () => {
@@ -558,6 +573,22 @@ describe("mutationNotation.ts", () => {
         expect(r.operation).toBe("before");
       });
 
+      it("valid on nested array selector segment in object variable", () => {
+        const r = validateMutationKey(
+          "partialMutationShowcase.rows[id=1]:after",
+          variableSchemaByKey,
+        );
+        expect(r.valid).toBe(true);
+        expect(r.operation).toBe("after");
+        expect(r.valueSchema).toEqual({
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            label: { type: "string" },
+          },
+        });
+      });
+
       it("invalid when path does not exist or does not point to array element", () => {
         const r = validateMutationKey("config.fake[0]:after", variableSchemaByKey);
         expect(r.valid).toBe(false);
@@ -612,6 +643,14 @@ describe("mutationNotation.ts", () => {
         expect(r.valid).toBe(true);
       });
 
+      it("valid when removing nested array element by selector", () => {
+        const r = validateMutationKey(
+          "partialMutationShowcase.rows[id=2]:remove",
+          variableSchemaByKey,
+        );
+        expect(r.valid).toBe(true);
+      });
+
       it("invalid when path does not exist", () => {
         const r = validateMutationKey("config.bad:remove", variableSchemaByKey);
         expect(r.valid).toBe(false);

package/src/linter/mutationNotation.ts

@@ -132,12 +132,7 @@ function getContainerSchemaAtPath(
   const lastSegment = pathSegments[pathSegments.length - 1];
   for (const seg of pathWithoutLast) {
     if (isOneOfSchema(current)) return null;
-    if ("index" in seg || "selector" in seg) {
-      if (current.type !== "array") return null;
-      const itemSchema = current.items;
-      if (!itemSchema || typeof itemSchema !== "object") return null;
-      current = resolveSchemaRef(itemSchema, schemasByKey);
-    } else {
+    if (seg.key) {
       if (current.type !== "object") return null;
       const props = current.properties;
       const additional = current.additionalProperties;
@@ -150,12 +145,40 @@ function getContainerSchemaAtPath(
       }
       current = resolveSchemaRef(next, schemasByKey);
     }
+    if ("index" in seg || "selector" in seg) {
+      if (current?.type !== "array") return null;
+      const itemSchema = current.items;
+      if (!itemSchema || typeof itemSchema !== "object") return null;
+      current = resolveSchemaRef(itemSchema, schemasByKey);
+    }
     if (!current) return null;
   }
   if (!current) return null;
   const parentSchema = current;
   if ("index" in lastSegment || "selector" in lastSegment) {
-    return { containerSchema: parentSchema, lastSegment, parentSchema };
+    let arraySchema: Schema | null = parentSchema;
+    if (lastSegment.key) {
+      if (arraySchema.type !== "object") return null;
+      const props = arraySchema.properties;
+      const additional = arraySchema.additionalProperties;
+      const next = props && typeof props === "object" ? props[lastSegment.key] : undefined;
+      if (next === undefined) {
+        if (!additional || typeof additional !== "object") return null;
+        arraySchema = resolveSchemaRef(additional, schemasByKey);
+      } else {
+        arraySchema = resolveSchemaRef(next, schemasByKey);
+      }
+      if (!arraySchema) return null;
+    }
+    const normalizedLastSegment =
+      "index" in lastSegment
+        ? ({ key: "", index: lastSegment.index } as PathSegment)
+        : ({ key: "", selector: lastSegment.selector } as PathSegment);
+    return {
+      containerSchema: arraySchema,
+      lastSegment: normalizedLastSegment,
+      parentSchema: arraySchema,
+    };
   }
   const propSchema =
     parentSchema.properties?.[lastSegment.key] ?? parentSchema.additionalProperties;