@featurevisor/core 2.9.0 → 2.11.0

package/src/linter/featureSchema.ts

@@ -1,23 +1,221 @@
 import { z } from "zod";
 
 import { ProjectConfig } from "../config";
+import { valueZodSchema, propertyTypeEnum, getPropertyZodSchema } from "./propertySchema";
 
 const tagRegex = /^[a-z0-9-]+$/;
 
-function isFlatObject(value) {
-  let isFlat = true;
+function isArrayOfStrings(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+function isFlatObjectValue(value: unknown): boolean {
+  return (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  );
+}
+
+function getVariableLabel(variableSchema, variableKey, path) {
+  return (
+    variableKey ??
+    variableSchema?.key ??
+    (path.length > 0 ? String(path[path.length - 1]) : "variable")
+  );
+}
+
+/**
+ * Recursively validates that every `required` array (at this level and in nested
+ * object/array schemas) only contains keys that exist in the same level's `properties`.
+ * Adds Zod issues with the correct path for invalid required field names.
+ */
+function refineRequiredKeysInSchema(
+  schema: {
+    type?: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    items?: unknown;
+  },
+  pathPrefix: (string | number)[],
+  ctx: z.RefinementCtx,
+): void {
+  if (!schema || typeof schema !== "object") return;
+
+  const effectiveType = schema.type;
+  const properties = schema.properties;
+  const required = schema.required;
+  const items = schema.items;
+
+  if (
+    effectiveType === "object" &&
+    Array.isArray(required) &&
+    required.length > 0 &&
+    properties &&
+    typeof properties === "object"
+  ) {
+    const allowedKeys = Object.keys(properties);
+    required.forEach((key, index) => {
+      if (!allowedKeys.includes(key)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Unknown required field "${key}". \`required\` must only contain property names defined in \`properties\`. Allowed: ${allowedKeys.length ? allowedKeys.join(", ") : "(none)"}.`,
+          path: [...pathPrefix, "required", index],
+        });
+      }
+    });
+  }
 
-  Object.keys(value).forEach((key) => {
-    if (typeof value[key] === "object") {
-      isFlat = false;
+  if (properties && typeof properties === "object") {
+    for (const key of Object.keys(properties)) {
+      const nested = properties[key];
+      if (nested && typeof nested === "object") {
+        refineRequiredKeysInSchema(
+          nested as Parameters<typeof refineRequiredKeysInSchema>[0],
+          [...pathPrefix, "properties", key],
+          ctx,
+        );
+      }
     }
-  });
+  }
 
-  return isFlat;
+  if (items && typeof items === "object" && !Array.isArray(items)) {
+    refineRequiredKeysInSchema(
+      items as Parameters<typeof refineRequiredKeysInSchema>[0],
+      [...pathPrefix, "items"],
+      ctx,
+    );
+  }
 }
 
-function isArrayOfStrings(value) {
-  return Array.isArray(value) && value.every((v) => typeof v === "string");
+function typeOfValue(value: unknown): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+/**
+ * Validates a variable value against an array schema. Recursively validates each item
+ * when the schema defines `items` (nested arrays/objects use the same refinement).
+ */
+function refineVariableValueArray(
+  projectConfig: ProjectConfig,
+  variableSchema: { items?: unknown; type: string },
+  variableValue: unknown[],
+  path: (string | number)[],
+  ctx: z.RefinementCtx,
+  variableKey?: string,
+): void {
+  const label = getVariableLabel(variableSchema, variableKey, path);
+  const itemSchema = variableSchema.items;
+
+  if (itemSchema) {
+    variableValue.forEach((item, index) => {
+      superRefineVariableValue(projectConfig, itemSchema, item, [...path, index], ctx, variableKey);
+    });
+  } else {
+    if (!isArrayOfStrings(variableValue)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" (type array): when \`items\` is not set, array must contain only strings; found non-string element.`,
+        path,
+      });
+    }
+  }
+
+  if (projectConfig.maxVariableArrayStringifiedLength) {
+    const stringified = JSON.stringify(variableValue);
+    if (stringified.length > projectConfig.maxVariableArrayStringifiedLength) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" array is too long (${stringified.length} characters), max length is ${projectConfig.maxVariableArrayStringifiedLength}`,
+        path,
+      });
+    }
+  }
+}
+
+/**
+ * Validates a variable value against an object schema. Recursively validates each property
+ * when the schema defines `properties` (nested objects/arrays use the same refinement).
+ */
+function refineVariableValueObject(
+  projectConfig: ProjectConfig,
+  variableSchema: {
+    properties?: Record<string, unknown>;
+    required?: string[];
+    type: string;
+  },
+  variableValue: Record<string, unknown>,
+  path: (string | number)[],
+  ctx: z.RefinementCtx,
+  variableKey?: string,
+): void {
+  const label = getVariableLabel(variableSchema, variableKey, path);
+  const schemaProperties = variableSchema.properties;
+
+  if (schemaProperties && typeof schemaProperties === "object") {
+    const requiredKeys =
+      variableSchema.required && variableSchema.required.length > 0
+        ? variableSchema.required.filter((k) =>
+            Object.prototype.hasOwnProperty.call(schemaProperties, k),
+          )
+        : Object.keys(schemaProperties);
+
+    for (const key of requiredKeys) {
+      if (!Object.prototype.hasOwnProperty.call(variableValue, key)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Missing required property "${key}" in variable "${label}"`,
+          path: [...path, key],
+        });
+      }
+    }
+
+    for (const key of Object.keys(variableValue)) {
+      const propSchema = schemaProperties[key];
+      if (!propSchema) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Unknown property "${key}" in variable "${label}" (not in schema)`,
+          path: [...path, key],
+        });
+      } else {
+        superRefineVariableValue(
+          projectConfig,
+          propSchema,
+          variableValue[key],
+          [...path, key],
+          ctx,
+          key,
+        );
+      }
+    }
+  } else {
+    for (const key of Object.keys(variableValue)) {
+      const propValue = variableValue[key];
+      if (!isFlatObjectValue(propValue)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Variable "${label}" is a flat object (no \`properties\` in schema); property "${key}" must be a primitive (string, number, boolean, or null), got: ${typeof propValue}`,
+          path: [...path, key],
+        });
+      }
+    }
+  }
+
+  if (projectConfig.maxVariableObjectStringifiedLength) {
+    const stringified = JSON.stringify(variableValue);
+    if (stringified.length > projectConfig.maxVariableObjectStringifiedLength) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" object is too long (${stringified.length} characters), max length is ${projectConfig.maxVariableObjectStringifiedLength}`,
+        path,
+      });
+    }
+  }
 }
 
 function superRefineVariableValue(
@@ -26,17 +224,16 @@ function superRefineVariableValue(
   variableValue,
   path,
   ctx,
+  variableKey?: string,
 ) {
-  if (!variableSchema) {
-    let message = `Unknown variable with value: ${variableValue}`;
+  const label = getVariableLabel(variableSchema, variableKey, path);
 
-    if (path.length > 0) {
-      const lastPath = path[path.length - 1];
-
-      if (typeof lastPath === "string") {
-        message = `Unknown variable "${lastPath}" with value: ${variableValue}`;
-      }
-    }
+  if (!variableSchema) {
+    const variableName =
+      path.length > 0 && typeof path[path.length - 1] === "string"
+        ? String(path[path.length - 1])
+        : "variable";
+    const message = `Variable "${variableName}" is used but not defined in variablesSchema. Define it under variablesSchema first, then use it here.`;
 
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
@@ -47,14 +244,28 @@ function superRefineVariableValue(
     return;
   }
 
-  // string
-  if (variableSchema.type === "string") {
+  // Require a value (no undefined) for every variable usage
+  if (variableValue === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Variable "${label}" value is required (got undefined).`,
+      path,
+    });
+    return;
+  }
+
+  const expectedType = variableSchema.type;
+  const gotType = typeOfValue(variableValue);
+
+  // string — only string allowed
+  if (expectedType === "string") {
     if (typeof variableValue !== "string") {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Invalid value for variable "${variableSchema.key}" (${variableSchema.type}): ${variableValue}`,
+        message: `Variable "${label}" (type string) must be a string; got ${gotType}.`,
         path,
       });
+      return;
     }
 
     if (
@@ -63,7 +274,7 @@ function superRefineVariableValue(
     ) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Variable "${variableSchema.key}" value is too long (${variableValue.length} characters), max length is ${projectConfig.maxVariableStringLength}`,
+        message: `Variable "${label}" value is too long (${variableValue.length} characters), max length is ${projectConfig.maxVariableStringLength}`,
         path,
       });
     }
@@ -71,94 +282,123 @@ function superRefineVariableValue(
     return;
   }
 
-  // integer, double
-  if (["integer", "double"].indexOf(variableSchema.type) > -1) {
+  // integer — only integer number allowed (no NaN, no Infinity, no float)
+  if (expectedType === "integer") {
     if (typeof variableValue !== "number") {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Invalid value for variable "${variableSchema.key}" (${variableSchema.type}): ${variableValue}`,
+        message: `Variable "${label}" (type integer) must be a number; got ${gotType}.`,
+        path,
+      });
+      return;
+    }
+    if (!Number.isFinite(variableValue)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" (type integer) must be a finite number; got ${variableValue}.`,
+        path,
+      });
+      return;
+    }
+    if (!Number.isInteger(variableValue)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" (type integer) must be an integer; got ${variableValue}.`,
         path,
       });
     }
-
     return;
   }
 
-  // boolean
-  if (variableSchema.type === "boolean") {
-    if (typeof variableValue !== "boolean") {
+  // double — only finite number allowed
+  if (expectedType === "double") {
+    if (typeof variableValue !== "number") {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Invalid value for variable "${variableSchema.key}" (${variableSchema.type}): ${variableValue}`,
+        message: `Variable "${label}" (type double) must be a number; got ${gotType}.`,
+        path,
+      });
+      return;
+    }
+    if (!Number.isFinite(variableValue)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" (type double) must be a finite number; got ${variableValue}.`,
         path,
       });
     }
-
     return;
   }
 
-  // array
-  if (variableSchema.type === "array") {
-    if (!Array.isArray(variableValue) || !isArrayOfStrings(variableValue)) {
+  // boolean — only boolean allowed
+  if (expectedType === "boolean") {
+    if (typeof variableValue !== "boolean") {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Invalid value for variable "${variableSchema.key}" (${variableSchema.type}): \n\n${variableValue}\n\n`,
+        message: `Variable "${label}" (type boolean) must be a boolean; got ${gotType}.`,
         path,
       });
     }
-
-    if (projectConfig.maxVariableArrayStringifiedLength) {
-      const stringified = JSON.stringify(variableValue);
-
-      if (stringified.length > projectConfig.maxVariableArrayStringifiedLength) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `Variable "${variableSchema.key}" array is too long (${stringified.length} characters), max length is ${projectConfig.maxVariableArrayStringifiedLength}`,
-          path,
-        });
-      }
-    }
-
     return;
   }
 
-  // object
-  if (variableSchema.type === "object") {
-    if (typeof variableValue !== "object" || !isFlatObject(variableValue)) {
+  // array — only array allowed; without items schema = array of strings
+  if (expectedType === "array") {
+    if (!Array.isArray(variableValue)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Invalid value for variable "${variableSchema.key}" (${variableSchema.type}): \n\n${variableValue}\n\n`,
+        message: `Variable "${label}" (type array) must be an array; got ${gotType}.`,
         path,
       });
+      return;
     }
+    refineVariableValueArray(projectConfig, variableSchema, variableValue, path, ctx, variableKey);
+    return;
+  }
 
-    if (projectConfig.maxVariableObjectStringifiedLength) {
-      const stringified = JSON.stringify(variableValue);
-
-      if (stringified.length > projectConfig.maxVariableObjectStringifiedLength) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `Variable "${variableSchema.key}" object is too long (${stringified.length} characters), max length is ${projectConfig.maxVariableObjectStringifiedLength}`,
-          path,
-        });
-      }
+  // object — only plain object allowed (no null, no array)
+  if (expectedType === "object") {
+    if (
+      typeof variableValue !== "object" ||
+      variableValue === null ||
+      Array.isArray(variableValue)
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" (type object) must be a plain object; got ${gotType}.`,
+        path,
+      });
+      return;
     }
-
+    refineVariableValueObject(
+      projectConfig,
+      variableSchema,
+      variableValue as Record<string, unknown>,
+      path,
+      ctx,
+      variableKey,
+    );
     return;
   }
 
-  // json
-  if (variableSchema.type === "json") {
+  // json — only string containing valid JSON allowed
+  if (expectedType === "json") {
+    if (typeof variableValue !== "string") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Variable "${label}" (type json) must be a string (JSON string); got ${gotType}.`,
+        path,
+      });
+      return;
+    }
     try {
-      JSON.parse(variableValue as string);
+      JSON.parse(variableValue);
 
       if (projectConfig.maxVariableJSONStringifiedLength) {
-        const stringified = variableValue;
-
-        if (stringified.length > projectConfig.maxVariableJSONStringifiedLength) {
+        if (variableValue.length > projectConfig.maxVariableJSONStringifiedLength) {
           ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: `Variable "${variableSchema.key}" JSON is too long (${stringified.length} characters), max length is ${projectConfig.maxVariableJSONStringifiedLength}`,
+            message: `Variable "${label}" JSON is too long (${variableValue.length} characters), max length is ${projectConfig.maxVariableJSONStringifiedLength}`,
             path,
           });
         }
@@ -167,13 +407,20 @@ function superRefineVariableValue(
     } catch (e) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `Invalid value for variable "${variableSchema.key}" (${variableSchema.type}): \n\n${variableValue}\n\n`,
+        message: `Variable "${label}" (type json) must be a valid JSON string; parse failed.`,
         path,
       });
     }
 
     return;
   }
+
+  // Unknown variable type — schema is invalid or unsupported
+  ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    message: `Variable "${label}" has unknown or unsupported type "${String(expectedType)}" in variablesSchema.`,
+    path,
+  });
 }
 
 function refineForce({
@@ -206,6 +453,7 @@ function refineForce({
           f.variables[variableKey],
           pathPrefix.concat([fN, "variables", variableKey]),
           ctx,
+          variableKey,
         );
       });
     }
@@ -231,6 +479,7 @@ function refineRules({
           rule.variables[variableKey],
           pathPrefix.concat([ruleN, "variables", variableKey]),
           ctx,
+          variableKey,
         );
       });
     }
@@ -308,21 +557,10 @@ export function getFeatureZodSchema(
   availableSegmentKeys: [string, ...string[]],
   availableFeatureKeys: [string, ...string[]],
 ) {
+  const propertyZodSchema = getPropertyZodSchema();
+  const variableValueZodSchema = valueZodSchema;
+
   const variationValueZodSchema = z.string().min(1);
-  const variableValueZodSchema = z.union([
-    z.string(),
-    z.number(),
-    z.boolean(),
-    z.array(z.string()),
-    z.record(z.unknown()).refine(
-      (value) => {
-        return isFlatObject(value);
-      },
-      {
-        message: "object is not flat",
-      },
-    ),
-  ]);
 
   const plainGroupSegment = z.string().refine(
     (value) => value === "*" || availableSegmentKeys.includes(value),
@@ -500,13 +738,31 @@ export function getFeatureZodSchema(
           z
             .object({
               deprecated: z.boolean().optional(),
-              type: z.enum(["string", "integer", "boolean", "double", "array", "object", "json"]),
+
+              type: z.union([z.literal("json"), propertyTypeEnum]),
+              // array: when omitted, treated as array of strings
+              items: propertyZodSchema.optional(),
+              // object: when omitted, treated as flat object (primitive values only)
+              properties: z.record(propertyZodSchema).optional(),
+              // object: optional list of required property names
+              required: z.array(z.string()).optional(),
+
               description: z.string().optional(),
+
               defaultValue: variableValueZodSchema,
-              useDefaultWhenDisabled: z.boolean().optional(),
               disabledValue: variableValueZodSchema.optional(),
+
+              useDefaultWhenDisabled: z.boolean().optional(),
             })
-            .strict(),
+            .strict()
+            .superRefine((variableSchema, ctx) => {
+              // Validate required ⊆ properties at this level and in all nested object schemas
+              refineRequiredKeysInSchema(
+                variableSchema as Parameters<typeof refineRequiredKeysInSchema>[0],
+                [],
+                ctx,
+              );
+            }),
         )
         .optional(),
 
@@ -625,16 +881,20 @@ export function getFeatureZodSchema(
           variableSchema.defaultValue,
           ["variablesSchema", variableKey, "defaultValue"],
           ctx,
+          variableKey,
         );
 
-        // disabledValue
-        superRefineVariableValue(
-          projectConfig,
-          variableSchema,
-          variableSchema.defaultValue,
-          ["variablesSchema", variableKey, "disabledValue"],
-          ctx,
-        );
+        // disabledValue (only when present)
+        if (variableSchema.disabledValue !== undefined) {
+          superRefineVariableValue(
+            projectConfig,
+            variableSchema,
+            variableSchema.disabledValue,
+            ["variablesSchema", variableKey, "disabledValue"],
+            ctx,
+            variableKey,
+          );
+        }
       });
 
       // variations
@@ -654,6 +914,7 @@ export function getFeatureZodSchema(
               variableValue,
               ["variations", variationN, "variables", variableKey],
               ctx,
+              variableKey,
             );
 
             // variations[n].variableOverrides[n].value
@@ -676,6 +937,7 @@ export function getFeatureZodSchema(
                         "value",
                       ],
                       ctx,
+                      variableKey,
                     );
                   });
                 }

package/src/linter/propertySchema.ts

@@ -0,0 +1,47 @@
+import type { PropertySchema, Value } from "@featurevisor/types";
+import { z } from "zod";
+
+// Recursive schema for Value: boolean | string | number | ObjectValue | Value[]
+export const valueZodSchema: z.ZodType<Value> = z.lazy(() =>
+  z.union([
+    z.boolean(),
+    z.string(),
+    z.number(),
+    // | Date // @TODO: support in future
+    z.record(z.string(), valueZodSchema),
+    z.array(valueZodSchema),
+  ]),
+);
+
+// @TODO: support "date" in future
+// @TODO: consider "semver" in future
+// @TODO: consider "url" in future
+export const propertyTypeEnum = z.enum([
+  "boolean",
+  "string",
+  "integer",
+  "double",
+  "object",
+  "array",
+]);
+
+export function getPropertyZodSchema() {
+  const propertyZodSchema: z.ZodType<PropertySchema> = z.lazy(() =>
+    z
+      .object({
+        description: z.string().optional(),
+        type: propertyTypeEnum.optional(),
+        // enum?: Value[]; const?: Value;
+        // Numeric: maximum?, minimum?
+        // String: maxLength?, minLength?, pattern?
+        items: propertyZodSchema.optional(),
+        // maxItems?, minItems?, uniqueItems?
+        required: z.array(z.string()).optional(),
+        properties: z.record(z.string(), propertyZodSchema).optional(),
+        // Annotations: default?: Value; examples?: Value[];
+      })
+      .strict(),
+  );
+
+  return propertyZodSchema;
+}