@messagevisor/core 0.0.1 → 0.1.0

package/src/linter/index.ts

@@ -0,0 +1,460 @@
+import * as fs from "fs";
+import * as path from "path";
+
+import type { Attribute, Locale, Message } from "@messagevisor/types";
+import type { ZodError, ZodTypeAny } from "zod";
+
+import type { ProjectConfig } from "../config";
+import type { Datasource } from "../datasource";
+import { getAttributeZodSchema } from "./attributeSchema";
+import { checkLocaleCircularDependency } from "./checkLocaleCircularDependency";
+import { getConditionsZodSchema } from "./conditionSchema";
+import { lintMessageIcuFormatStyles } from "./icuStyleLint";
+import { getLocaleZodSchema } from "./localeSchema";
+import { getMessageZodSchema } from "./messageSchema";
+import { getLintIssuesFromZodError } from "./printError";
+import { getTargetZodSchema } from "./targetSchema";
+import { getSegmentZodSchema } from "./segmentSchema";
+import { getTestZodSchema } from "./testSchema";
+import {
+  assertProjectSetJsonSelection,
+  getProjectSetExecutions,
+  getProjectSetRelativeFilePath,
+} from "../sets";
+import { CLI_FORMAT_BOLD, CLI_FORMAT_GREEN, CLI_FORMAT_RED, colorize } from "../tester/cliFormat";
+import { prettyDuration } from "../tester/prettyDuration";
+
+export type LintEntityType =
+  | "locale"
+  | "attribute"
+  | "segment"
+  | "message"
+  | "target"
+  | "test"
+  | "project";
+
+export interface LintProjectOptions {
+  keyPattern?: string;
+  entityType?: string;
+  set?: string;
+  json?: boolean;
+  pretty?: boolean;
+}
+
+export interface LintError {
+  level: "error";
+  filePath: string;
+  entityType: LintEntityType;
+  entityKey: string;
+  message: string;
+  path: (string | number)[];
+  code?: string;
+  value?: unknown;
+}
+
+export interface LintResult {
+  hasError: boolean;
+  errors: LintError[];
+  duration: number;
+}
+
+const ENTITY_NAME_REGEX_ERROR = "Names must be alphanumeric and can contain _, -, /, and .";
+
+function isValidEntityKey(projectConfig: ProjectConfig, key: string) {
+  return /^[a-zA-Z0-9_\-/]+$/.test(key.split(projectConfig.namespaceCharacter).join(""));
+}
+
+function getParserExtension(projectConfig: ProjectConfig) {
+  return (projectConfig.parser as any).extension || "yml";
+}
+
+function getFullPathFromKey(projectConfig: ProjectConfig, entityType: LintEntityType, key: string) {
+  const fileName = `${key.split(projectConfig.namespaceCharacter).join(path.sep)}.${getParserExtension(projectConfig)}`;
+
+  if (entityType === "locale") {
+    return path.join(projectConfig.localesDirectoryPath, fileName);
+  }
+
+  if (entityType === "attribute") {
+    return path.join(projectConfig.attributesDirectoryPath, fileName);
+  }
+
+  if (entityType === "segment") {
+    return path.join(projectConfig.segmentsDirectoryPath, fileName);
+  }
+
+  if (entityType === "message") {
+    return path.join(projectConfig.messagesDirectoryPath, fileName);
+  }
+
+  if (entityType === "target") {
+    return path.join(projectConfig.targetsDirectoryPath, fileName);
+  }
+
+  if (entityType === "test") {
+    const specFileName = `${key
+      .split(projectConfig.namespaceCharacter)
+      .join(path.sep)}.spec.${getParserExtension(projectConfig)}`;
+    const specFilePath = path.join(projectConfig.testsDirectoryPath, specFileName);
+
+    return fs.existsSync(specFilePath)
+      ? specFilePath
+      : path.join(projectConfig.testsDirectoryPath, fileName);
+  }
+
+  return path.join(process.cwd(), "messagevisor.config.js");
+}
+
+async function readAll<T>(
+  keys: string[],
+  read: (key: string) => Promise<T>,
+): Promise<Record<string, T>> {
+  const entries: [string, T][] = [];
+
+  for (const key of keys) {
+    try {
+      entries.push([key, await read(key)]);
+    } catch {
+      // Parse/read errors are reported during entity validation.
+    }
+  }
+
+  return Object.fromEntries(entries);
+}
+
+export async function lintProject(
+  projectConfig: ProjectConfig,
+  datasource: Datasource,
+  options: LintProjectOptions = {},
+): Promise<LintResult> {
+  const startTime = Date.now();
+  const errors: LintError[] = [];
+  const keyPattern = options.keyPattern ? new RegExp(options.keyPattern) : null;
+
+  function shouldLintKey(key: string) {
+    return !keyPattern || keyPattern.test(key);
+  }
+
+  function recordError(error: Omit<LintError, "level">) {
+    errors.push({ level: "error", ...error });
+  }
+
+  function reportZodError(
+    entityType: LintEntityType,
+    key: string,
+    fullPath: string,
+    error: ZodError,
+  ) {
+    for (const issue of getLintIssuesFromZodError(error)) {
+      recordError({
+        filePath: path.relative(process.cwd(), fullPath),
+        entityType,
+        entityKey: key,
+        message: issue.message,
+        path: issue.path,
+        code: issue.code,
+        value: issue.value,
+      });
+    }
+  }
+
+  async function lintEntity(
+    entityType: Exclude<LintEntityType, "project">,
+    key: string,
+    schema: ZodTypeAny,
+    read: (key: string) => Promise<unknown>,
+  ) {
+    const fullPath = getFullPathFromKey(projectConfig, entityType, key);
+
+    if (!isValidEntityKey(projectConfig, key)) {
+      recordError({
+        filePath: path.relative(process.cwd(), fullPath),
+        entityType,
+        entityKey: key,
+        message: `Invalid name: "${key}". ${ENTITY_NAME_REGEX_ERROR}`,
+        path: [],
+        code: "invalid_name",
+      });
+    }
+
+    try {
+      const parsed = await read(key);
+      const result = schema.safeParse(parsed);
+
+      if (!result.success) {
+        reportZodError(entityType, key, fullPath, result.error);
+      }
+    } catch (error) {
+      recordError({
+        filePath: path.relative(process.cwd(), fullPath),
+        entityType,
+        entityKey: key,
+        message: error instanceof Error ? error.message : String(error),
+        path: [],
+        code: error instanceof Error ? error.name : "error",
+      });
+    }
+  }
+
+  const [localeKeys, attributeKeys, segmentKeys, messageKeys, targetKeys, testKeys] =
+    await Promise.all([
+      datasource.listLocales(),
+      datasource.listAttributes(),
+      datasource.listSegments(),
+      datasource.listMessages(),
+      datasource.listTargets(),
+      datasource.listTests(),
+    ]);
+
+  if (localeKeys.length === 0) {
+    recordError({
+      filePath: "messagevisor.config.js",
+      entityType: "project",
+      entityKey: "messagevisor.config.js",
+      message: "At least one locale is required",
+      path: ["locales"],
+      code: "missing_locale",
+    });
+  }
+
+  const localesByKey = await readAll<Locale>(localeKeys, (key) => datasource.readLocale(key));
+  const attributesByKey = await readAll<Attribute>(attributeKeys, (key) =>
+    datasource.readAttribute(key),
+  );
+  const messagesByKey = await readAll<Message>(messageKeys, (key) => datasource.readMessage(key));
+
+  const localeZodSchema = getLocaleZodSchema(localeKeys, messageKeys);
+  const attributeZodSchema = getAttributeZodSchema();
+  const conditionsZodSchema = getConditionsZodSchema(attributesByKey);
+  const segmentZodSchema = getSegmentZodSchema(conditionsZodSchema);
+  const messageZodSchema = getMessageZodSchema(localeKeys, segmentKeys, attributesByKey, {
+    namespaceCharacter: projectConfig.namespaceCharacter,
+    exportOverrideKeySeparator: projectConfig.exportOverrideKeySeparator,
+  });
+  const targetZodSchema = getTargetZodSchema(localeKeys);
+  const testZodSchema = getTestZodSchema(messageKeys, segmentKeys, localeKeys, targetKeys);
+
+  if (!options.entityType || options.entityType === "locale") {
+    for (const key of localeKeys.filter(shouldLintKey)) {
+      await lintEntity("locale", key, localeZodSchema, (entityKey) =>
+        datasource.readLocale(entityKey),
+      );
+    }
+  }
+
+  for (const field of [
+    "inheritFormatsFrom",
+    "inheritTranslationsFrom",
+    "mergeExamplesFrom",
+  ] as const) {
+    for (const circularDependency of checkLocaleCircularDependency(localesByKey, field)) {
+      const key = circularDependency.cycle[0];
+      const fullPath = getFullPathFromKey(projectConfig, "locale", key);
+
+      recordError({
+        filePath: path.relative(process.cwd(), fullPath),
+        entityType: "locale",
+        entityKey: key,
+        message: `Circular locale dependency detected for ${field}: ${circularDependency.cycle.join(" -> ")}`,
+        path: [field],
+        code: "circular_locale_dependency",
+      });
+    }
+  }
+
+  if (!options.entityType || options.entityType === "attribute") {
+    for (const key of attributeKeys.filter(shouldLintKey)) {
+      await lintEntity("attribute", key, attributeZodSchema, (entityKey) =>
+        datasource.readAttribute(entityKey),
+      );
+    }
+  }
+
+  if (!options.entityType || options.entityType === "segment") {
+    for (const key of segmentKeys.filter(shouldLintKey)) {
+      await lintEntity("segment", key, segmentZodSchema, (entityKey) =>
+        datasource.readSegment(entityKey),
+      );
+    }
+  }
+
+  if (!options.entityType || options.entityType === "message") {
+    for (const key of messageKeys.filter(shouldLintKey)) {
+      await lintEntity("message", key, messageZodSchema, (entityKey) =>
+        datasource.readMessage(entityKey),
+      );
+    }
+
+    errors.push(
+      ...lintMessageIcuFormatStyles(
+        Object.fromEntries(Object.entries(messagesByKey).filter(([key]) => shouldLintKey(key))),
+        localesByKey,
+        (key) => path.relative(process.cwd(), getFullPathFromKey(projectConfig, "message", key)),
+        { icuSkeleton: projectConfig.icuSkeleton },
+      ),
+    );
+  }
+
+  if (!options.entityType || options.entityType === "target") {
+    for (const key of targetKeys.filter(shouldLintKey)) {
+      await lintEntity("target", key, targetZodSchema, (entityKey) =>
+        datasource.readTarget(entityKey),
+      );
+    }
+  }
+
+  if (!options.entityType || options.entityType === "test") {
+    for (const key of testKeys.filter(shouldLintKey)) {
+      await lintEntity("test", key, testZodSchema, (entityKey) => datasource.readTest(entityKey));
+    }
+  }
+
+  return {
+    hasError: errors.length > 0,
+    errors,
+    duration: Date.now() - startTime,
+  };
+}
+
+function formatPath(errorPath: (string | number)[]) {
+  return errorPath.reduce<string>((pathSegments, entry) => {
+    if (typeof entry === "number") {
+      return `${pathSegments}[${entry}]`;
+    }
+
+    return pathSegments ? `${pathSegments}.${entry}` : entry;
+  }, "");
+}
+
+function getLintOptionsLabel(parsed: any) {
+  const labels = [];
+
+  if (parsed.set) {
+    labels.push(`set: ${parsed.set}`);
+  }
+
+  if (parsed.entityType) {
+    labels.push(`entity: ${parsed.entityType}`);
+  }
+
+  if (parsed.keyPattern) {
+    labels.push(`keyPattern: ${parsed.keyPattern}`);
+  }
+
+  return labels.length > 0 ? labels.join(", ") : "all definitions";
+}
+
+async function lintProjectSets(
+  projectConfig: ProjectConfig,
+  datasource: Datasource,
+  options: LintProjectOptions = {},
+): Promise<LintResult> {
+  const startTime = Date.now();
+  const errors: LintError[] = [];
+  const setExecutions = await getProjectSetExecutions(projectConfig, datasource, options.set);
+
+  for (const execution of setExecutions) {
+    const result = await lintProject(execution.projectConfig, execution.datasource, options);
+
+    errors.push(
+      ...result.errors.map((error) => ({
+        ...error,
+        filePath: projectConfig.sets
+          ? getProjectSetRelativeFilePath(projectConfig, execution.set, error.filePath)
+          : error.filePath,
+        entityKey: projectConfig.sets ? `${execution.set}/${error.entityKey}` : error.entityKey,
+      })),
+    );
+  }
+
+  return {
+    hasError: errors.length > 0,
+    errors,
+    duration: Date.now() - startTime,
+  };
+}
+
+function groupLintErrors(errors: LintError[]) {
+  const groups: Array<{ label: string; filePath: string; errors: LintError[] }> = [];
+  const groupIndexes = new Map<string, number>();
+
+  for (const error of errors) {
+    const label = `${error.entityType} "${error.entityKey}"`;
+    const groupKey = `${label}:${error.filePath}`;
+    let groupIndex = groupIndexes.get(groupKey);
+
+    if (typeof groupIndex === "undefined") {
+      groupIndex = groups.length;
+      groupIndexes.set(groupKey, groupIndex);
+      groups.push({ label, filePath: error.filePath, errors: [] });
+    }
+
+    groups[groupIndex].errors.push(error);
+  }
+
+  return groups;
+}
+
+function printLintResult(result: LintResult, parsed: any) {
+  console.log("");
+  console.log(CLI_FORMAT_BOLD, "Linting Messagevisor definitions");
+  console.log(`  ${colorize("Target", 36)}: ${getLintOptionsLabel(parsed)}`);
+  console.log("");
+
+  if (!result.hasError) {
+    console.log(CLI_FORMAT_GREEN, "✔ No lint errors found");
+    console.log(CLI_FORMAT_BOLD, `Time:  ${prettyDuration(result.duration)}`);
+    return;
+  }
+
+  console.log(CLI_FORMAT_RED, `✘ ${result.errors.length} lint error(s) found`);
+  console.log("");
+
+  for (const group of groupLintErrors(result.errors)) {
+    console.log(CLI_FORMAT_BOLD, group.label);
+    console.log(`  ${colorize(group.filePath, 36)}`);
+
+    for (const error of group.errors) {
+      const errorPath = formatPath(error.path);
+      const code = error.code ? colorize(error.code, 33) : colorize("lint_error", 33);
+      const pathSuffix = errorPath ? ` ${colorize(errorPath, 2)}` : "";
+
+      console.error(`  ${colorize("✘", 31)} [${code}]${pathSuffix}`);
+      console.error(`    ${error.message}`);
+    }
+
+    console.log("");
+  }
+
+  console.log(CLI_FORMAT_RED, `Errors: ${result.errors.length} failed`);
+  console.log(CLI_FORMAT_BOLD, `Time:   ${prettyDuration(result.duration)}`);
+}
+
+export const lintPlugin = {
+  command: "lint",
+  handler: async ({ projectConfig, datasource, parsed }: any) => {
+    assertProjectSetJsonSelection(projectConfig, parsed.set, parsed.json);
+
+    const result = await lintProjectSets(projectConfig, datasource, {
+      set: parsed.set,
+      entityType: parsed.entityType,
+      keyPattern: parsed.keyPattern,
+      json: parsed.json,
+      pretty: parsed.pretty,
+    });
+
+    if (parsed.json) {
+      console.log(
+        parsed.pretty ? JSON.stringify(result.errors, null, 2) : JSON.stringify(result.errors),
+      );
+    } else {
+      printLintResult(result, parsed);
+    }
+
+    return !result.hasError;
+  },
+  examples: [
+    { command: "lint", description: "lint Messagevisor project definitions" },
+    { command: "lint --json --pretty", description: "print lint results as JSON" },
+  ],
+};

package/src/linter/localeSchema.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+
+import { formatPresetsZodSchema } from "./formatSchema";
+import { refineWithMessage } from "./zodHelpers";
+
+export function getLocaleZodSchema(localeKeys: string[], messageKeys: string[]) {
+  const matrixZodSchema = z.record(
+    z.string(),
+    z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])),
+  );
+
+  const localeExampleSchema = z
+    .object({
+      matrix: matrixZodSchema.optional(),
+      index: z.number().int().min(0).optional(),
+      description: z.string().optional(),
+      values: z.record(z.string(), z.unknown()).optional(),
+      context: z.record(z.string(), z.unknown()).optional(),
+      formats: formatPresetsZodSchema.optional(),
+      timeZone: z.string().optional(),
+      currency: z.string().optional(),
+      rawMessage: z.string().optional(),
+      message: refineWithMessage(
+        z.string(),
+        (value) => messageKeys.includes(value),
+        (value) => `Unknown message "${value}"`,
+      ).optional(),
+    })
+    .strict()
+    .superRefine((data, ctx) => {
+      const hasRawMessage = typeof data.rawMessage !== "undefined";
+      const hasMessage = typeof data.message !== "undefined";
+
+      if (hasRawMessage === hasMessage) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Example must define exactly one of `rawMessage` or `message`.",
+          path: ["rawMessage"],
+        });
+      }
+    });
+
+  return z
+    .object({
+      key: z.string().optional(),
+      promotable: z.boolean().optional(),
+      description: z.string({
+        error: (issue) => (issue.input === undefined ? "Required" : undefined),
+      }),
+      direction: z.enum(["ltr", "rtl"]).optional(),
+      inheritFormatsFrom: refineWithMessage(
+        z.string(),
+        (value) => localeKeys.includes(value),
+        (value) => `Unknown locale "${value}"`,
+      ).optional(),
+      inheritTranslationsFrom: refineWithMessage(
+        z.string(),
+        (value) => localeKeys.includes(value),
+        (value) => `Unknown locale "${value}"`,
+      ).optional(),
+      mergeExamplesFrom: refineWithMessage(
+        z.string(),
+        (value) => localeKeys.includes(value),
+        (value) => `Unknown locale "${value}"`,
+      ).optional(),
+      formats: formatPresetsZodSchema.optional(),
+      examples: z.array(localeExampleSchema).optional(),
+    })
+    .strict();
+}

package/src/linter/messageSchema.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+
+import { getConditionsZodSchema } from "./conditionSchema";
+import { valueZodSchema } from "./schema";
+import { refineWithMessage } from "./zodHelpers";
+
+export function getGroupSegmentZodSchema(segmentKeys: string[]) {
+  type GroupSegmentInput = any;
+
+  const groupSegmentZodSchema: z.ZodType<GroupSegmentInput> = z.lazy(() =>
+    z.union([
+      refineWithMessage(
+        z.string(),
+        (value) => segmentKeys.includes(value),
+        (value) => `Unknown segment "${value}"`,
+      ),
+      z.object({ and: z.array(groupSegmentZodSchema).min(1) }).strict(),
+      z.object({ or: z.array(groupSegmentZodSchema).min(1) }).strict(),
+      z.object({ not: z.array(groupSegmentZodSchema).min(1) }).strict(),
+    ]),
+  );
+
+  return z.union([z.literal("*"), groupSegmentZodSchema, z.array(groupSegmentZodSchema).min(1)]);
+}
+
+export function getMessageZodSchema(
+  localeKeys: string[],
+  segmentKeys: string[],
+  attributesByKey: any,
+  options: {
+    namespaceCharacter: string;
+    exportOverrideKeySeparator: string;
+  },
+) {
+  const matrixZodSchema = z.record(
+    z.string(),
+    z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])),
+  );
+
+  const messageExampleLocaleSchema = refineWithMessage(
+    z.string(),
+    (value) => localeKeys.includes(value) || /^\$\{\{.+\}\}$/.test(value),
+    (value) => `Unknown locale "${value}"`,
+  );
+
+  const messageExampleZodSchema = z
+    .object({
+      matrix: matrixZodSchema.optional(),
+      index: z.number().int().min(0).optional(),
+      description: z.string().optional(),
+      locale: messageExampleLocaleSchema,
+      values: z.record(z.string(), z.unknown()).optional(),
+      context: z.record(z.string(), z.unknown()).optional(),
+      formats: z.record(z.string(), z.unknown()).optional(),
+      timeZone: z.string().optional(),
+      currency: z.string().optional(),
+    })
+    .strict();
+
+  const localeTranslations = z
+    .record(
+      refineWithMessage(
+        z.string(),
+        (value) => localeKeys.includes(value),
+        (value) => `Unknown locale "${value}"`,
+      ),
+      z.string(),
+    )
+    .refine((value) => Object.keys(value).length > 0, {
+      message: "At least one translation is required",
+    });
+
+  const conditionsZodSchema = getConditionsZodSchema(attributesByKey);
+  const groupSegmentZodSchema = getGroupSegmentZodSchema(segmentKeys);
+
+  const overrideZodSchema = z
+    .object({
+      key: z.string().min(1),
+      description: z.string().optional(),
+      summary: z.string().optional(),
+      conditions: conditionsZodSchema.optional(),
+      segments: groupSegmentZodSchema.optional(),
+      translations: localeTranslations,
+    })
+    .strict()
+    .superRefine((data, ctx) => {
+      if (!data.conditions && !data.segments) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Override must define either `conditions` or `segments`.",
+          path: ["conditions"],
+        });
+      }
+    });
+
+  return z
+    .object({
+      key: z.string().optional(),
+      archived: z.boolean().optional(),
+      promotable: z.boolean().optional(),
+      deprecated: z.boolean().optional(),
+      deprecationWarning: z.string().optional(),
+      description: z.string({
+        error: (issue) => (issue.input === undefined ? "Required" : undefined),
+      }),
+      summary: z.string().optional(),
+      meta: z.record(z.string(), valueZodSchema).optional(),
+      examples: z.array(messageExampleZodSchema).optional(),
+      translations: localeTranslations,
+      overrides: z.array(overrideZodSchema).optional(),
+    })
+    .strict()
+    .superRefine((data, ctx) => {
+      const overrideKeys = new Set<string>();
+
+      for (let index = 0; index < (data.overrides || []).length; index++) {
+        const override = (data.overrides || [])[index];
+        const disallowedCharacters = [
+          ["namespaceCharacter", options.namespaceCharacter],
+          ["exportOverrideKeySeparator", options.exportOverrideKeySeparator],
+        ];
+
+        for (const [label, character] of disallowedCharacters) {
+          if (override.key.includes(character)) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message: `Override key "${override.key}" must not include ${label} "${character}".`,
+              path: ["overrides", index, "key"],
+            });
+          }
+        }
+
+        if (overrideKeys.has(override.key)) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Duplicate override key "${override.key}". Override keys must be unique within a message.`,
+            path: ["overrides", index, "key"],
+          });
+        }
+
+        overrideKeys.add(override.key);
+      }
+
+      if (data.deprecationWarning && !data.deprecated) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "`deprecationWarning` can only be set when `deprecated` is true.",
+          path: ["deprecationWarning"],
+        });
+      }
+    });
+}