@messagevisor/core 0.0.1 → 0.1.0

package/src/find-duplicates/index.spec.ts

@@ -0,0 +1,289 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { getProjectConfig } from "../config";
+import { Datasource } from "../datasource";
+import { findDuplicateTranslations, findDuplicatesPlugin } 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() {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-duplicates-"));
+
+  await writeFile(root, "messagevisor.config.js", "module.exports = {};\n");
+  await writeFile(root, "locales/en.yml", "description: English\n");
+  await writeFile(
+    root,
+    "locales/en-US.yml",
+    "description: English US\ninheritTranslationsFrom: en\n",
+  );
+  await writeFile(root, "locales/nl.yml", "description: Dutch\n");
+  await writeFile(
+    root,
+    "messages/actions/save.yml",
+    "description: Save action\ntranslations:\n  en: Save\n  nl: Opslaan\n",
+  );
+  await writeFile(
+    root,
+    "messages/common/save.yml",
+    "description: Common save\ntranslations:\n  en: Save\n  en-US: Save\n  nl: Opslaan\n",
+  );
+  await writeFile(
+    root,
+    "messages/actions/cancel.yml",
+    "description: Cancel action\ntranslations:\n  en: Cancel\n  nl: Annuleren\n",
+  );
+  await writeFile(
+    root,
+    "messages/override-only.yml",
+    [
+      "description: Override should not count",
+      "translations:",
+      "  en: Unique base",
+      "overrides:",
+      "  - key: duplicate",
+      "    segments: '*'",
+      "    translations:",
+      "      en: Save",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(
+    root,
+    "messages/empty/one.yml",
+    "description: Empty one\ntranslations:\n  en: ''\n  nl: '   '\n",
+  );
+  await writeFile(
+    root,
+    "messages/empty/two.yml",
+    "description: Empty two\ntranslations:\n  en: ''\n  nl: '   '\n",
+  );
+  await writeFile(
+    root,
+    "messages/archived/save.yml",
+    "description: Archived save\narchived: true\ntranslations:\n  en: Save\n  nl: Opslaan\n",
+  );
+
+  return root;
+}
+
+async function createSetsProject() {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "messagevisor-duplicates-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\n");
+    await writeFile(
+      root,
+      `sets/${set}/messages/actions/save.yml`,
+      `description: Save ${set}\ntranslations:\n  en: Save ${set}\n`,
+    );
+    await writeFile(
+      root,
+      `sets/${set}/messages/common/save.yml`,
+      `description: Common save ${set}\ntranslations:\n  en: Save ${set}\n`,
+    );
+  }
+
+  return root;
+}
+
+function getDatasource(root: string) {
+  const projectConfig = getProjectConfig(root);
+  const datasource = new Datasource(projectConfig, root);
+
+  return { projectConfig, datasource };
+}
+
+function stripAnsi(value: string) {
+  return value.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+describe("findDuplicateTranslations", function () {
+  it("finds direct and inherited duplicate translations grouped by locale", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+
+    const result = await findDuplicateTranslations(projectConfig, datasource);
+
+    expect(result.summary).toEqual({
+      sets: 1,
+      locales: 3,
+      duplicateValues: 3,
+      duplicateMessageKeys: 6,
+    });
+    expect(result.results[0].set).toEqual(null);
+    expect(result.results[0].locales.map((entry) => entry.locale)).toEqual(["en", "en-US", "nl"]);
+
+    const enUsDuplicate = result.results[0].locales
+      .find((entry) => entry.locale === "en-US")
+      ?.duplicateValues.find((entry) => entry.value === "Save");
+
+    expect(enUsDuplicate).toEqual({
+      value: "Save",
+      messageKeys: ["actions.save", "common.save"],
+      sources: [
+        { messageKey: "actions.save", locale: "en" },
+        { messageKey: "common.save", locale: "en-US" },
+      ],
+    });
+  });
+
+  it("ignores overrides, empty values, whitespace-only values, and archived messages", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+
+    const result = await findDuplicateTranslations(projectConfig, datasource, {
+      locale: "en",
+    });
+
+    const values = result.results[0].locales[0].duplicateValues;
+
+    expect(values).toHaveLength(1);
+    expect(values[0].value).toEqual("Save");
+    expect(values[0].messageKeys).toEqual(["actions.save", "common.save"]);
+    expect(values[0].messageKeys).not.toContain("override-only");
+    expect(values[0].messageKeys).not.toContain("empty.one");
+    expect(values[0].messageKeys).not.toContain("empty.two");
+    expect(values[0].messageKeys).not.toContain("archived.save");
+  });
+
+  it("filters by locale and reports empty results cleanly", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+
+    const result = await findDuplicateTranslations(projectConfig, datasource, {
+      locale: "fr",
+    }).catch((error) => error);
+
+    expect(result.message).toContain('Unknown locale "fr"');
+
+    await writeFile(
+      root,
+      "messages/common/save.yml",
+      "description: Common save\ntranslations:\n  en: Store\n  nl: Bewaren\n",
+    );
+
+    const empty = await findDuplicateTranslations(projectConfig, datasource, {
+      locale: "en-US",
+    });
+
+    expect(empty.summary).toEqual({
+      sets: 1,
+      locales: 0,
+      duplicateValues: 0,
+      duplicateMessageKeys: 0,
+    });
+    expect(empty.results).toEqual([{ set: null, locales: [] }]);
+  });
+
+  it("scans sets independently by default and narrows to one set with --set", async function () {
+    const root = await createSetsProject();
+    const { projectConfig, datasource } = getDatasource(root);
+
+    const allSets = await findDuplicateTranslations(projectConfig, datasource);
+
+    expect(allSets.summary).toEqual({
+      sets: 2,
+      locales: 2,
+      duplicateValues: 2,
+      duplicateMessageKeys: 4,
+    });
+    expect(allSets.results.map((entry) => entry.set)).toEqual(["dev", "production"]);
+    expect(allSets.results[0].locales[0].duplicateValues[0].value).toEqual("Save dev");
+    expect(allSets.results[1].locales[0].duplicateValues[0].value).toEqual("Save production");
+
+    const production = await findDuplicateTranslations(projectConfig, datasource, {
+      set: "production",
+    });
+
+    expect(production.summary).toEqual({
+      sets: 1,
+      locales: 1,
+      duplicateValues: 1,
+      duplicateMessageKeys: 2,
+    });
+    expect(production.results.map((entry) => entry.set)).toEqual(["production"]);
+  });
+});
+
+describe("findDuplicatesPlugin", function () {
+  it("prints readable duplicate output", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await findDuplicatesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { locale: "en-US" },
+    });
+
+    const rawOutput = logSpy.mock.calls.map((call) => call.join(" ")).join("\n");
+    const output = stripAnsi(rawOutput);
+
+    expect(rawOutput).toContain("\x1b[1m");
+    expect(rawOutput).toContain("\x1b[33m");
+    expect(output).toContain("Finding duplicate Messagevisor translations");
+    expect(output).toContain("Duplicate values:  1");
+    expect(output).toContain('Locale "en-US"');
+    expect(output).toContain('"Save"');
+    expect(output).toContain("- actions.save (from en)");
+    expect(output).toContain("- common.save");
+    expect(output).toContain("Duplicate scan complete: 1 value(s) across 1 locale(s).");
+
+    logSpy.mockRestore();
+  });
+
+  it("prints JSON output and respects --pretty", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => undefined);
+
+    await findDuplicatesPlugin.handler({
+      projectConfig,
+      datasource,
+      parsed: { locale: "en-US", json: true, pretty: true },
+    });
+
+    const output = logSpy.mock.calls[0][0];
+
+    expect(output).toContain('\n  "summary":');
+    expect(JSON.parse(output).results[0].locales[0].duplicateValues[0]).toEqual({
+      value: "Save",
+      messageKeys: ["actions.save", "common.save"],
+      sources: [
+        { messageKey: "actions.save", locale: "en" },
+        { messageKey: "common.save", locale: "en-US" },
+      ],
+    });
+
+    logSpy.mockRestore();
+  });
+
+  it("returns false and prints a friendly message for expected errors", async function () {
+    const root = await createProject();
+    const { projectConfig, datasource } = getDatasource(root);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await expect(
+      findDuplicatesPlugin.handler({
+        projectConfig,
+        datasource,
+        parsed: { set: "dev" },
+      }),
+    ).resolves.toEqual(false);
+
+    expect(errorSpy).toHaveBeenCalledWith(
+      "Option --set can only be used when project sets are enabled.",
+    );
+
+    errorSpy.mockRestore();
+  });
+});

package/src/find-duplicates/index.ts

@@ -0,0 +1,314 @@
+import type { Locale, Message, Translation } from "@messagevisor/types";
+
+import type { ProjectConfig } from "../config";
+import type { Datasource } from "../datasource";
+import { MessagevisorCLIError, printMessagevisorCLIError } from "../error";
+import { getProjectSetExecutions } from "../sets";
+import { CLI_FORMAT_BOLD, CLI_FORMAT_CYAN, CLI_FORMAT_GREEN, colorize } from "../tester/cliFormat";
+
+export interface FindDuplicatesOptions {
+  set?: string;
+  locale?: string;
+}
+
+export interface DuplicateTranslationSource {
+  messageKey: string;
+  locale: string;
+}
+
+export interface DuplicateTranslationValue {
+  value: string;
+  messageKeys: string[];
+  sources: DuplicateTranslationSource[];
+}
+
+export interface DuplicateTranslationLocaleResult {
+  locale: string;
+  duplicateValues: DuplicateTranslationValue[];
+}
+
+export interface DuplicateTranslationSetResult {
+  set: string | null;
+  locales: DuplicateTranslationLocaleResult[];
+}
+
+export interface FindDuplicatesResult {
+  summary: {
+    sets: number;
+    locales: number;
+    duplicateValues: number;
+    duplicateMessageKeys: number;
+  };
+  results: DuplicateTranslationSetResult[];
+}
+
+interface ResolvedTranslation {
+  value: string;
+  sourceLocale: string;
+}
+
+async function readAll<T>(
+  keys: string[],
+  read: (key: string) => Promise<T>,
+): Promise<Record<string, T>> {
+  const entries = await Promise.all(keys.map(async (key) => [key, await read(key)] as const));
+  return Object.fromEntries(entries);
+}
+
+function resolveLocaleChain(localeKey: string, locales: Record<string, Locale>) {
+  const chain: string[] = [];
+  const seen = new Set<string>();
+  let currentKey: string | undefined = localeKey;
+
+  while (currentKey && !seen.has(currentKey)) {
+    seen.add(currentKey);
+    chain.unshift(currentKey);
+    currentKey = locales[currentKey]?.inheritTranslationsFrom;
+  }
+
+  return chain;
+}
+
+function resolveTranslation(
+  translations: Record<string, Translation> | undefined,
+  localeKey: string,
+  locales: Record<string, Locale>,
+): ResolvedTranslation | undefined {
+  const candidates = resolveLocaleChain(localeKey, locales).reverse();
+
+  for (const candidate of candidates) {
+    if (typeof translations?.[candidate] !== "undefined") {
+      return {
+        value: translations[candidate],
+        sourceLocale: candidate,
+      };
+    }
+  }
+}
+
+function isAvailable(message: Message) {
+  return !message.archived;
+}
+
+function hasContent(value: string) {
+  return value.trim().length > 0;
+}
+
+function toDuplicateLocaleResult(
+  locale: string,
+  messages: Record<string, Message>,
+  locales: Record<string, Locale>,
+): DuplicateTranslationLocaleResult {
+  const entriesByValue = new Map<string, DuplicateTranslationSource[]>();
+
+  for (const [messageKey, message] of Object.entries(messages)) {
+    if (!isAvailable(message)) {
+      continue;
+    }
+
+    const resolved = resolveTranslation(message.translations, locale, locales);
+
+    if (!resolved || !hasContent(resolved.value)) {
+      continue;
+    }
+
+    const existing = entriesByValue.get(resolved.value) || [];
+    existing.push({
+      messageKey,
+      locale: resolved.sourceLocale,
+    });
+    entriesByValue.set(resolved.value, existing);
+  }
+
+  const duplicateValues = Array.from(entriesByValue.entries())
+    .filter(([, entries]) => entries.length > 1)
+    .map(([value, sources]) => ({
+      value,
+      messageKeys: sources.map((source) => source.messageKey).sort(),
+      sources: sources
+        .slice()
+        .sort(
+          (a, b) => a.messageKey.localeCompare(b.messageKey) || a.locale.localeCompare(b.locale),
+        ),
+    }))
+    .sort((a, b) => a.value.localeCompare(b.value));
+
+  return {
+    locale,
+    duplicateValues,
+  };
+}
+
+async function findDuplicatesInDatasource(
+  datasource: Datasource,
+  set: string | null,
+  options: Pick<FindDuplicatesOptions, "locale">,
+): Promise<DuplicateTranslationSetResult> {
+  const [localeKeys, messageKeys] = await Promise.all([
+    datasource.listLocales(),
+    datasource.listMessages(),
+  ]);
+
+  if (options.locale && !localeKeys.includes(options.locale)) {
+    throw new MessagevisorCLIError(
+      `Unknown locale "${options.locale}". Available locales: ${localeKeys.join(", ") || "none"}.`,
+    );
+  }
+
+  const selectedLocales = options.locale ? [options.locale] : localeKeys;
+  const [locales, messages] = await Promise.all([
+    readAll<Locale>(localeKeys, (key) => datasource.readLocale(key)),
+    readAll<Message>(messageKeys, (key) => datasource.readMessage(key)),
+  ]);
+
+  return {
+    set,
+    locales: selectedLocales
+      .map((locale) => toDuplicateLocaleResult(locale, messages, locales))
+      .filter((result) => result.duplicateValues.length > 0),
+  };
+}
+
+function summarize(results: DuplicateTranslationSetResult[]): FindDuplicatesResult["summary"] {
+  const duplicateValues = results.reduce(
+    (sum, result) =>
+      sum +
+      result.locales.reduce((localeSum, locale) => localeSum + locale.duplicateValues.length, 0),
+    0,
+  );
+  const duplicateMessageKeys = results.reduce(
+    (sum, result) =>
+      sum +
+      result.locales.reduce(
+        (localeSum, locale) =>
+          localeSum +
+          locale.duplicateValues.reduce(
+            (valueSum, duplicate) => valueSum + duplicate.messageKeys.length,
+            0,
+          ),
+        0,
+      ),
+    0,
+  );
+
+  return {
+    sets: results.length,
+    locales: results.reduce((sum, result) => sum + result.locales.length, 0),
+    duplicateValues,
+    duplicateMessageKeys,
+  };
+}
+
+export async function findDuplicateTranslations(
+  projectConfig: ProjectConfig,
+  datasource: Datasource,
+  options: FindDuplicatesOptions = {},
+): Promise<FindDuplicatesResult> {
+  if (!projectConfig.sets && options.set) {
+    throw new MessagevisorCLIError("Option --set can only be used when project sets are enabled.");
+  }
+
+  const executions = await getProjectSetExecutions(projectConfig, datasource, options.set);
+  const results = await Promise.all(
+    executions.map((execution) =>
+      findDuplicatesInDatasource(
+        execution.datasource,
+        projectConfig.sets ? execution.set : null,
+        options,
+      ),
+    ),
+  );
+
+  return {
+    summary: summarize(results),
+    results,
+  };
+}
+
+function printDuplicateSources(locale: string, duplicate: DuplicateTranslationValue) {
+  for (const source of duplicate.sources) {
+    const inheritedSuffix = source.locale !== locale ? colorize(` (from ${source.locale})`, 2) : "";
+    console.log(`    - ${colorize(source.messageKey, 1)}${inheritedSuffix}`);
+  }
+}
+
+function printPlainResult(result: FindDuplicatesResult, hasSets: boolean) {
+  console.log("");
+  console.log(CLI_FORMAT_BOLD, "Finding duplicate Messagevisor translations");
+  console.log(`  Sets:              ${result.summary.sets}`);
+  console.log(`  Locales:           ${result.summary.locales}`);
+  console.log(`  Duplicate values:  ${result.summary.duplicateValues}`);
+  console.log(`  Message key hits:  ${result.summary.duplicateMessageKeys}`);
+  console.log("");
+
+  if (result.summary.duplicateValues === 0) {
+    console.log(CLI_FORMAT_GREEN, "No duplicate translations found.");
+    return;
+  }
+
+  for (const setResult of result.results) {
+    if (setResult.locales.length === 0) {
+      continue;
+    }
+
+    if (hasSets) {
+      console.log(CLI_FORMAT_BOLD, `Set "${setResult.set}"`);
+    }
+
+    for (const localeResult of setResult.locales) {
+      console.log(CLI_FORMAT_CYAN, `Locale "${localeResult.locale}"`);
+
+      for (const duplicate of localeResult.duplicateValues) {
+        console.log(`  ${colorize(JSON.stringify(duplicate.value), 33)}`);
+        printDuplicateSources(localeResult.locale, duplicate);
+      }
+
+      console.log("");
+    }
+  }
+
+  console.log(
+    CLI_FORMAT_GREEN,
+    `Duplicate scan complete: ${result.summary.duplicateValues} value(s) across ${result.summary.locales} locale(s).`,
+  );
+}
+
+export const findDuplicatesPlugin = {
+  command: "find-duplicates",
+  handler: async ({ projectConfig, datasource, parsed }: any) => {
+    try {
+      const result = await findDuplicateTranslations(projectConfig, datasource, {
+        set: parsed.set,
+        locale: parsed.locale,
+      });
+
+      if (parsed.json) {
+        console.log(parsed.pretty ? JSON.stringify(result, null, 2) : JSON.stringify(result));
+        return;
+      }
+
+      printPlainResult(result, projectConfig.sets);
+    } catch (error) {
+      if (printMessagevisorCLIError(error)) {
+        return false;
+      }
+
+      throw error;
+    }
+  },
+  examples: [
+    { command: "find-duplicates", description: "find duplicate translation values" },
+    {
+      command: "find-duplicates --locale=en-US",
+      description: "find duplicates for one locale",
+    },
+    {
+      command: "find-duplicates --set=staging",
+      description: "find duplicates in one set",
+    },
+    {
+      command: "find-duplicates --locale=en-US --json --pretty",
+      description: "print duplicate translations as JSON",
+    },
+  ],
+};

package/src/generate-code/index.ts

@@ -0,0 +1,92 @@
+import * as fs from "fs";
+import * as path from "path";
+
+import type { Plugin } from "../cli";
+import type { ProjectConfig } from "../config";
+import type { Datasource } from "../datasource";
+import { MessagevisorCLIError, printMessagevisorCLIError } from "../error";
+import {
+  generateTypeScriptCodeForProject,
+  type TypeScriptCodeGenerationOptions,
+} from "./typescript";
+
+export const ALLOWED_LANGUAGES_FOR_CODE_GENERATION = ["typescript"];
+
+export interface GenerateCodeOptions extends TypeScriptCodeGenerationOptions {
+  language?: string;
+  outDir?: string;
+}
+
+export async function generateCodeForProject(
+  projectConfig: ProjectConfig,
+  datasource: Datasource,
+  rootDirectoryPath: string,
+  options: GenerateCodeOptions,
+) {
+  if (!options.language) {
+    throw new MessagevisorCLIError("Option --language is required.");
+  }
+
+  if (!options.outDir) {
+    throw new MessagevisorCLIError("Option --out-dir is required.");
+  }
+
+  if (ALLOWED_LANGUAGES_FOR_CODE_GENERATION.indexOf(options.language) === -1) {
+    throw new MessagevisorCLIError(
+      `Language ${options.language} is not supported. Supported languages: ${ALLOWED_LANGUAGES_FOR_CODE_GENERATION.join(", ")}.`,
+    );
+  }
+
+  const outDir = path.isAbsolute(options.outDir)
+    ? options.outDir
+    : path.join(rootDirectoryPath, options.outDir);
+
+  await fs.promises.mkdir(outDir, { recursive: true });
+
+  const result = await generateTypeScriptCodeForProject(projectConfig, datasource, outDir, {
+    set: options.set,
+    target: options.target,
+    includeMessages: options.includeMessages,
+    excludeMessages: options.excludeMessages,
+    react: options.react,
+  });
+
+  console.log(
+    `Generated ${result.files.length} TypeScript file(s) for ${result.messageKeys.length} message key(s) in ${outDir}`,
+  );
+
+  return result;
+}
+
+export const generateCodePlugin: Plugin = {
+  command: "generate-code",
+  handler: async ({ rootDirectoryPath, projectConfig, datasource, parsed }) => {
+    try {
+      await generateCodeForProject(projectConfig, datasource, rootDirectoryPath, {
+        language: parsed.language,
+        outDir: parsed.outDir,
+        set: parsed.set,
+        target: parsed.target,
+        includeMessages: parsed.includeMessages,
+        excludeMessages: parsed.excludeMessages,
+        react: parsed.react,
+      });
+    } catch (error) {
+      if (printMessagevisorCLIError(error)) {
+        return false;
+      }
+
+      throw error;
+    }
+  },
+  examples: [
+    {
+      command: "generate-code --language typescript --out-dir src/generated",
+      description: "Generate TypeScript message key helpers",
+    },
+    {
+      command: "generate-code --language typescript --out-dir src/generated --react",
+      description: "Generate TypeScript and React message key helpers",
+    },
+  ],
+};