@messagevisor/core 0.0.1 → 0.1.0

package/src/linter/testSchema.spec.ts

@@ -0,0 +1,405 @@
+import { getTestZodSchema } from "./testSchema";
+
+describe("getTestZodSchema", function () {
+  const schema = getTestZodSchema(
+    ["auth.signin", "common.welcome"],
+    ["adult", "betaUsers"],
+    ["en", "nl"],
+    ["web", "mobile"],
+  );
+
+  it("accepts matrix on all supported test assertion kinds", function () {
+    expect(() =>
+      schema.parse({
+        message: "auth.signin",
+        assertions: [
+          {
+            matrix: {
+              name: ["Ada", "Sam"],
+              enabled: [true],
+            },
+            locale: "en",
+            target: "web",
+            description: "Greeting ${{ name }}",
+            withFlags: {
+              "new-homepage": "${{ enabled }}",
+            },
+            values: {
+              name: "${{ name }}",
+            },
+            expectedTranslation: "Hello ${{ name }}",
+            expectedByRuntime: {
+              go: "Hello ${{ name }}",
+            },
+          },
+        ],
+      }),
+    ).not.toThrow();
+
+    expect(() =>
+      schema.parse({
+        segment: "adult",
+        assertions: [
+          {
+            matrix: {
+              expected: [true],
+            },
+            segment: "adult",
+            context: {
+              age: 21,
+            },
+            expectedToMatch: "${{ expected }}",
+          },
+        ],
+      }),
+    ).not.toThrow();
+
+    expect(() =>
+      schema.parse({
+        locale: "en",
+        assertions: [
+          {
+            matrix: {
+              target: ["web"],
+              amount: [12],
+            },
+            description: "Locale ${{ target }}",
+            target: "${{ target }}",
+            expectedFormats: {
+              number: {
+                money: {
+                  currency: "USD",
+                },
+              },
+            },
+            rawMessage: "{amount, number, money}",
+            values: {
+              amount: "${{ amount }}",
+            },
+            expectedTranslation: "$12.00",
+            expectedByRuntime: {
+              go: "USD12.00",
+            },
+          },
+        ],
+      }),
+    ).not.toThrow();
+
+    expect(() =>
+      schema.parse({
+        target: "web",
+        assertions: [
+          {
+            matrix: {
+              currency: ["USD"],
+            },
+            locale: "en",
+            expectedFormats: {
+              number: {
+                money: {
+                  currency: "${{ currency }}",
+                },
+              },
+            },
+          },
+          {
+            locale: "en",
+            rawMessage: "Total: {amount, number, money}",
+            values: {
+              amount: 12,
+            },
+            expectedTranslation: "Total: $12.00",
+            expectedByRuntime: {
+              go: "Total: USD12.00",
+            },
+          },
+          {
+            locale: "en",
+            message: "common.welcome",
+            expectedTranslation: "Hello Ada",
+          },
+        ],
+      }),
+    ).not.toThrow();
+  });
+
+  it("rejects invalid matrix values", function () {
+    const result = schema.safeParse({
+      message: "auth.signin",
+      assertions: [
+        {
+          matrix: {
+            user: {
+              name: "Ada",
+            },
+          },
+          locale: "en",
+          target: "web",
+          expectedTranslation: "Sign in",
+        },
+      ],
+    });
+
+    expect(result.success).toEqual(false);
+    const nestedIssues =
+      result.error.issues[0]?.code === "invalid_union"
+        ? result.error.issues[0].errors.flat()
+        : result.error.issues;
+    expect(
+      nestedIssues.some(
+        (issue) =>
+          issue.path.join(".") === "assertions.0.matrix.user" &&
+          issue.message.toLowerCase().includes("array"),
+      ),
+    ).toEqual(true);
+  });
+
+  it("requires runtime-specific expected values to be strings", function () {
+    const result = schema.safeParse({
+      message: "auth.signin",
+      assertions: [
+        {
+          locale: "en",
+          target: "web",
+          expectedTranslation: "Sign in",
+          expectedByRuntime: {
+            go: 12,
+          },
+        },
+      ],
+    });
+
+    expect(result.success).toEqual(false);
+    const nestedIssues =
+      result.error.issues[0]?.code === "invalid_union"
+        ? result.error.issues[0].errors.flat()
+        : result.error.issues;
+    expect(
+      nestedIssues.some(
+        (issue) =>
+          issue.path.join(".") === "assertions.0.expectedByRuntime.go" &&
+          issue.message.toLowerCase().includes("string"),
+      ),
+    ).toEqual(true);
+  });
+
+  it("keeps key-like fields strict and literal", function () {
+    const result = schema.safeParse({
+      message: "auth.signin",
+      assertions: [
+        {
+          matrix: {
+            locale: ["en"],
+          },
+          locale: "${{ locale }}",
+          target: "web",
+          expectedTranslation: "Sign in",
+        },
+      ],
+    });
+
+    expect(result.success).toEqual(false);
+    expect(
+      result.error.issues.some(
+        (issue) =>
+          issue.path.join(".").includes("locale") &&
+          issue.message.includes('Unknown locale "${{ locale }}"'),
+      ),
+    ).toEqual(true);
+  });
+
+  it("accepts locale assertions with only raw-message translation or with both purposes", function () {
+    expect(() =>
+      schema.parse({
+        locale: "en",
+        assertions: [
+          {
+            rawMessage: "Hello {name}",
+            values: {
+              name: "Ada",
+            },
+            expectedTranslation: "Hello Ada",
+          },
+          {
+            target: "web",
+            expectedFormats: {
+              number: {
+                money: {
+                  currency: "USD",
+                },
+              },
+            },
+            rawMessage: "{amount, number, money}",
+            values: {
+              amount: 12,
+            },
+            expectedTranslation: "$12.00",
+          },
+        ],
+      }),
+    ).not.toThrow();
+  });
+
+  it("accepts target assertions with structure checks, raw translation, or message translation", function () {
+    expect(() =>
+      schema.parse({
+        target: "web",
+        assertions: [
+          {
+            locale: "en",
+            expectedToIncludeMessages: ["common.welcome"],
+          },
+          {
+            locale: "en",
+            rawMessage: "Hello {name}",
+            values: {
+              name: "Ada",
+            },
+            expectedTranslation: "Hello Ada",
+          },
+          {
+            locale: "en",
+            message: "common.welcome",
+            expectedTranslation: "Hello Ada",
+          },
+          {
+            locale: "en",
+            expectedFormats: {
+              number: {
+                money: {
+                  currency: "USD",
+                },
+              },
+            },
+            message: "common.welcome",
+            expectedTranslation: "Hello Ada",
+          },
+        ],
+      }),
+    ).not.toThrow();
+  });
+
+  it("rejects incomplete or empty locale assertions", function () {
+    const missingExpectedTranslation = schema.safeParse({
+      locale: "en",
+      assertions: [
+        {
+          rawMessage: "Hello {name}",
+        },
+      ],
+    });
+
+    expect(missingExpectedTranslation.success).toEqual(false);
+    expect(
+      missingExpectedTranslation.error.issues.some((issue) =>
+        issue.message.includes("`rawMessage` and `expectedTranslation` together"),
+      ),
+    ).toEqual(true);
+
+    const missingRawMessage = schema.safeParse({
+      locale: "en",
+      assertions: [
+        {
+          expectedTranslation: "Hello Ada",
+        },
+      ],
+    });
+
+    expect(missingRawMessage.success).toEqual(false);
+    expect(
+      missingRawMessage.error.issues.some((issue) =>
+        issue.message.includes("`rawMessage` and `expectedTranslation` together"),
+      ),
+    ).toEqual(true);
+
+    const emptyAssertion = schema.safeParse({
+      locale: "en",
+      assertions: [
+        {
+          description: "No-op",
+        },
+      ],
+    });
+
+    expect(emptyAssertion.success).toEqual(false);
+    expect(
+      emptyAssertion.error.issues.some((issue) =>
+        issue.message.includes("at least one of `expectedFormats` or `rawMessage`"),
+      ),
+    ).toEqual(true);
+  });
+
+  it("rejects invalid target translation assertion combinations", function () {
+    const bothSources = schema.safeParse({
+      target: "web",
+      assertions: [
+        {
+          locale: "en",
+          rawMessage: "Hello {name}",
+          message: "common.welcome",
+          expectedTranslation: "Hello Ada",
+        },
+      ],
+    });
+
+    expect(bothSources.success).toEqual(false);
+    expect(
+      bothSources.error.issues.some((issue) =>
+        issue.message.includes("either `rawMessage` or `message`, not both"),
+      ),
+    ).toEqual(true);
+
+    const missingExpectedTranslation = schema.safeParse({
+      target: "web",
+      assertions: [
+        {
+          locale: "en",
+          rawMessage: "Hello {name}",
+        },
+      ],
+    });
+
+    expect(missingExpectedTranslation.success).toEqual(false);
+    expect(
+      missingExpectedTranslation.error.issues.some((issue) =>
+        issue.message.includes("must also define `expectedTranslation`"),
+      ),
+    ).toEqual(true);
+
+    const orphanedExpectedTranslation = schema.safeParse({
+      target: "web",
+      assertions: [
+        {
+          locale: "en",
+          expectedTranslation: "Hello Ada",
+        },
+      ],
+    });
+
+    expect(orphanedExpectedTranslation.success).toEqual(false);
+    expect(
+      orphanedExpectedTranslation.error.issues.some((issue) =>
+        issue.message.includes("must also define `rawMessage` or `message`"),
+      ),
+    ).toEqual(true);
+
+    const emptyAssertion = schema.safeParse({
+      target: "web",
+      assertions: [
+        {
+          locale: "en",
+          description: "No-op",
+        },
+      ],
+    });
+
+    expect(emptyAssertion.success).toEqual(false);
+    expect(
+      emptyAssertion.error.issues.some((issue) =>
+        issue.message.includes(
+          "must define inclusion/exclusion checks, `expectedFormats`, or translation",
+        ),
+      ),
+    ).toEqual(true);
+  });
+});

package/src/linter/testSchema.ts

@@ -0,0 +1,239 @@
+import { z } from "zod";
+
+import { refineWithMessage } from "./zodHelpers";
+
+export function getTestZodSchema(
+  messageKeys: string[],
+  segmentKeys: string[],
+  localeKeys: string[],
+  targetKeys: string[],
+) {
+  const matrixZodSchema = z.record(
+    z.string(),
+    z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])),
+  );
+  const formatPresets = z.record(z.string(), z.unknown());
+  const expectedByRuntime = z.record(z.string(), z.string());
+  const targetOrMatrixValue = refineWithMessage(
+    z.string(),
+    (value) => targetKeys.includes(value) || /^\$\{\{.+\}\}$/.test(value),
+    (value) => `Unknown target "${value}"`,
+  );
+
+  const messageAssertion = z
+    .object({
+      matrix: matrixZodSchema.optional(),
+      description: z.string().optional(),
+      context: z.record(z.string(), z.unknown()).optional(),
+      locale: refineWithMessage(
+        z.string(),
+        (value) => localeKeys.includes(value),
+        (value) => `Unknown locale "${value}"`,
+      ),
+      target: targetOrMatrixValue.optional(),
+      values: z.record(z.string(), z.unknown()).optional(),
+      withFlags: z.record(z.string(), z.union([z.boolean(), z.string()])).optional(),
+      withVariations: z.record(z.string(), z.string()).optional(),
+      currency: z.string().optional(),
+      timeZone: z.string().optional(),
+      formats: formatPresets.optional(),
+      expectedTranslation: z.string(),
+      expectedByRuntime: expectedByRuntime.optional(),
+    })
+    .strict();
+
+  const segmentAssertion = z
+    .object({
+      matrix: matrixZodSchema.optional(),
+      description: z.string().optional(),
+      segment: refineWithMessage(
+        z.string(),
+        (value) => segmentKeys.includes(value),
+        (value) => `Unknown segment "${value}"`,
+      ),
+      context: z.record(z.string(), z.unknown()).optional(),
+      expectedToMatch: z.union([z.boolean(), z.string()]),
+    })
+    .strict();
+
+  const localeAssertion = z
+    .object({
+      matrix: matrixZodSchema.optional(),
+      description: z.string().optional(),
+      target: targetOrMatrixValue.optional(),
+      expectedFormats: formatPresets.optional(),
+      rawMessage: z.string().optional(),
+      expectedTranslation: z.string().optional(),
+      expectedByRuntime: expectedByRuntime.optional(),
+      values: z.record(z.string(), z.unknown()).optional(),
+      context: z.record(z.string(), z.unknown()).optional(),
+      formats: formatPresets.optional(),
+      currency: z.string().optional(),
+      timeZone: z.string().optional(),
+    })
+    .strict()
+    .superRefine((data, ctx) => {
+      const hasExpectedFormats = typeof data.expectedFormats !== "undefined";
+      const hasRawMessage = typeof data.rawMessage !== "undefined";
+      const hasExpectedTranslation = typeof data.expectedTranslation !== "undefined";
+
+      if (hasRawMessage !== hasExpectedTranslation) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Locale assertions must define `rawMessage` and `expectedTranslation` together.",
+          path: hasRawMessage ? ["expectedTranslation"] : ["rawMessage"],
+        });
+      }
+
+      if (!hasExpectedFormats && !hasRawMessage && !hasExpectedTranslation) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "Locale assertions must define at least one of `expectedFormats` or `rawMessage` with `expectedTranslation`.",
+          path: ["expectedFormats"],
+        });
+      }
+    });
+
+  const targetAssertion = z
+    .object({
+      matrix: matrixZodSchema.optional(),
+      description: z.string().optional(),
+      locale: refineWithMessage(
+        z.string(),
+        (value) => localeKeys.includes(value),
+        (value) => `Unknown locale "${value}"`,
+      ),
+      expectedToIncludeMessages: z
+        .array(
+          refineWithMessage(
+            z.string(),
+            (value) => messageKeys.includes(value),
+            (value) => `Unknown message "${value}"`,
+          ),
+        )
+        .optional(),
+      expectedToNotIncludeMessages: z
+        .array(
+          refineWithMessage(
+            z.string(),
+            (value) => messageKeys.includes(value),
+            (value) => `Unknown message "${value}"`,
+          ),
+        )
+        .optional(),
+      expectedFormats: formatPresets.optional(),
+      rawMessage: z.string().optional(),
+      message: refineWithMessage(
+        z.string(),
+        (value) => messageKeys.includes(value),
+        (value) => `Unknown message "${value}"`,
+      ).optional(),
+      expectedTranslation: z.string().optional(),
+      expectedByRuntime: expectedByRuntime.optional(),
+      values: z.record(z.string(), z.unknown()).optional(),
+      context: z.record(z.string(), z.unknown()).optional(),
+      formats: formatPresets.optional(),
+      currency: z.string().optional(),
+      timeZone: z.string().optional(),
+    })
+    .strict()
+    .superRefine((data, ctx) => {
+      const hasRawMessage = typeof data.rawMessage !== "undefined";
+      const hasMessage = typeof data.message !== "undefined";
+      const hasExpectedTranslation = typeof data.expectedTranslation !== "undefined";
+      const hasStructureChecks =
+        typeof data.expectedFormats !== "undefined" ||
+        typeof data.expectedToIncludeMessages !== "undefined" ||
+        typeof data.expectedToNotIncludeMessages !== "undefined";
+
+      if (hasRawMessage && hasMessage) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Target assertions must define either `rawMessage` or `message`, not both.",
+          path: ["rawMessage"],
+        });
+      }
+
+      if ((hasRawMessage || hasMessage) && !hasExpectedTranslation) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "Target assertions that define `rawMessage` or `message` must also define `expectedTranslation`.",
+          path: ["expectedTranslation"],
+        });
+      }
+
+      if (hasExpectedTranslation && !hasRawMessage && !hasMessage) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "Target assertions that define `expectedTranslation` must also define `rawMessage` or `message`.",
+          path: ["expectedTranslation"],
+        });
+      }
+
+      if (!hasStructureChecks && !hasRawMessage && !hasMessage && !hasExpectedTranslation) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "Target assertions must define inclusion/exclusion checks, `expectedFormats`, or translation.",
+          path: ["expectedFormats"],
+        });
+      }
+    });
+
+  const messageTest = z
+    .object({
+      key: z.string().optional(),
+      promotable: z.boolean().optional(),
+      message: refineWithMessage(
+        z.string(),
+        (value) => messageKeys.includes(value),
+        (value) => `Unknown message "${value}"`,
+      ),
+      assertions: z.array(messageAssertion).min(1),
+    })
+    .strict();
+
+  const segmentTest = z
+    .object({
+      key: z.string().optional(),
+      promotable: z.boolean().optional(),
+      segment: refineWithMessage(
+        z.string(),
+        (value) => segmentKeys.includes(value),
+        (value) => `Unknown segment "${value}"`,
+      ),
+      assertions: z.array(segmentAssertion).min(1),
+    })
+    .strict();
+
+  const localeTest = z
+    .object({
+      key: z.string().optional(),
+      promotable: z.boolean().optional(),
+      locale: refineWithMessage(
+        z.string(),
+        (value) => localeKeys.includes(value),
+        (value) => `Unknown locale "${value}"`,
+      ),
+      assertions: z.array(localeAssertion).min(1),
+    })
+    .strict();
+
+  const targetTest = z
+    .object({
+      key: z.string().optional(),
+      promotable: z.boolean().optional(),
+      target: refineWithMessage(
+        z.string(),
+        (value) => targetKeys.includes(value),
+        (value) => `Unknown target "${value}"`,
+      ),
+      assertions: z.array(targetAssertion).min(1),
+    })
+    .strict();
+
+  return z.union([messageTest, segmentTest, localeTest, targetTest]);
+}

package/src/linter/zodHelpers.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+export function refineWithMessage<T>(
+  schema: z.ZodType<T>,
+  predicate: (value: T) => boolean,
+  getMessage: (value: T) => string,
+) {
+  return schema.superRefine((value, ctx) => {
+    if (!predicate(value)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: getMessage(value),
+      });
+    }
+  });
+}