@featurevisor/core 2.25.0 → 2.26.0

package/src/linter/featureSchema.ts

@@ -12,6 +12,7 @@ import {
   refineStringLengthPattern,
   refineArrayItems,
 } from "./schema";
+import { refineWithMessage } from "./zodHelpers";
 
 const tagRegex = /^[a-z0-9-]+$/;
 
@@ -1306,7 +1307,7 @@ export function getFeatureZodSchema(
   const schemaZodSchema = getSchemaZodSchema(availableSchemaKeys);
   const variableValueZodSchema = valueZodSchema;
   const variableValueOrNullZodSchema = z.union([valueZodSchema, z.null()]);
-  const overridePathMapValueZodSchema = z.record(variableValueOrNullZodSchema);
+  const overridePathMapValueZodSchema = z.record(z.string(), variableValueOrNullZodSchema);
   const overrideValueZodSchema = z.union([
     variableValueOrNullZodSchema,
     overridePathMapValueZodSchema,
@@ -1314,11 +1315,10 @@ export function getFeatureZodSchema(
 
   const variationValueZodSchema = z.string().min(1);
 
-  const plainGroupSegment = z.string().refine(
+  const plainGroupSegment = refineWithMessage(
+    z.string(),
     (value) => value === "*" || availableSegmentKeys.includes(value),
-    (value) => ({
-      message: `Unknown segment key "${value}"`,
-    }),
+    (value) => `Unknown segment key "${value}"`,
   );
 
   const andOrNotGroupSegment = z.union([
@@ -1358,9 +1358,10 @@ export function getFeatureZodSchema(
 
           enabled: z.boolean().optional(),
           variation: variationValueZodSchema.optional(),
-          variables: z.record(variableValueOrNullZodSchema).optional(),
+          variables: z.record(z.string(), variableValueOrNullZodSchema).optional(),
           variableOverrides: z
             .record(
+              z.string(),
               z.array(
                 z.union([
                   z
@@ -1379,44 +1380,46 @@ export function getFeatureZodSchema(
               ),
             )
             .optional(),
-          variationWeights: z.record(z.number().min(0).max(100)).optional(),
+          variationWeights: z.record(z.string(), z.number().min(0).max(100)).optional(),
         })
         .strict(),
     )
 
     // must have at least one rule
-    .refine(
-      (value) => value.length > 0,
-      () => ({
-        message: "Must have at least one rule",
-      }),
-    )
+    .superRefine((value, ctx) => {
+      if (value.length === 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Must have at least one rule",
+        });
+      }
+    })
 
     // duplicate rules
-    .refine(
-      (value) => {
-        const keys = value.map((v) => v.key);
-        return keys.length === new Set(keys).size;
-      },
-      (value) => ({
-        message: "Duplicate rule keys found: " + value.map((v) => v.key).join(", "),
-      }),
-    )
+    .superRefine((value, ctx) => {
+      const keys = value.map((v) => v.key);
+      if (keys.length !== new Set(keys).size) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Duplicate rule keys found: " + value.map((v) => v.key).join(", "),
+        });
+      }
+    })
 
     // enforce catch-all rule
-    .refine(
-      (value) => {
-        if (!projectConfig.enforceCatchAllRule) {
-          return true;
-        }
+    .superRefine((value, ctx) => {
+      if (!projectConfig.enforceCatchAllRule) {
+        return;
+      }
 
-        const hasCatchAllAsLastRule = value[value.length - 1].segments === "*";
-        return hasCatchAllAsLastRule;
-      },
-      () => ({
-        message: `Missing catch-all rule with \`segments: "*"\` at the end`,
-      }),
-    );
+      const hasCatchAllAsLastRule = value[value.length - 1].segments === "*";
+      if (!hasCatchAllAsLastRule) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Missing catch-all rule with \`segments: "*"\` at the end`,
+        });
+      }
+    });
 
   const forceSchema = z
     .array(
@@ -1426,7 +1429,7 @@ export function getFeatureZodSchema(
             segments: groupSegmentsZodSchema,
             enabled: z.boolean().optional(),
             variation: variationValueZodSchema.optional(),
-            variables: z.record(variableValueOrNullZodSchema).optional(),
+            variables: z.record(z.string(), variableValueOrNullZodSchema).optional(),
           })
           .strict(),
         z
@@ -1434,25 +1437,23 @@ export function getFeatureZodSchema(
             conditions: conditionsZodSchema,
             enabled: z.boolean().optional(),
             variation: variationValueZodSchema.optional(),
-            variables: z.record(variableValueOrNullZodSchema).optional(),
+            variables: z.record(z.string(), variableValueOrNullZodSchema).optional(),
           })
           .strict(),
       ]),
     )
     .optional();
 
-  const attributeKeyZodSchema = z.string().refine(
+  const attributeKeyZodSchema = refineWithMessage(
+    z.string(),
     (value) => value === "*" || availableAttributeKeys.includes(value),
-    (value) => ({
-      message: `Unknown attribute "${value}"`,
-    }),
+    (value) => `Unknown attribute "${value}"`,
   );
 
-  const featureKeyZodSchema = z.string().refine(
+  const featureKeyZodSchema = refineWithMessage(
+    z.string(),
     (value) => availableFeatureKeys.includes(value),
-    (value) => ({
-      message: `Unknown feature "${value}"`,
-    }),
+    (value) => `Unknown feature "${value}"`,
   );
 
   const environmentKeys = projectConfig.environments || [];
@@ -1465,21 +1466,21 @@ export function getFeatureZodSchema(
 
       tags: z
         .array(
-          z.string().refine(
+          refineWithMessage(
+            z.string(),
             (value) => tagRegex.test(value),
-            (value) => ({
-              message: `Tag "${value}" must be lower cased and alphanumeric, and may contain hyphens.`,
-            }),
+            (value) =>
+              `Tag "${value}" must be lower cased and alphanumeric, and may contain hyphens.`,
           ),
         )
-        .refine(
-          (value) => {
-            return value.length === new Set(value).size;
-          },
-          (value) => ({
-            message: "Duplicate tags found: " + value.join(", "),
-          }),
-        ),
+        .superRefine((value, ctx) => {
+          if (value.length !== new Set(value).size) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: "Duplicate tags found: " + value.join(", "),
+            });
+          }
+        }),
 
       required: z
         .array(
@@ -1507,23 +1508,22 @@ export function getFeatureZodSchema(
 
       variablesSchema: z
         .record(
+          z.string(),
           z
             .object({
               deprecated: z.boolean().optional(),
 
               // Reference to a reusable schema (mutually exclusive with type/properties/required/items)
-              schema: z
-                .string()
-                .refine(
-                  (value) => availableSchemaKeys.includes(value),
-                  (value) => ({ message: `Unknown schema "${value}"` }),
-                )
-                .optional(),
+              schema: refineWithMessage(
+                z.string(),
+                (value) => availableSchemaKeys.includes(value),
+                (value) => `Unknown schema "${value}"`,
+              ).optional(),
 
               // Inline schema (mutually exclusive with schema)
               type: z.union([z.literal("json"), propertyTypeEnum]).optional(),
               items: schemaZodSchema.optional(),
-              properties: z.record(schemaZodSchema).optional(),
+              properties: z.record(z.string(), schemaZodSchema).optional(),
               additionalProperties: schemaZodSchema.optional(),
               required: z.array(z.string()).optional(),
               enum: z.array(variableValueZodSchema).optional(),
@@ -1639,9 +1639,10 @@ export function getFeatureZodSchema(
               description: z.string().optional(),
               value: variationValueZodSchema,
               weight: z.number().min(0).max(100),
-              variables: z.record(variableValueOrNullZodSchema).optional(),
+              variables: z.record(z.string(), variableValueOrNullZodSchema).optional(),
               variableOverrides: z
                 .record(
+                  z.string(),
                   z.array(
                     z.union([
                       z
@@ -1663,31 +1664,35 @@ export function getFeatureZodSchema(
             })
             .strict(),
         )
-        .refine(
-          (value) => {
-            const variationValues = value.map((v) => v.value);
-            return variationValues.length === new Set(variationValues).size;
-          },
-          (value) => ({
-            message: "Duplicate variation values found: " + value.map((v) => v.value).join(", "),
-          }),
-        )
+        .superRefine((value, ctx) => {
+          const variationValues = value.map((v) => v.value);
+          if (variationValues.length !== new Set(variationValues).size) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: "Duplicate variation values found: " + value.map((v) => v.value).join(", "),
+            });
+          }
+        })
         .optional(),
 
       expose:
         projectConfig.environments === false
           ? exposeSchema.optional()
-          : z.record(z.enum(environmentKeys as [string, ...string[]]), exposeSchema).optional(),
+          : z
+              .partialRecord(z.enum(environmentKeys as [string, ...string[]]), exposeSchema)
+              .optional(),
 
       force:
         projectConfig.environments === false
           ? forceSchema
-          : z.record(z.enum(environmentKeys as [string, ...string[]]), forceSchema).optional(),
+          : z
+              .partialRecord(z.enum(environmentKeys as [string, ...string[]]), forceSchema)
+              .optional(),
 
       rules:
         projectConfig.environments === false
           ? rulesSchema
-          : z.record(z.enum(environmentKeys as [string, ...string[]]), rulesSchema),
+          : z.partialRecord(z.enum(environmentKeys as [string, ...string[]]), rulesSchema),
     })
     .strict()
     .superRefine((value, ctx) => {

package/src/linter/groupSchema.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import { ProjectConfig } from "../config";
 import { Datasource } from "../datasource";
+import { refineWithMessage } from "./zodHelpers";
 
 export function getGroupZodSchema(
   projectConfig: ProjectConfig,
@@ -15,19 +16,17 @@ export function getGroupZodSchema(
         .array(
           z
             .object({
-              feature: z
-                .string()
-                .optional()
-                .refine(
-                  (value) => {
-                    if (value && availableFeatureKeys.indexOf(value) === -1) {
-                      return false;
-                    }
+              feature: refineWithMessage(
+                z.string().optional(),
+                (value) => {
+                  if (value && availableFeatureKeys.indexOf(value) === -1) {
+                    return false;
+                  }
 
-                    return true;
-                  },
-                  (value) => ({ message: `Unknown feature "${value}"` }),
-                ),
+                  return true;
+                },
+                (value) => `Unknown feature "${value}"`,
+              ),
               percentage: z.number().min(0).max(100),
             })
             .strict(),

package/src/linter/lintProject.spec.ts

@@ -20,13 +20,13 @@ function createTempSplitProject() {
 
   fs.writeFileSync(
     path.join(tempRoot, "featurevisor.config.js"),
-    [
-      "module.exports = {",
-      "  environments: ['staging', 'production'],",
-      "  splitByEnvironment: true,",
-      "  tags: ['all'],",
-      "};",
-    ].join("\n"),
+    `
+module.exports = {
+  environments: ['staging', 'production'],
+  splitByEnvironment: true,
+  tags: ['all'],
+};
+`.trimStart(),
     "utf8",
   );
 
@@ -36,25 +36,46 @@ function createTempSplitProject() {
 
   fs.writeFileSync(
     path.join(tempRoot, "features", "foo.yml"),
-    ["key: foo", "description: Foo", "tags:", "  - all", "bucketBy: userId"].join("\n"),
+    `
+key: foo
+description: Foo
+tags:
+  - all
+bucketBy: userId
+`.trimStart(),
     "utf8",
   );
 
   fs.writeFileSync(
     path.join(tempRoot, "environments", "staging", "foo.yml"),
-    ["rules:", "  - key: everyone", "    segments: '*'", "    percentage: 100"].join("\n"),
+    `
+rules:
+  - key: everyone
+    segments: '*'
+    percentage: 100
+`.trimStart(),
     "utf8",
   );
 
   fs.writeFileSync(
     path.join(tempRoot, "environments", "production", "foo.yml"),
-    ["rules:", "  - key: everyone", "    segments: '*'", "    percentage: 0"].join("\n"),
+    `
+rules:
+  - key: everyone
+    segments: '*'
+    percentage: 0
+`.trimStart(),
     "utf8",
   );
 
   return tempRoot;
 }
 
+function replaceInFile(filePath: string, search: string, replacement: string) {
+  const contents = fs.readFileSync(filePath, "utf8");
+  fs.writeFileSync(filePath, contents.replace(search, replacement), "utf8");
+}
+
 function getDeps(rootDirectoryPath: string) {
   const projectConfig = getProjectConfig(rootDirectoryPath);
   const datasource = new Datasource(projectConfig, rootDirectoryPath);
@@ -91,7 +112,10 @@ describe("core: lintProject", function () {
   it("returns structured errors in JSON mode", async () => {
     fs.writeFileSync(
       path.join(tempProjectPath, "attributes", "invalid name.yml"),
-      "description: this has an invalid key name\ntype: string\n",
+      `
+description: this has an invalid key name
+type: string
+`.trimStart(),
       "utf8",
     );
 
@@ -114,6 +138,83 @@ describe("core: lintProject", function () {
     expect(result.errors[0].filePath).toContain("attributes");
   });
 
+  it("reports real example-1 segment, feature, and test schema mistakes with useful paths", async () => {
+    replaceInFile(
+      path.join(tempProjectPath, "segments", "desktop.yml"),
+      `
+conditions:
+  - attribute: device
+    operator: equals
+    value: desktop
+`.trimStart(),
+      `
+conditions:
+  - attribute: device
+    operator: equals
+    value: desktop
+  - attribute: notARealAttribute
+    operator: equals
+    value: nope
+`.trimStart(),
+    );
+
+    replaceInFile(
+      path.join(tempProjectPath, "features", "withSchema.yml"),
+      `
+  singleLink:
+    schema: link
+    defaultValue:
+      title: Home
+      url: /
+`.trimStart(),
+      `
+  singleLink:
+    schema: link
+    defaultValue:
+      title: Home
+      url: 123
+`.trimStart(),
+    );
+
+    replaceInFile(
+      path.join(tempProjectPath, "tests", "features", "withSchema.spec.yml"),
+      "    environment: staging",
+      "    environment: qa",
+    );
+
+    const result = await lintProject(getDeps(tempProjectPath) as any, { json: true });
+
+    expect(result.hasError).toBe(true);
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          filePath: expect.stringContaining(path.join("segments", "desktop.yml")),
+          entityType: "segment",
+          key: "desktop",
+          message: 'Unknown attribute "notARealAttribute"',
+          path: ["conditions", 1, "attribute"],
+          code: "custom",
+        }),
+        expect.objectContaining({
+          filePath: expect.stringContaining(path.join("features", "withSchema.yml")),
+          entityType: "feature",
+          key: "withSchema",
+          message: 'Variable "url" (type string) must be a string; got number.',
+          path: ["variablesSchema", "singleLink", "defaultValue", "url"],
+          code: "custom",
+        }),
+        expect.objectContaining({
+          filePath: expect.stringContaining(path.join("tests", "features", "withSchema.spec.yml")),
+          entityType: "test",
+          key: "features/withSchema.spec",
+          message: 'Unknown environment "qa"',
+          path: ["assertions", 0, "environment"],
+          code: "custom",
+        }),
+      ]),
+    );
+  });
+
   it("plugin prints pretty JSON only once in --json --pretty mode", async () => {
     const consoleLogSpy = jest.spyOn(console, "log").mockImplementation(() => {});
 
@@ -135,7 +236,9 @@ describe("core: lintProject", function () {
   it("does not call process.exit for zod validation errors while linting tests", async () => {
     fs.writeFileSync(
       path.join(tempProjectPath, "tests", "broken.spec.yml"),
-      "feature: foo\n",
+      `
+feature: foo
+`.trimStart(),
       "utf8",
     );
 
@@ -170,7 +273,12 @@ describe("core: lintProject", function () {
     const splitProjectPath = createTempSplitProject();
     fs.writeFileSync(
       path.join(splitProjectPath, "environments", "staging", "foo.yml"),
-      ["rules:", "  - key: everyone", "    segments: '*'", "    percentage: invalid"].join("\n"),
+      `
+rules:
+  - key: everyone
+    segments: '*'
+    percentage: invalid
+`.trimStart(),
       "utf8",
     );
 

package/src/linter/printError.ts

@@ -1,4 +1,4 @@
-import { ZodError } from "zod";
+import { ZodError, ZodIssue } from "zod";
 
 import { CLI_FORMAT_RED } from "../tester/cliFormat";
 
@@ -9,20 +9,37 @@ export interface LintIssueFromZod {
   value?: unknown;
 }
 
+function normalizePath(path: PropertyKey[]): (string | number)[] {
+  return path.map((segment) => (typeof segment === "symbol" ? String(segment) : segment));
+}
+
+function getInvalidUnionIssue(issue: ZodIssue): ZodIssue | undefined {
+  if (issue.code !== "invalid_union" || issue.path.length > 0) {
+    return undefined;
+  }
+
+  const unionErrors = (issue as any).unionErrors as ZodError[] | undefined;
+  if (Array.isArray(unionErrors) && unionErrors.length > 0) {
+    return unionErrors[unionErrors.length - 1].issues[0];
+  }
+
+  const errors = (issue as any).errors as ZodIssue[][] | undefined;
+  if (Array.isArray(errors) && errors.length > 0) {
+    return errors[errors.length - 1][0];
+  }
+
+  return undefined;
+}
+
 export function getLintIssuesFromZodError(e: ZodError): LintIssueFromZod[] {
   return e.issues
     .map((issue) => {
-      if (
-        issue.code === "invalid_union" &&
-        issue.path.length === 0 &&
-        issue.unionErrors.length > 0
-      ) {
-        const lastUnionError = issue.unionErrors[issue.unionErrors.length - 1];
-        const nestedIssue = lastUnionError.issues[0];
+      const nestedIssue = getInvalidUnionIssue(issue);
 
+      if (nestedIssue) {
         return {
           message: nestedIssue.message,
-          path: nestedIssue.path,
+          path: normalizePath(nestedIssue.path),
           code: nestedIssue.code,
           value: (nestedIssue as any).received,
         };
@@ -30,7 +47,7 @@ export function getLintIssuesFromZodError(e: ZodError): LintIssueFromZod[] {
 
       return {
         message: issue.message,
-        path: issue.path,
+        path: normalizePath(issue.path),
         code: issue.code,
         value: (issue as any).received,
       };

package/src/linter/schema.spec.ts

@@ -18,12 +18,13 @@ import {
 /** Build a refinement context that collects issues for assertion. */
 function createRefinementCtx(): { issues: z.ZodIssue[]; ctx: z.RefinementCtx } {
   const issues: z.ZodIssue[] = [];
-  const ctx: z.RefinementCtx = {
-    path: [],
-    addIssue(issue: z.ZodIssue) {
-      issues.push(issue);
+  const ctx = {
+    addIssue(issue: Parameters<z.RefinementCtx["addIssue"]>[0]) {
+      if (typeof issue !== "string") {
+        issues.push(issue as z.ZodIssue);
+      }
     },
-  };
+  } as z.RefinementCtx;
   return { issues, ctx };
 }
 
@@ -440,7 +441,7 @@ describe("schema.ts :: getSchemaZodSchema", () => {
     const Schema = getSchemaZodSchema(["link", "color"]);
     const result = Schema.safeParse({ schema: "nonexistent" });
     expect(result.success).toBe(false);
-    const err = !result.success ? (result as z.SafeParseError<unknown>).error : null;
+    const err = !result.success ? (result as z.ZodSafeParseError<unknown>).error : null;
     expect(err?.issues.some((i) => i.message === 'Unknown schema "nonexistent"')).toBe(true);
   });
 
@@ -456,7 +457,7 @@ describe("schema.ts :: getSchemaZodSchema", () => {
       oneOf: [{ type: "string" }],
     });
     expect(result.success).toBe(false);
-    const err = !result.success ? (result as z.SafeParseError<unknown>).error : null;
+    const err = !result.success ? (result as z.ZodSafeParseError<unknown>).error : null;
     const msg =
       err?.issues.map((i) => (typeof i.message === "string" ? i.message : "")).join(" ") ?? "";
     expect(msg).toMatch(/array|length|minimum|oneOf|element/i);
@@ -474,7 +475,7 @@ describe("schema.ts :: getSchemaZodSchema", () => {
     const Schema = getSchemaZodSchema([]);
     const result = Schema.safeParse({ type: "array" });
     expect(result.success).toBe(false);
-    const err = !result.success ? (result as z.SafeParseError<unknown>).error : null;
+    const err = !result.success ? (result as z.ZodSafeParseError<unknown>).error : null;
     expect(
       err?.issues.some(
         (i) =>
@@ -501,7 +502,7 @@ describe("schema.ts :: getSchemaZodSchema", () => {
       enum: ["a", 42, "c"],
     });
     expect(result.success).toBe(false);
-    const err = !result.success ? (result as z.SafeParseError<unknown>).error : null;
+    const err = !result.success ? (result as z.ZodSafeParseError<unknown>).error : null;
     expect(
       err?.issues.some(
         (i) => typeof i.message === "string" && i.message.includes("does not match type"),
@@ -622,7 +623,7 @@ describe("schema.ts :: getSchemaZodSchema", () => {
       const Schema = getSchemaZodSchema(schemaKeys);
       const result = Schema.safeParse(invalidSchema);
       expect(result.success).toBe(false);
-      const err = !result.success ? (result as z.SafeParseError<unknown>).error : null;
+      const err = !result.success ? (result as z.ZodSafeParseError<unknown>).error : null;
       expect(err).not.toBeNull();
       const messages = (err?.issues ?? [])
         .map((i) => (typeof i.message === "string" ? i.message : ""))
@@ -679,7 +680,7 @@ describe("schema.ts :: getSchemaZodSchema", () => {
       const Schema = getSchemaZodSchema([]);
       const result = Schema.safeParse({ type: "string", invalidKey: true });
       expect(result.success).toBe(false);
-      const err = !result.success ? (result as z.SafeParseError<unknown>).error : null;
+      const err = !result.success ? (result as z.ZodSafeParseError<unknown>).error : null;
       const messages = (err?.issues ?? [])
         .map((i) => (typeof i.message === "string" ? i.message : ""))
         .join(" ");

package/src/linter/schema.ts

@@ -1,6 +1,8 @@
 import type { Schema, SchemaKey, Value } from "@featurevisor/types";
 import { z } from "zod";
 
+import { refineWithMessage } from "./zodHelpers";
+
 /** Returns true if value matches the schema type. */
 function valueMatchesType(v: unknown, type: string): boolean {
   switch (type) {
@@ -460,15 +462,11 @@ export function getSchemaZodSchema(schemaKeys: SchemaKey[] = []) {
         additionalProperties: schemaZodSchema.optional(),
         // Annotations: default?: Value; examples?: Value[];
 
-        schema: z
-          .string()
-          .refine(
-            (value) => schemaKeys.includes(value),
-            (value) => ({
-              message: `Unknown schema "${value}"`,
-            }),
-          )
-          .optional(),
+        schema: refineWithMessage(
+          z.string(),
+          (value) => schemaKeys.includes(value),
+          (value) => `Unknown schema "${value}"`,
+        ).optional(),
         oneOf: z.array(schemaZodSchema).min(2).optional(),
       })
       .strict()