@featurevisor/core 2.17.0 → 2.19.0

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,
@@ -51,6 +46,7 @@ function resolveVariableSchema(
     type?: string;
     items?: unknown;
     properties?: unknown;
+    additionalProperties?: unknown;
     required?: string[];
     enum?: unknown[];
     const?: unknown;
@@ -69,6 +65,7 @@ function resolveVariableSchema(
   type?: string;
   items?: unknown;
   properties?: unknown;
+  additionalProperties?: unknown;
   required?: string[];
   enum?: unknown[];
   const?: unknown;
@@ -89,6 +86,7 @@ function resolveVariableSchema(
     type?: string;
     items?: unknown;
     properties?: unknown;
+    additionalProperties?: unknown;
     required?: string[];
     enum?: unknown[];
     const?: unknown;
@@ -133,6 +131,7 @@ function valueMatchesSchema(
     enum?: unknown[];
     oneOf?: unknown[];
     properties?: Record<string, unknown>;
+    additionalProperties?: unknown;
     required?: string[];
     items?: unknown;
     minimum?: number;
@@ -195,8 +194,16 @@ function valueMatchesSchema(
   if (type === "object") {
     if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
     const props = resolved.properties;
-    if (!props || typeof props !== "object") return true;
+    const additional = resolved.additionalProperties;
     const obj = value as Record<string, unknown>;
+    if ((!props || typeof props !== "object") && (!additional || typeof additional !== "object")) {
+      return true;
+    }
+    if (!props || typeof props !== "object") {
+      return Object.keys(obj).every((key) =>
+        valueMatchesSchema(additional as { [k: string]: unknown }, obj[key], schemasByKey),
+      );
+    }
     const required = new Set(resolved.required || []);
     for (const key of required) {
       if (!Object.prototype.hasOwnProperty.call(obj, key)) return false;
@@ -205,9 +212,15 @@ function valueMatchesSchema(
     }
     for (const key of Object.keys(obj)) {
       const propSchema = props[key];
-      if (!propSchema) return false;
-      if (!valueMatchesSchema(propSchema as { [k: string]: unknown }, obj[key], schemasByKey))
+      if (propSchema) {
+        if (!valueMatchesSchema(propSchema as { [k: string]: unknown }, obj[key], schemasByKey))
+          return false;
+      } else if (additional && typeof additional === "object") {
+        if (!valueMatchesSchema(additional as { [k: string]: unknown }, obj[key], schemasByKey))
+          return false;
+      } else {
         return false;
+      }
     }
     return true;
   }
@@ -259,6 +272,7 @@ function valueDeepEqual(a: unknown, b: unknown): boolean {
 type SchemaLikeForRequired = {
   type?: string;
   properties?: Record<string, unknown>;
+  additionalProperties?: unknown;
   required?: string[];
   items?: unknown;
   schema?: string;
@@ -325,6 +339,19 @@ function refineRequiredKeysInSchema(
       }
     }
   }
+  const additionalProperties = (current as { additionalProperties?: unknown }).additionalProperties;
+  if (
+    additionalProperties &&
+    typeof additionalProperties === "object" &&
+    !Array.isArray(additionalProperties)
+  ) {
+    refineRequiredKeysInSchema(
+      additionalProperties as SchemaLikeForRequired,
+      [...pathPrefix, "additionalProperties"],
+      ctx,
+      schemasByKey,
+    );
+  }
 
   if (items && typeof items === "object" && !Array.isArray(items)) {
     refineRequiredKeysInSchema(
@@ -453,6 +480,7 @@ function refineVariableValueObject(
   projectConfig: ProjectConfig,
   variableSchema: {
     properties?: Record<string, unknown>;
+    additionalProperties?: unknown;
     required?: string[];
     type: string;
   },
@@ -464,6 +492,7 @@ function refineVariableValueObject(
 ): void {
   const label = getVariableLabel(variableSchema, variableKey, path);
   const schemaProperties = variableSchema.properties;
+  const additionalProperties = variableSchema.additionalProperties;
 
   if (schemaProperties && typeof schemaProperties === "object") {
     const requiredKeys =
@@ -485,7 +514,17 @@ function refineVariableValueObject(
 
     for (const key of Object.keys(variableValue)) {
       const propSchema = schemaProperties[key];
-      if (!propSchema) {
+      if (!propSchema && additionalProperties && typeof additionalProperties === "object") {
+        superRefineVariableValue(
+          projectConfig,
+          additionalProperties as Parameters<typeof superRefineVariableValue>[1],
+          variableValue[key],
+          [...path, key],
+          ctx,
+          key,
+          schemasByKey,
+        );
+      } else if (!propSchema) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message: `Unknown property "${key}" in variable "${label}" (not in schema)`,
@@ -503,6 +542,18 @@ function refineVariableValueObject(
         );
       }
     }
+  } else if (additionalProperties && typeof additionalProperties === "object") {
+    for (const key of Object.keys(variableValue)) {
+      superRefineVariableValue(
+        projectConfig,
+        additionalProperties as Parameters<typeof superRefineVariableValue>[1],
+        variableValue[key],
+        [...path, key],
+        ctx,
+        key,
+        schemasByKey,
+      );
+    }
   } else {
     for (const key of Object.keys(variableValue)) {
       const propValue = variableValue[key];
@@ -944,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
@@ -1009,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) {
@@ -1087,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);
 
@@ -1135,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(),
@@ -1280,6 +1524,7 @@ export function getFeatureZodSchema(
               type: z.union([z.literal("json"), propertyTypeEnum]).optional(),
               items: schemaZodSchema.optional(),
               properties: z.record(schemaZodSchema).optional(),
+              additionalProperties: schemaZodSchema.optional(),
               required: z.array(z.string()).optional(),
               enum: z.array(variableValueZodSchema).optional(),
               const: variableValueZodSchema.optional(),
@@ -1315,7 +1560,7 @@ export function getFeatureZodSchema(
                 ctx.addIssue({
                   code: z.ZodIssueCode.custom,
                   message:
-                    "Variable schema cannot have both `schema` (reference) and inline properties (`type`, `oneOf`, `properties`, `required`, `items`). Use one or the other.",
+                    "Variable schema cannot have both `schema` (reference) and inline properties (`type`, `oneOf`, `properties`, `additionalProperties`, `required`, `items`). Use one or the other.",
                   path: [],
                 });
                 return;
@@ -1324,6 +1569,8 @@ export function getFeatureZodSchema(
                 const hasInlineStructure =
                   ("type" in variableSchema && variableSchema.type != null) ||
                   ("properties" in variableSchema && variableSchema.properties != null) ||
+                  ("additionalProperties" in variableSchema &&
+                    variableSchema.additionalProperties != null) ||
                   ("required" in variableSchema && variableSchema.required != null) ||
                   ("items" in variableSchema && variableSchema.items != null) ||
                   ("oneOf" in variableSchema && variableSchema.oneOf != null);
@@ -1340,7 +1587,7 @@ export function getFeatureZodSchema(
                   ctx.addIssue({
                     code: z.ZodIssueCode.custom,
                     message:
-                      "When `schema` is set, do not set `type`, `oneOf`, `properties`, `required`, or `items`.",
+                      "When `schema` is set, do not set `type`, `oneOf`, `properties`, `additionalProperties`, `required`, or `items`.",
                     path: [],
                   });
                 }
@@ -1400,13 +1647,13 @@ export function getFeatureZodSchema(
                       z
                         .object({
                           conditions: conditionsZodSchema,
-                          value: variableValueZodSchema,
+                          value: overrideValueZodSchema,
                         })
                         .strict(),
                       z
                         .object({
                           segments: groupSegmentsZodSchema,
-                          value: variableValueZodSchema,
+                          value: overrideValueZodSchema,
                         })
                         .strict(),
                     ]),
@@ -1593,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

@@ -257,6 +257,17 @@ describe("mutationNotation.ts", () => {
       expect(result).toBeNull();
     });
 
+    it("resolves unknown object key via additionalProperties", () => {
+      const result = resolveSchemaAtPath(
+        {
+          type: "object",
+          additionalProperties: { type: "string" },
+        },
+        [{ key: "dynamicKey" }],
+      );
+      expect(result).toEqual({ type: "string" });
+    });
+
     it("returns null when stepping into non-object", () => {
       const result = resolveSchemaAtPath(objectSchema, [{ key: "width" }, { key: "foo" }]);
       expect(result).toBeNull();
@@ -384,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)", () => {
@@ -446,6 +472,18 @@ describe("mutationNotation.ts", () => {
         expect(r.error).toContain("path does not exist");
       });
 
+      it("valid when path uses additionalProperties", () => {
+        const schemas: Record<string, Schema> = {
+          labels: {
+            type: "object",
+            additionalProperties: { type: "string" },
+          },
+        };
+        const r = validateMutationKey("labels.headline", schemas);
+        expect(r.valid).toBe(true);
+        expect(r.valueSchema).toEqual({ type: "string" });
+      });
+
       it("invalid when target schema is oneOf", () => {
         const schemas: Record<string, Schema> = {
           x: {
@@ -535,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);
@@ -589,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);