@messagevisor/core 0.0.1 → 0.1.0

package/src/examples/coerceExampleIsoDates.spec.ts

@@ -0,0 +1,81 @@
+import { coerceExampleValuesIsoDates } from "./coerceExampleIsoDates";
+
+describe("coerceExampleValuesIsoDates", function () {
+  it("converts ISO 8601 date and datetime strings to Date", function () {
+    const out = coerceExampleValuesIsoDates({
+      d: "2026-11-26",
+      when: "2026-11-26T15:05:00.000Z",
+      deadline: "2026-12-24T23:59:00.000Z",
+      event: "2026-06-01T14:00:00.000Z",
+    });
+
+    expect(out?.d).toBeInstanceOf(Date);
+    expect((out?.d as Date).toISOString().slice(0, 10)).toEqual("2026-11-26");
+    expect(out?.when).toBeInstanceOf(Date);
+    expect((out?.when as Date).toISOString()).toEqual("2026-11-26T15:05:00.000Z");
+    expect(out?.deadline).toBeInstanceOf(Date);
+    expect(out?.event).toBeInstanceOf(Date);
+  });
+
+  it("accepts flexible ISO-like forms without fractional seconds and with space / lowercase", function () {
+    const out = coerceExampleValuesIsoDates({
+      noMsZ: "2026-07-04T12:30:00Z",
+      noMsLowerZ: "2026-07-04T12:30:00z",
+      hourMinuteZ: "2026-07-04T12:30Z",
+      spaceSep: "2026-07-04 12:30:45",
+      offsetNoMs: "2026-07-04T12:30:00+02:00",
+      offsetShort: "2026-07-04T12:30:00+02",
+      trimmed: "  2026-07-04T00:00:00Z  ",
+    });
+
+    expect(out?.noMsZ).toBeInstanceOf(Date);
+    expect((out?.noMsZ as Date).toISOString()).toEqual("2026-07-04T12:30:00.000Z");
+    expect(out?.noMsLowerZ).toBeInstanceOf(Date);
+    expect((out?.noMsLowerZ as Date).toISOString()).toEqual("2026-07-04T12:30:00.000Z");
+    expect(out?.hourMinuteZ).toBeInstanceOf(Date);
+    expect(out?.spaceSep).toBeInstanceOf(Date);
+    expect(out?.offsetNoMs).toBeInstanceOf(Date);
+    expect(out?.offsetShort).toBeInstanceOf(Date);
+    expect(out?.trimmed).toBeInstanceOf(Date);
+    expect((out?.trimmed as Date).toISOString()).toEqual("2026-07-04T00:00:00.000Z");
+  });
+
+  it("accepts comma as fractional-second separator", function () {
+    const out = coerceExampleValuesIsoDates({
+      t: "2026-01-02T03:04:05,678Z",
+    });
+
+    expect(out?.t).toBeInstanceOf(Date);
+    expect((out?.t as Date).toISOString()).toEqual("2026-01-02T03:04:05.678Z");
+  });
+
+  it("does not convert non-ISO strings or numbers", function () {
+    const out = coerceExampleValuesIsoDates({
+      name: "Ada",
+      amount: 10,
+      loose: "12/25/2026",
+      yearOnly: "2026",
+    });
+
+    expect(out?.name).toEqual("Ada");
+    expect(out?.amount).toEqual(10);
+    expect(out?.loose).toEqual("12/25/2026");
+    expect(out?.yearOnly).toEqual("2026");
+  });
+
+  it("walks nested objects and arrays", function () {
+    const out = coerceExampleValuesIsoDates({
+      range: { start: "2026-01-01T00:00:00.000Z", end: "2026-01-02T00:00:00.000Z" },
+      slots: ["2026-06-01T10:00:00Z", "plain"],
+    });
+
+    expect((out?.range as Record<string, unknown>).start).toBeInstanceOf(Date);
+    expect((out?.range as Record<string, unknown>).end).toBeInstanceOf(Date);
+    expect((out?.slots as unknown[])[0]).toBeInstanceOf(Date);
+    expect((out?.slots as unknown[])[1]).toEqual("plain");
+  });
+
+  it("returns undefined for undefined input", function () {
+    expect(coerceExampleValuesIsoDates(undefined)).toBeUndefined();
+  });
+});

package/src/examples/coerceExampleIsoDates.ts

@@ -0,0 +1,98 @@
+/**
+ * Coerce ISO 8601-like strings in example `values` to `Date` for CLI evaluation (ICU date/time formatters).
+ *
+ * Accepted shapes (non-exhaustive; `Date.parse` must still succeed):
+ * - Calendar: `YYYY-MM-DD`
+ * - Datetime: `T` or space between date and time; `t` / `z` case-insensitive where applicable
+ * - Time: `HH:MM` or `HH:MM:SS`, optional fractional seconds (`.` or `,`), optional `Z` or numeric offset (`±HH`, `±HH:MM`, `±HHMM`)
+ */
+
+const ISO_8601_LIKE =
+  /^\d{4}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}(?::\d{2})?(?:[.,]\d{1,9})?(?:[Zz]|[+-]\d{2}(?::?\d{2})?)?)?$/;
+
+function isIso8601TimestampString(value: string): boolean {
+  const trimmed = value.trim();
+  if (!ISO_8601_LIKE.test(trimmed)) {
+    return false;
+  }
+
+  return !Number.isNaN(Date.parse(coerceParseableIsoLike(trimmed)));
+}
+
+/**
+ * Normalize a few ISO variants so `Date.parse` behaves consistently (comma decimals, lowercase z).
+ */
+function normalizeIsoLikeForParse(value: string): string {
+  let s = value.trim();
+  if (s.includes(",") && /\d{2}:\d{2}(?::\d{2})?,/.test(s)) {
+    s = s.replace(",", ".");
+  }
+  return s;
+}
+
+/**
+ * If `Date.parse` rejects a valid-looking ISO string, apply small normalizations (hour-only offset).
+ */
+function coerceParseableIsoLike(trimmed: string): string {
+  const commaNormalized = normalizeIsoLikeForParse(trimmed);
+  if (!Number.isNaN(Date.parse(commaNormalized))) {
+    return commaNormalized;
+  }
+
+  const s = commaNormalized;
+  if (/[+-]\d{2}:\d{2}$/.test(s) || /[+-]\d{4}$/.test(s)) {
+    return s;
+  }
+
+  const hourOnlyOffset = s.match(/^(.+)([+-]\d{2})$/);
+  if (hourOnlyOffset) {
+    const withMinutes = `${hourOnlyOffset[1]}${hourOnlyOffset[2]}:00`;
+    if (!Number.isNaN(Date.parse(withMinutes))) {
+      return withMinutes;
+    }
+  }
+
+  return s;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)
+  );
+}
+
+function coerceLeaf(value: unknown): unknown {
+  if (typeof value === "string" && isIso8601TimestampString(value)) {
+    const trimmed = value.trim();
+    return new Date(Date.parse(coerceParseableIsoLike(trimmed)));
+  }
+
+  if (isPlainObject(value)) {
+    return coerceExampleValuesIsoDates(value);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => coerceLeaf(entry));
+  }
+
+  return value;
+}
+
+/**
+ * Returns a shallow copy with coerced values (nested plain objects and arrays are walked).
+ */
+export function coerceExampleValuesIsoDates(
+  values: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (typeof values === "undefined") {
+    return undefined;
+  }
+
+  const result: Record<string, unknown> = {};
+
+  for (const key of Object.keys(values)) {
+    result[key] = coerceLeaf(values[key]);
+  }
+
+  return result;
+}

package/src/examples/index.spec.ts

@@ -0,0 +1,453 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { getProjectConfig } from "../config";
+import { Datasource } from "../datasource";
+import { examplesPlugin, resolveExamples } from "./index";
+
+async function writeFile(root: string, relativePath: string, content: string) {
+  const filePath = path.join(root, relativePath);
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.promises.writeFile(filePath, content);
+}
+
+async function createProject(configContent = "module.exports = {};\n") {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-examples-"));
+
+  await writeFile(root, "messagevisor.config.js", configContent);
+  await writeFile(
+    root,
+    "locales/en.yml",
+    [
+      "description: English",
+      "formats:",
+      "  number:",
+      "    decimal:",
+      "      minimumFractionDigits: 2",
+      "      maximumFractionDigits: 2",
+      "examples:",
+      "  - description: Greeting raw",
+      "    rawMessage: Hello {name}",
+      "    values:",
+      "      name: Ada",
+      "    formats:",
+      "      number:",
+      "        adHoc:",
+      "          maximumFractionDigits: 1",
+      "  - matrix:",
+      "      name: [John, Jane]",
+      "      age: [30, 25]",
+      "    description: Matrix ${{ name }}",
+      "    rawMessage: Hello {name}! You are {age} years old.",
+      "    values:",
+      "      name: ${{ name }}",
+      "      age: ${{ age }}",
+      "  - description: Referenced message",
+      "    message: auth.signin",
+      "    context:",
+      "      age: 21",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(
+    root,
+    "locales/en-US.yml",
+    [
+      "description: English US",
+      "inheritFormatsFrom: en",
+      "inheritTranslationsFrom: en",
+      "mergeExamplesFrom: en",
+      "examples:",
+      "  - description: Local US example",
+      "    rawMessage: Welcome {name}",
+      "    values:",
+      "      name: Sam",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(
+    root,
+    "messages/auth/signin.yml",
+    [
+      "description: Sign in",
+      "examples:",
+      "  - description: Default signin",
+      "    locale: en",
+      "  - matrix:",
+      "      locale: [en, en-US]",
+      "      age: [17, 21]",
+      "    description: Signin for ${{ locale }} age ${{ age }}",
+      "    locale: ${{ locale }}",
+      "    context:",
+      "      age: ${{ age }}",
+      "translations:",
+      "  en: Sign in",
+      "overrides:",
+      "  - key: adult",
+      "    segments: adult",
+      "    translations:",
+      "      en: Adult sign in",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(
+    root,
+    "segments/adult.yml",
+    [
+      "description: Adult",
+      "conditions:",
+      "  - attribute: age",
+      "    operator: greaterThanOrEquals",
+      "    value: 18",
+      "",
+    ].join("\n"),
+  );
+
+  return root;
+}
+
+async function createSetsProject() {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-examples-sets-"));
+  await writeFile(root, "messagevisor.config.js", "module.exports = { sets: true };\n");
+
+  for (const set of ["dev", "production"]) {
+    await writeFile(
+      root,
+      `sets/${set}/locales/en.yml`,
+      [
+        "description: English",
+        "examples:",
+        `  - description: ${set} raw`,
+        `    rawMessage: Hello from ${set}`,
+        "",
+      ].join("\n"),
+    );
+  }
+
+  return root;
+}
+
+function getDatasource(root: string) {
+  const projectConfig = getProjectConfig(root);
+  const datasource = new Datasource(projectConfig, root);
+
+  return { projectConfig, datasource };
+}
+
+describe("examplesPlugin", function () {
+  it("lists rich examples in JSON and evaluates raw and message examples", async function () {
+    const interpolationModulePath = path.join(
+      path.resolve(__dirname, "../../../.."),
+      "packages/module-interpolation/src/index.ts",
+    );
+    const root = await createProject(
+      [
+        `const { createInterpolationModule } = require(${JSON.stringify(interpolationModulePath)});`,
+        "module.exports = {",
+        "  modules: [createInterpolationModule()],",
+        "};",
+        "",
+      ].join("\n"),
+    );
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { json: true, pretty: true },
+    } as any);
+
+    const result = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(Array.isArray(result.locales)).toEqual(true);
+    expect(Array.isArray(result.messages)).toEqual(true);
+    expect(
+      result.locales.some(
+        (entry: any) =>
+          entry.rawMessage === "Hello {name}" && entry.evaluatedTranslation === "Hello Ada",
+      ),
+    ).toEqual(true);
+    expect(
+      result.locales.some(
+        (entry: any) =>
+          entry.message === "auth.signin" &&
+          entry.evaluatedTranslation === "Adult sign in" &&
+          entry.sourceLocale === "en",
+      ),
+    ).toEqual(true);
+    expect(
+      result.locales.filter(
+        (entry: any) => entry.description && entry.description.startsWith("Matrix "),
+      ),
+    ).toHaveLength(8);
+    expect(
+      result.locales.some(
+        (entry: any) =>
+          entry.locale === "en-US" &&
+          entry.sourceLocale === "en" &&
+          entry.description === "Matrix John",
+      ),
+    ).toEqual(true);
+    expect(
+      result.messages.some(
+        (entry: any) =>
+          entry.message === "auth.signin" &&
+          entry.locale === "en" &&
+          entry.description === "Default signin" &&
+          entry.evaluatedTranslation === "Sign in",
+      ),
+    ).toEqual(true);
+    expect(
+      result.messages.some(
+        (entry: any) =>
+          entry.message === "auth.signin" &&
+          entry.locale === "en-US" &&
+          entry.description === "Signin for en-US age 21" &&
+          entry.evaluatedTranslation === "Adult sign in",
+      ),
+    ).toEqual(true);
+    logSpy.mockRestore();
+  });
+
+  it("merges inherited examples before local examples for a locale", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { locale: "en-US", json: true },
+    } as any);
+
+    const result = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(result.locales[0].sourceLocale).toEqual("en");
+    expect(result.locales[result.locales.length - 1].sourceLocale).toEqual("en-US");
+    logSpy.mockRestore();
+  });
+
+  it("can include evaluation input for external runtime conformance", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { json: true, includeEvaluationInput: true },
+    } as any);
+
+    const result = JSON.parse(String(logSpy.mock.calls[0][0]));
+    const rawExample = result.locales.find((entry: any) => entry.description === "Greeting raw");
+    const localeMessageExample = result.locales.find(
+      (entry: any) => entry.description === "Referenced message",
+    );
+    const messageExample = result.messages.find(
+      (entry: any) => entry.description === "Default signin",
+    );
+
+    expect(rawExample.evaluationInput.defaultFormats.en.number.decimal).toEqual({
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    });
+    expect(rawExample.evaluationInput.formats.number.adHoc).toEqual({
+      maximumFractionDigits: 1,
+    });
+    expect(localeMessageExample.evaluationInput.datafile.messages["auth.signin"]).toBeDefined();
+    expect(Object.keys(localeMessageExample.evaluationInput.datafile.messages)).toEqual([
+      "auth.signin",
+    ]);
+    expect(messageExample.evaluationInput.datafile.messages["auth.signin"]).toBeDefined();
+
+    logSpy.mockRestore();
+  });
+
+  it("lists all sets by default and supports set filtering", async function () {
+    const root = await createSetsProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { json: true },
+    } as any);
+
+    const allResults = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(allResults.locales.map((entry: any) => entry.set).sort()).toEqual(["dev", "production"]);
+    expect(allResults.messages).toEqual([]);
+
+    logSpy.mockClear();
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { set: "dev", json: true },
+    } as any);
+
+    const devResults = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(devResults.locales).toHaveLength(1);
+    expect(devResults.locales[0].set).toEqual("dev");
+    logSpy.mockRestore();
+  });
+
+  it("supports example and matrix index filtering", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { exampleIndex: 2, matrixIndex: 2, json: true },
+    } as any);
+
+    const result = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(result.locales).toHaveLength(2);
+    expect(
+      result.locales.every((entry: any) => entry.exampleIndex === 1 && entry.matrixIndex === 1),
+    ).toEqual(true);
+    expect(result.locales.every((entry: any) => entry.description === "Matrix John")).toEqual(true);
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].description).toEqual("Signin for en age 21");
+    logSpy.mockRestore();
+  });
+
+  it("supports description and evaluated translation pattern filtering", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { locale: "en-US", descriptionPattern: "local us", json: true },
+    } as any);
+
+    const descriptionResult = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(descriptionResult.locales).toHaveLength(1);
+    expect(descriptionResult.locales[0].description).toEqual("Local US example");
+    expect(descriptionResult.messages).toEqual([]);
+
+    logSpy.mockClear();
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { locale: "en-US", translationPattern: "adult sign in", json: true },
+    } as any);
+
+    const translationResult = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(translationResult.locales).toHaveLength(1);
+    expect(translationResult.locales[0].evaluatedTranslation).toEqual("Adult sign in");
+    expect(translationResult.messages).toHaveLength(1);
+    expect(translationResult.messages[0].evaluatedTranslation).toEqual("Adult sign in");
+    logSpy.mockRestore();
+  });
+
+  it("supports message example filtering by example and matrix index", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { locale: "en-US", exampleIndex: 2, matrixIndex: 4, json: true },
+    } as any);
+
+    const result = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(result.locales).toHaveLength(1);
+    expect(result.locales.every((entry: any) => entry.description === "Matrix Jane")).toEqual(true);
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].description).toEqual("Signin for en-US age 21");
+    logSpy.mockRestore();
+  });
+
+  it("supports resolving examples for a specific message", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+
+    const result = await resolveExamples(projectConfig, datasource, {
+      onlyMessages: true,
+      message: "auth.signin",
+    });
+
+    expect(result.locales).toEqual([]);
+    expect(result.messages.length).toBeGreaterThan(0);
+    expect(result.messages.every((entry) => entry.message === "auth.signin")).toEqual(true);
+  });
+
+  it("supports onlyMessages and onlyLocales output selection", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { onlyMessages: true, json: true },
+    } as any);
+
+    const onlyMessagesResult = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(onlyMessagesResult.locales).toEqual([]);
+    expect(onlyMessagesResult.messages.length).toBeGreaterThan(0);
+
+    logSpy.mockClear();
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { onlyLocales: true, json: true },
+    } as any);
+
+    const onlyLocalesResult = JSON.parse(String(logSpy.mock.calls[0][0]));
+    expect(onlyLocalesResult.locales.length).toBeGreaterThan(0);
+    expect(onlyLocalesResult.messages).toEqual([]);
+    logSpy.mockRestore();
+  });
+
+  it("fails when onlyMessages and onlyLocales are both requested", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await expect(
+        examplesPlugin.handler({
+          projectConfig,
+          datasource,
+          parsed: { onlyMessages: true, onlyLocales: true },
+        } as any),
+      ).resolves.toEqual(false);
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        "Pass either --onlyLocales or --onlyMessages, not both.",
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("prints grouped plain output", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    await examplesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: {},
+    } as any);
+
+    const output = logSpy.mock.calls.map((call) => String(call[0])).join("\n");
+    expect(output).toContain("Locales");
+    expect(output).toContain("Messages");
+    expect(output).toContain('Locale "en":');
+    expect(output).toContain('Message "auth.signin":');
+    expect(output).toContain("Evaluated translation:");
+    expect(output).toContain("Found ");
+    logSpy.mockRestore();
+  });
+});